Changeset View
Changeset View
Standalone View
Standalone View
docs/uri-scheme-browse.rst
| Show All 33 Lines | |||||
| For instance, instead of having to specify a (root) revision by **sha1_git**, users might want to | For instance, instead of having to specify a (root) revision by **sha1_git**, users might want to | ||||
| specify a place and a time. In Software Heritage a "place" is an origin, with an optional | specify a place and a time. In Software Heritage a "place" is an origin, with an optional | ||||
| branch name; a "time" is a timestamp at which some place has been observed by | branch name; a "time" is a timestamp at which some place has been observed by | ||||
| Software Heritage crawlers. | Software Heritage crawlers. | ||||
| Wherever a revision context is expected in a path (i.e., a | Wherever a revision context is expected in a path (i.e., a | ||||
| **/browse/revision/(sha1_git)/** path fragment) we can put in its stead a path fragment | **/browse/revision/(sha1_git)/** path fragment) we can put in its stead a path fragment | ||||
| of the form **/origin/(origin_type)/url/(origin_url)/[/visit/(timestamp)/][?branch=(branch)]**. | of the form **/origin/(origin_url)/[/visit/(timestamp)/][?branch=(branch)]**. | ||||
| Such a fragment is resolved, internally by the archive, to a revision **sha1_git** as follows: | Such a fragment is resolved, internally by the archive, to a revision **sha1_git** as follows: | ||||
| - if **timestamp** is absent: look for the most recent crawl of origin | - if **timestamp** is absent: look for the most recent crawl of origin | ||||
| identified by **origin_type** and **origin_url** | identified by **origin_url** | ||||
| - if **timestamp** is given: look for the closest crawl of origin identified | - if **timestamp** is given: look for the closest crawl of origin identified | ||||
| by **origin_type** and **origin_url** from timestamp **timestamp** | by **origin_url** from timestamp **timestamp** | ||||
| - if **branch** is given as a query parameter: look for the branch **branch** | - if **branch** is given as a query parameter: look for the branch **branch** | ||||
| - if **branch** is absent: look for branch "HEAD" or "master" | - if **branch** is absent: look for branch "HEAD" or "master" | ||||
| - return the revision **sha1_git** pointed by the chosen branch | - return the revision **sha1_git** pointed by the chosen branch | ||||
| The already mentioned URLs for revision contexts can therefore be alternatively | The already mentioned URLs for revision contexts can therefore be alternatively | ||||
| specified by users as: | specified by users as: | ||||
| * :http:get:`/browse/origin/[(origin_type)/url/](origin_url)/directory/[(path)/]` | * :http:get:`/browse/origin/(origin_url)/directory/[(path)/]` | ||||
| * :http:get:`/browse/origin/[(origin_type)/url/](origin_url)/visit/(timestamp)/directory/[(path)/]` | * :http:get:`/browse/origin/(origin_url)/visit/(timestamp)/directory/[(path)/]` | ||||
| * :http:get:`/browse/origin/[(origin_type)/url/](origin_url)/content/(path)/` | * :http:get:`/browse/origin/(origin_url)/content/(path)/` | ||||
| * :http:get:`/browse/origin/[(origin_type)/url/](origin_url)/visit/(timestamp)/content/(path)/` | * :http:get:`/browse/origin/(origin_url)/visit/(timestamp)/content/(path)/` | ||||
| * :http:get:`/browse/origin/[(origin_type)/url/](origin_url)/log/` | * :http:get:`/browse/origin/(origin_url)/log/` | ||||
| * :http:get:`/browse/origin/[(origin_type)/url/](origin_url)/visit/(timestamp)/log/` | * :http:get:`/browse/origin/(origin_url)/visit/(timestamp)/log/` | ||||
| Typing: | Typing: | ||||
| - **origin_type** corresponds to the type of the archived origin: | |||||
| ``git``, ``svn``,``hg``, ``deb``, ``pypi``, ``ftp`` or ``deposit`` | |||||
| - **origin_url** corresponds to the URL the origin was crawled from, | - **origin_url** corresponds to the URL the origin was crawled from, | ||||
| for instance https://github.com/(user)/(repo)/ | for instance https://github.com/(user)/(repo)/ | ||||
| - **branch** name is given as per the corresponding VCS (e.g., Git) as | - **branch** name is given as per the corresponding VCS (e.g., Git) as | ||||
| a query parameter to the requested URL. | a query parameter to the requested URL. | ||||
| - **timestamp** is given in a format as liberal as possible, to uphold the | - **timestamp** is given in a format as liberal as possible, to uphold the | ||||
| principle of least surprise. At the very minimum it is possible to | principle of least surprise. At the very minimum it is possible to | ||||
| Show All 24 Lines | |||||