diff --git a/docs/index.rst b/docs/index.rst
index 798d3aad..f747214f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,19 +1,19 @@
Software Heritage Web Applications - Development Documentation
===============================================================
.. toctree::
- :maxdepth: 2
+ :maxdepth: 3
:caption: Contents:
dev-info.md
uri-scheme-api
uri-scheme-browse
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
diff --git a/docs/uri-scheme-api-content.rst b/docs/uri-scheme-api-content.rst
index 423080c9..859a661c 100644
--- a/docs/uri-scheme-api-content.rst
+++ b/docs/uri-scheme-api-content.rst
@@ -1,275 +1,338 @@
Content
-------
+.. http:get:: /api/1/content/known/(sha1)[,(sha1), ...,(sha1)]/
+
+ Check whether some content(s) (aka "blob(s)") is present in the SWH archive
+ based on its *sha1* checksum.
+
+ :param string sha1: hexadecimal representation of the *sha1* checksum value
+ of the content to check existence. Multiple values can be provided separated
+ by ','.
+
+ :reqheader Accept: the requested response content type,
+ either *application/json* (default) or *application/yaml*
+ :resheader Content-Type: this depends on :http:header:`Accept` header of request
+
+ :>json array search_res: array holding the search result for each provided *sha1*
+ :>json object search_stats: some statistics regarding the number of *sha1* provided
+ and the percentage of those found in the SWH archive
+
+ **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options`
+
+ :statuscode 200: no error
+ :statuscode 400: an invalid *sha1* has been provided
+
+ **Request:**
+
+ .. parsed-literal::
+
+ $ curl -i :swh_web_api:`content/known/dc2830a9e72f23c1dfebef4413003221baa5fb62,0c3f19cb47ebfbe643fb19fa94c874d18fa62d12/`
+
+ **Response:**
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "search_res": [
+ {
+ "found": true,
+ "sha1": "dc2830a9e72f23c1dfebef4413003221baa5fb62"
+ },
+ {
+ "found": true,
+ "sha1": "0c3f19cb47ebfbe643fb19fa94c874d18fa62d12"
+ }
+ ],
+ "search_stats": {
+ "nbfiles": 2,
+ "pct": 100.0
+ }
+ }
+
+
.. http:get:: /api/1/content/[(hash_type):](hash)/
Get information about a content (aka a "blob") object.
In the SWH archive, a content object is identified based on checksum
values computed using various hashing algorithms.
:param string hash_type: optional parameter specifying which hashing algorithm has been used
to compute the content checksum. It can be either *sha1*, *sha1_git*, *sha256*
or *blake2s256*. If that parameter is not provided, it is assumed that the
hashing algorithm used is *sha1*.
:param string hash: hexadecimal representation of the checksum value computed with
the specified hashing algorithm.
:reqheader Accept: the requested response content type,
either *application/json* (default) or *application/yaml*
:resheader Content-Type: this depends on :http:header:`Accept` header of request
:>json object checksums: object holding the computed checksum values for the requested content
:>json string data_url: link to :http:get:`/api/1/content/[(hash_type):](hash)/raw/`
for downloading the content raw bytes
:>json string filetype_url: link to :http:get:`/api/1/content/[(hash_type):](hash)/filetype/`
for getting information about the content MIME type
:>json string language_url: link to :http:get:`/api/1/content/[(hash_type):](hash)/language/`
for getting information about the programming language used in the content
:>json number length: length of the content in bytes
:>json string license_url: link to :http:get:`/api/1/content/[(hash_type):](hash)/license/`
for getting information about the license of the content
+ **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options`
+
:statuscode 200: no error
:statuscode 400: an invalid *hash_type* or *hash* has been provided
:statuscode 404: requested content can not be found in the SWH archive
- **Request**:
+ **Request:**
.. parsed-literal::
$ curl -i :swh_web_api:`content/sha1_git:fe95a46679d128ff167b7c55df5d02356c5a1ae1/`
- **Response**:
+ **Response:**
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"checksums": {
"blake2s256": "791e07fcea240ade6dccd0a9309141673c31242cae9c237cf3855e151abc78e9",
"sha1": "dc2830a9e72f23c1dfebef4413003221baa5fb62",
"sha1_git": "fe95a46679d128ff167b7c55df5d02356c5a1ae1",
"sha256": "b5c7fe0536f44ef60c8780b6065d30bca74a5cd06d78a4a71ba1ad064770f0c9"
},
"data_url": "/api/1/content/sha1_git:fe95a46679d128ff167b7c55df5d02356c5a1ae1/raw/",
"filetype_url": "/api/1/content/sha1_git:fe95a46679d128ff167b7c55df5d02356c5a1ae1/filetype/",
"language_url": "/api/1/content/sha1_git:fe95a46679d128ff167b7c55df5d02356c5a1ae1/language/",
"length": 151810,
"license_url": "/api/1/content/sha1_git:fe95a46679d128ff167b7c55df5d02356c5a1ae1/license/",
"status": "visible"
}
.. http:get:: /api/1/content/[(hash_type):](hash)/raw/
Get the raw content of a content object (aka a "blob"), as a byte sequence.
:param string hash_type: optional parameter specifying which hashing algorithm has been used
to compute the content checksum. It can be either *sha1*, *sha1_git*, *sha256*
or *blake2s256*. If that parameter is not provided, it is assumed that the
hashing algorithm used is *sha1*.
:param string hash: hexadecimal representation of the checksum value computed with
the specified hashing algorithm.
:query string filename: if provided, the downloaded content will get that filename
:resheader Content-Type: application/octet-stream
+ **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options`
+
:statuscode 200: no error
:statuscode 400: an invalid *hash_type* or *hash* has been provided
:statuscode 404: requested content can not be found in the SWH archive
- **Request**:
+ **Request:**
.. parsed-literal::
$ curl -i :swh_web_api:`content/sha1:dc2830a9e72f23c1dfebef4413003221baa5fb62/raw/`
- **Response**:
+ **Response:**
.. sourcecode:: http
HTTP/1.1 200 OK
Content-disposition: attachment; filename=content_sha1_dc2830a9e72f23c1dfebef4413003221baa5fb62_raw
Content-Type: application/octet-stream
/* 'dir', 'vdir' and 'ls' directory listing programs for GNU.
Copyright (C) 1985-2015 Free Software Foundation, Inc.
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see . */
...
.. http:get:: /api/1/content/[(hash_type):](hash)/filetype/
Get information about the detected MIME type of a content object.
:param string hash_type: optional parameter specifying which hashing algorithm has been used
to compute the content checksum. It can be either *sha1*, *sha1_git*, *sha256*
or *blake2s256*. If that parameter is not provided, it is assumed that the
hashing algorithm used is *sha1*.
:param string hash: hexadecimal representation of the checksum value computed with
the specified hashing algorithm.
:>json object content_url: link to :http:get:`/api/1/content/[(hash_type):](hash)/` for
getting information about the content
:>json string encoding: the detected content encoding
:>json string id: the *sha1* identifier of the content
:>json string mimetype: the detected MIME type of the content
:>json object tool: information about the tool used to detect the content filetype
:reqheader Accept: the requested response content type,
either *application/json* (default) or *application/yaml*
:resheader Content-Type: this depends on :http:header:`Accept` header of request
+ **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options`
+
:statuscode 200: no error
:statuscode 400: an invalid *hash_type* or *hash* has been provided
:statuscode 404: requested content can not be found in the SWH archive
- **Request**:
+ **Request:**
.. parsed-literal::
$ curl -i :swh_web_api:`content/sha1:dc2830a9e72f23c1dfebef4413003221baa5fb62/filetype/`
- **Response**:
+ **Response:**
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"content_url": "/api/1/content/sha1:dc2830a9e72f23c1dfebef4413003221baa5fb62/",
"encoding": "us-ascii",
"id": "dc2830a9e72f23c1dfebef4413003221baa5fb62",
"mimetype": "text/x-c",
"tool": {
"configuration": {
"command_line": "file --mime "
},
"id": 7,
"name": "file",
"version": "5.22"
}
}
.. http:get:: /api/1/content/[(hash_type):](hash)/language/
Get information about the programming language used in a content object.
:param string hash_type: optional parameter specifying which hashing algorithm has been used
to compute the content checksum. It can be either *sha1*, *sha1_git*, *sha256*
or *blake2s256*. If that parameter is not provided, it is assumed that the
hashing algorithm used is *sha1*.
:param string hash: hexadecimal representation of the checksum value computed with
the specified hashing algorithm.
:>json object content_url: link to :http:get:`/api/1/content/[(hash_type):](hash)/` for
getting information about the content
:>json string id: the *sha1* identifier of the content
:>json string lang: the detected programming language if any
:>json object tool: information about the tool used to detect the programming language
:reqheader Accept: the requested response content type,
either *application/json* (default) or *application/yaml*
:resheader Content-Type: this depends on :http:header:`Accept` header of request
+ **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options`
+
:statuscode 200: no error
:statuscode 400: an invalid *hash_type* or *hash* has been provided
:statuscode 404: requested content can not be found in the SWH archive
- **Request**:
+ **Request:**
.. parsed-literal::
$ curl -i :swh_web_api:`content/sha1:dc2830a9e72f23c1dfebef4413003221baa5fb62/language/`
- **Response**:
+ **Response:**
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"content_url": "/api/1/content/sha1:dc2830a9e72f23c1dfebef4413003221baa5fb62/",
"id": "dc2830a9e72f23c1dfebef4413003221baa5fb62",
"lang": "c",
"tool": {
"configuration": {
"debian-package": "python3-pygments",
"max_content_size": 10240,
"type": "library"
},
"id": 8,
"name": "pygments",
"version": "2.0.1+dfsg-1.1+deb8u1"
}
}
.. http:get:: /api/1/content/[(hash_type):](hash)/license/
Get information about the license of a content object.
:param string hash_type: optional parameter specifying which hashing algorithm has been used
to compute the content checksum. It can be either *sha1*, *sha1_git*, *sha256*
or *blake2s256*. If that parameter is not provided, it is assumed that the
hashing algorithm used is *sha1*.
:param string hash: hexadecimal representation of the checksum value computed with
the specified hashing algorithm.
:>json object content_url: link to :http:get:`/api/1/content/[(hash_type):](hash)/` for
getting information about the content
:>json string id: the *sha1* identifier of the content
:>json array licenses: array of strings containing the detected license names if any
:>json object tool: information about the tool used to detect the license
:reqheader Accept: the requested response content type,
either *application/json* (default) or *application/yaml*
:resheader Content-Type: this depends on :http:header:`Accept` header of request
+ **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options`
+
:statuscode 200: no error
:statuscode 400: an invalid *hash_type* or *hash* has been provided
:statuscode 404: requested content can not be found in the SWH archive
- **Request**:
+ **Request:**
.. parsed-literal::
$ curl -i :swh_web_api:`content/sha1:dc2830a9e72f23c1dfebef4413003221baa5fb62/license/`
- **Response**:
+ **Response:**
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"content_url": "/api/1/content/sha1:dc2830a9e72f23c1dfebef4413003221baa5fb62/",
"id": "dc2830a9e72f23c1dfebef4413003221baa5fb62",
"licenses": [
"GPL-3.0+"
],
"tool": {
"configuration": {
"command_line": "nomossa "
},
"id": 1,
"name": "nomos",
"version": "3.1.0rc2-31-ga2cbb8c"
}
}
diff --git a/docs/uri-scheme-api-directory.rst b/docs/uri-scheme-api-directory.rst
index 46d48676..78f46c18 100644
--- a/docs/uri-scheme-api-directory.rst
+++ b/docs/uri-scheme-api-directory.rst
@@ -1,85 +1,87 @@
Directory
---------
.. http:get:: /api/1/directory/(sha1_git)/[(path)/]
Get information about directory objects.
Directories are identified by *sha1* checksums, compatible with Git directory identifiers.
See :func:`swh.model.identifiers.directory_identifier` in our data model module for details
about how they are computed.
When given only a directory identifier, this endpoint returns information about the directory itself,
returning its content (usually a list of directory entries). When given a directory identifier and a
path, this endpoint returns information about the directory entry pointed by the relative path,
starting path resolution from the given directory.
:param string sha1_git: hexadecimal representation of the directory *sha1_git* identifier
:param string path: optional parameter to get information about the directory entry
pointed by that relative path
:reqheader Accept: the requested response content type,
either *application/json* (default) or *application/yaml*
:resheader Content-Type: this depends on :http:header:`Accept` header of request
- :>json object checksums: object holding the computed checksum values for a directory entry
+ :>jsonarr object checksums: object holding the computed checksum values for a directory entry
(only for file entries)
- :>json string dir_id: *sha1_git* identifier of the requested directory
- :>json number length: length of a directory entry in bytes (only for file entries)
+ :>jsonarr string dir_id: *sha1_git* identifier of the requested directory
+ :>jsonarr number length: length of a directory entry in bytes (only for file entries)
for getting information about the content MIME type
- :>json string name: the directory entry name
- :>json number perms: permissions for the directory entry
- :>json string target: *sha1_git* identifier of the directory entry
- :>json string target_url: link to :http:get:`/api/1/content/[(hash_type):](hash)/`
+ :>jsonarr string name: the directory entry name
+ :>jsonarr number perms: permissions for the directory entry
+ :>jsonarr string target: *sha1_git* identifier of the directory entry
+ :>jsonarr string target_url: link to :http:get:`/api/1/content/[(hash_type):](hash)/`
or :http:get:`/api/1/directory/(sha1_git)/[(path)/]` depending on the directory entry type
- :>json string type: the type of the directory entry, can be either *dir*, *file* or *rev*
+ :>jsonarr string type: the type of the directory entry, can be either *dir*, *file* or *rev*
+
+ **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options`
:statuscode 200: no error
:statuscode 400: an invalid *hash_type* or *hash* has been provided
:statuscode 404: requested directory can not be found in the SWH archive
- **Request**:
+ **Request:**
.. parsed-literal::
$ curl -i :swh_web_api:`directory/977fc4b98c0e85816348cebd3b12026407c368b6/`
- **Response**:
+ **Response:**
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"checksums": {
"sha1": "e2d79ae437210941840f49966497cc348c7e817f",
"sha1_git": "58471109208922c9ee8c4b06135725f03ed16814",
"sha256": "2b7001f4819e898776b45b2fa3411018b7bc24e38afbb351691c32508eb2ae5d"
},
"dir_id": "977fc4b98c0e85816348cebd3b12026407c368b6",
"length": 582,
"name": ".bzrignore",
"perms": 33188,
"status": "visible",
"target": "58471109208922c9ee8c4b06135725f03ed16814",
"target_url": "/api/1/content/sha1_git:58471109208922c9ee8c4b06135725f03ed16814/",
"type": "file"
},
{
"checksums": {
"sha1": "f47aabb47381119cf72add7633bc095ca2cd030d",
"sha1_git": "2106da61725973b81a63a817ec6f245706af4353",
"sha256": "4f0475fac23bcd3ebceceecffb0d4facc5a413f6d9a0287185fb75638b8e9c69"
},
"dir_id": "977fc4b98c0e85816348cebd3b12026407c368b6",
"length": 453,
"name": ".codecov.yml",
"perms": 33188,
"status": "visible",
"target": "2106da61725973b81a63a817ec6f245706af4353",
"target_url": "/api/1/content/sha1_git:2106da61725973b81a63a817ec6f245706af4353/",
"type": "file"
},
]
diff --git a/docs/uri-scheme-api-origin.rst b/docs/uri-scheme-api-origin.rst
index 19d67226..e64c74bc 100644
--- a/docs/uri-scheme-api-origin.rst
+++ b/docs/uri-scheme-api-origin.rst
@@ -1,210 +1,210 @@
Origin
------
-Information
-^^^^^^^^^^^
-
.. http:get:: /api/1/origin/(origin_id)/
Get information about a software origin from its unique (but otherwise meaningless)
identifier.
:param int origin_id: a SWH origin identifier
:>json number id: the origin unique identifier
:>json string origin_visits_url: link to in order to get information about the SWH
visits for that origin
:>json string type: the type of software origin (*git*, *svn*, *hg*, *deb*, *ftp*, ...)
:>json string url: the origin canonical url
:reqheader Accept: the requested response content type,
either *application/json* (default) or *application/yaml*
:resheader Content-Type: this depends on :http:header:`Accept` header of request
:statuscode 200: no error
:statuscode 404: requested origin can not be found in the SWH archive
- **Request**:
+ **Request:**
.. parsed-literal::
$ curl -i :swh_web_api:`origin/1/`
- **Response**:
+ **Response:**
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 1,
"origin_visits_url": "/api/1/origin/1/visits/",
"type": "git",
"url": "https://github.com/hylang/hy"
}
.. http:get:: /api/1/origin/(origin_type)/url/(origin_url)/
Get information about a software origin from its type and canonical url.
:param string origin_type: the origin type (*git*, *svn*, *hg*, *deb*, *ftp*, ...)
:param string origin_url: the origin url
:>json number id: the origin unique identifier
:>json string origin_visits_url: link to in order to get information about the SWH
visits for that origin
:>json string type: the type of software origin (*git*, *svn*, *hg*, *deb*, *ftp*, ...)
:>json string url: the origin canonical url
:reqheader Accept: the requested response content type,
either *application/json* (default) or *application/yaml*
:resheader Content-Type: this depends on :http:header:`Accept` header of request
+ **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options`
+
:statuscode 200: no error
:statuscode 404: requested origin can not be found in the SWH archive
- **Request**:
+ **Request:**
.. parsed-literal::
$ curl -i :swh_web_api:`origin/git/url/https://github.com/python/cpython/`
- **Response**:
+ **Response:**
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 13706355,
"origin_visits_url": "/api/1/origin/13706355/visits/",
"type": "git",
"url": "https://github.com/python/cpython"
}
-Visits
-^^^^^^
-
.. http:get:: /api/1/origin/(origin_id)/visits/
Get information about all visits of a software origin.
:param int origin_id: a SWH origin identifier
:query int per_page: specify the number of visits to list, for pagination purposes
:query int last_visit: visit to start listing from, for pagination purposes
:reqheader Accept: the requested response content type,
either *application/json* (default) or *application/yaml*
:resheader Content-Type: this depends on :http:header:`Accept` header of request
:resheader Link: indicates that a subsequent result page is available and contains
the url pointing to it
- :>json string date: ISO representation of the visit date (in UTC)
- :>json number id: the unique identifier of the origin
- :>json string origin_visit_url: link to :http:get:`/api/1/origin/(origin_id)/visit/(visit_id)/`
+ :>jsonarr string date: ISO representation of the visit date (in UTC)
+ :>jsonarr number id: the unique identifier of the origin
+ :>jsonarr string origin_visit_url: link to :http:get:`/api/1/origin/(origin_id)/visit/(visit_id)/`
in order to get information about the visit
- :>json string status: status of the visit (either *full*, *partial* or *ongoing*)
- :>json number visit: the unique identifier of the visit
+ :>jsonarr string status: status of the visit (either *full*, *partial* or *ongoing*)
+ :>jsonarr number visit: the unique identifier of the visit
+
+ **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options`
:statuscode 200: no error
:statuscode 404: requested origin can not be found in the SWH archive
- **Request**:
+ **Request:**
.. parsed-literal::
$ curl -i :swh_web_api:`origin/1/visits/`
- **Response**:
+ **Response:**
.. sourcecode:: http
HTTP/1.1 200 OK
Link: ; rel="next"
Content-Type: application/json
[
{
"date": "2015-08-04T22:26:14.804009+00:00",
"origin": 1,
"origin_visit_url": "/api/1/origin/1/visit/1/",
"status": "full",
"visit": 1
},
{
"date": "2016-02-22T16:56:16.725068+00:00",
"metadata": {},
"origin": 1,
"origin_visit_url": "/api/1/origin/1/visit/2/",
"status": "full",
"visit": 2
},
]
.. http:get:: /api/1/origin/(origin_id)/visit/(visit_id)/
Get information about a specific visit of a software origin.
:param int origin_id: a SWH origin identifier
:param int visit_id: a visit identifier
:reqheader Accept: the requested response content type,
either *application/json* (default) or *application/yaml*
:resheader Content-Type: this depends on :http:header:`Accept` header of request
:>json string date: ISO representation of the visit date (in UTC)
:>json object occurrences: object containing all branches associated to the origin found
during the visit, for each of them the associated SWH revision id is given but also
a link to in order to get information about it
:>json number origin: the origin unique identifier
:>json string origin_url: link to get information about the origin
:>json string status: status of the visit (either *full*, *partial* or *ongoing*)
:>json number visit: the unique identifier of the visit
+ **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options`
+
:statuscode 200: no error
:statuscode 404: requested origin or visit can not be found in the SWH archive
- **Request**:
+ **Request:**
.. parsed-literal::
$ curl -i :swh_web_api:`origin/1500/visit/1/`
- **Response**:
+ **Response:**
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"date": "2015-08-23T17:48:46.800813+00:00",
"occurrences": {
"refs/heads/master": {
"target": "83c20a6a63a7ebc1a549d367bc07a61b926cecf3",
"target_type": "revision",
"target_url": "/api/1/revision/83c20a6a63a7ebc1a549d367bc07a61b926cecf3/"
},
"refs/heads/wiki": {
"target": "71f667aeb5d02562f2fa0941ad91df69c474ff3b",
"target_type": "revision",
"target_url": "/api/1/revision/71f667aeb5d02562f2fa0941ad91df69c474ff3b/"
},
"refs/tags/dpkt-1.6": {
"target": "7fc0fd582812af36064d1c85fe51e33227920479",
"target_type": "revision",
"target_url": "/api/1/revision/7fc0fd582812af36064d1c85fe51e33227920479/"
},
"refs/tags/dpkt-1.7": {
"target": "0c9dbfbc0974ec8ac1d8253aa1092366a03633a8",
"target_type": "revision",
"target_url": "/api/1/revision/0c9dbfbc0974ec8ac1d8253aa1092366a03633a8/"
}
},
"origin": 1500,
"origin_url": "/api/1/origin/1500/",
"status": "full",
"visit": 1
}
diff --git a/docs/uri-scheme-api-person.rst b/docs/uri-scheme-api-person.rst
new file mode 100644
index 00000000..535d2f11
--- /dev/null
+++ b/docs/uri-scheme-api-person.rst
@@ -0,0 +1,42 @@
+Person
+------
+
+.. http:get:: /api/1/person/(person_id)/
+
+ Get information about a person in the SWH archive.
+
+ :param int person_id: a SWH person identifier
+
+ :reqheader Accept: the requested response content type,
+ either *application/json* (default) or *application/yaml*
+ :resheader Content-Type: this depends on :http:header:`Accept` header of request
+
+ :>json string email: the email of the person
+ :>json string fullname: the full name of the person: combination of its name and email
+ :>json number id: the unique identifier of the person
+ :>json string name: the name of the person
+
+ **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options`
+
+ :statuscode 200: no error
+ :statuscode 404: requested person can not be found in the SWH archive
+
+ **Request:**
+
+ .. parsed-literal::
+
+ $ curl -i :swh_web_api:`person/8275/`
+
+ **Response:**
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "email": "torvalds@linux-foundation.org",
+ "fullname": "Linus Torvalds ",
+ "id": 8275,
+ "name": "Linus Torvalds"
+ }
diff --git a/docs/uri-scheme-api-release.rst b/docs/uri-scheme-api-release.rst
new file mode 100644
index 00000000..041da523
--- /dev/null
+++ b/docs/uri-scheme-api-release.rst
@@ -0,0 +1,64 @@
+Release
+-------
+
+.. http:get:: /api/1/release/(sha1_git)/
+
+ Get information about a release in the SWH archive.
+ Releases are identified by *sha1* checksums, compatible with Git tag identifiers.
+ See :func:`swh.model.identifiers.release_identifier` in our data model module for details
+ about how they are computed.
+
+ :param string sha1_git: hexadecimal representation of the release *sha1_git* identifier
+
+ :reqheader Accept: the requested response content type,
+ either *application/json* (default) or *application/yaml*
+ :resheader Content-Type: this depends on :http:header:`Accept` header of request
+
+ :>json object author: information about the author of the release
+ :>json string author_url: link to :http:get:`/api/1/person/(person_id)/` to get
+ information about the author of the release
+ :>json string date: ISO representation of the release date (in UTC)
+ :>json string id: the release unique identifier
+ :>json string message: the message associated to the release
+ :>json string name: the name of the release
+ :>json string target: the target identifier of the release
+ :>json string target_type: the type of the target, can be either *release*,
+ *revision*, *content*, *directory*
+ :>json string target_url: a link to the adequate api url based on the target type
+
+ **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options`
+
+ :statuscode 200: no error
+ :statuscode 400: an invalid *sha1_git* value has been provided
+ :statuscode 404: requested release can not be found in the SWH archive
+
+ **Request:**
+
+ .. parsed-literal::
+
+ $ curl -i :swh_web_api:`release/208f61cc7a5dbc9879ae6e5c2f95891e270f09ef/`
+
+ **Response:**
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "author": {
+ "email": "nad@python.org",
+ "fullname": "Ned Deily ",
+ "id": 8318464,
+ "name": "Ned Deily"
+ },
+ "author_url": "/api/1/person/8318464/",
+ "date": "2017-03-21T02:46:28-04:00",
+ "id": "208f61cc7a5dbc9879ae6e5c2f95891e270f09ef",
+ "message": "Tag v3.6.1\n-----BEGIN PGP SIGNATURE-----\n\niQIcBAABCgAGBQJY0MxgAAoJEC00fqaqZUIdkZ0QAJw9PR++cbpS3Pt8QrmgS+xG\nPxrZ1yPPNPNSfbmRLWOlHJ0nBzFPVXUWdrqnevmZVRghyrc78sjuBL8QczYsum22\n1B6X/63vX3dI9yj8FR5nldEYPBMOOD6ryObWoKMeqyQT3LhAqxIU/9oqAsbx+ZYw\nrXmRTuypenmZabq3yIv2hORMFgcS7JZFuVb181b0Cihji/7l+WRI9hkGO8POBeFq\ntfJ16beH8hbbDw/+MLpwJifsALWsQOqnWt2/C8tJeHtMX+FLuJflwcIwotv73E22\nulmpXNwTNxnK5l5/C9JC6kr5nN9VJatVpSpe6dftAmTy16O5OrADtePZYxOZ7S3X\n6ipOaiKl3s/2oykkmasxPeaVXllbWgd2UGqIBlAUxM6rVD/4DyVDUHqbDotQD8Kz\nZ8nSFxou1ZdRTSlC26ToGCNc+B6bqv9GTC1hph/ijJkhvXfIC9X1fc/uO1wrV+wB\ni2dxXKh1mQCXuogNAx6rv7gPaXbPgDHob7Tlvo5Ddhr7rQoAaMjceGfUMOTORSqO\nR4ssE6yyNASQtMjW+Y5WeVEgtX7ttGKBsgD0PsrZTCjnZfJkFtZGUyfkdwNzLK8v\nRBqi1r+tEuR5tpin4h+erdlVjeMhVMQZOhBYmxY2Ge70PMVrOz4KaFY1GD+aaxt7\n+PfOKUxMYGKvogv7gD/3\n=Peec\n-----END PGP SIGNATURE-----\n",
+ "name": "v3.6.1",
+ "synthetic": false,
+ "target": "69c0db5050f623e8895b72dfe970392b1f9a0e2e",
+ "target_type": "revision",
+ "target_url": "/api/1/revision/69c0db5050f623e8895b72dfe970392b1f9a0e2e/"
+ }
diff --git a/docs/uri-scheme-api-revision.rst b/docs/uri-scheme-api-revision.rst
new file mode 100644
index 00000000..b79a0ad5
--- /dev/null
+++ b/docs/uri-scheme-api-revision.rst
@@ -0,0 +1,477 @@
+Revision
+--------
+
+.. http:get:: /api/1/revision/(sha1_git)/
+
+ Get information about a revision in the SWH archive.
+ Releases are identified by *sha1* checksums, compatible with Git commit identifiers.
+ See :func:`swh.model.identifiers.revision_identifier` in our data model module for details
+ about how they are computed.
+
+ :param string sha1_git: hexadecimal representation of the revision *sha1_git* identifier
+
+ :reqheader Accept: the requested response content type,
+ either *application/json* (default) or *application/yaml*
+ :resheader Content-Type: this depends on :http:header:`Accept` header of request
+
+ :>json object author: information about the author of the revision
+ :>json string author_url: link to :http:get:`/api/1/person/(person_id)/` to get
+ information about the author of the revision
+ :>json object committer: information about the committer of the revision
+ :>json string committer_url: link to :http:get:`/api/1/person/(person_id)/` to get
+ information about the committer of the revision
+ :>json string committer_date: ISO representation of the commit date (in UTC)
+ :>json string date: ISO representation of the revision date (in UTC)
+ :>json string directory: the unique identifier that revision points to
+ :>json string directory_url: link to :http:get:`/api/1/directory/(sha1_git)/[(path)/]`
+ to get information about the directory associated to the revision
+ :>json string id: the revision unique identifier
+ :>json boolean merge: whether or not the revision corresponds to a merge commit
+ :>json string message: the message associated to the revision
+ :>json array parents: the parents of the revision, i.e. the previous revisions
+ that head directly to it, each entry of that array contains an unique parent
+ revision identifier but also a link to :http:get:`/api/1/revision/(sha1_git)/`
+ to get more informations about it
+ :>json string type: the type of the revision
+
+ **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options`
+
+ :statuscode 200: no error
+ :statuscode 400: an invalid *sha1_git* value has been provided
+ :statuscode 404: requested revision can not be found in the SWH archive
+
+ **Request:**
+
+ .. parsed-literal::
+
+ $ curl -i :swh_web_api:`revision/aafb16d69fd30ff58afdd69036a26047f3aebdc6/`
+
+ **Response:**
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "author": {
+ "email": "nicolas.dandrimont@crans.org",
+ "fullname": "Nicolas Dandrimont ",
+ "id": 42,
+ "name": "Nicolas Dandrimont"
+ },
+ "author_url": "/api/1/person/42/",
+ "committer": {
+ "email": "nicolas.dandrimont@crans.org",
+ "fullname": "Nicolas Dandrimont ",
+ "id": 42,
+ "name": "Nicolas Dandrimont"
+ },
+ "committer_date": "2014-08-18T18:18:25+02:00",
+ "committer_url": "/api/1/person/42/",
+ "date": "2014-08-18T18:18:25+02:00",
+ "directory": "9f2e5898e00a66e6ac11033959d7e05b1593353b",
+ "directory_url": "/api/1/directory/9f2e5898e00a66e6ac11033959d7e05b1593353b/",
+ "history_url": "/api/1/revision/aafb16d69fd30ff58afdd69036a26047f3aebdc6/log/",
+ "id": "aafb16d69fd30ff58afdd69036a26047f3aebdc6",
+ "merge": true,
+ "message": "Merge branch 'master' into pr/584\n",
+ "metadata": {},
+ "parents": [
+ {
+ "id": "26307d261279861c2d9c9eca3bb38519f951bea4",
+ "url": "/api/1/revision/26307d261279861c2d9c9eca3bb38519f951bea4/"
+ },
+ {
+ "id": "37fc9e08d0c4b71807a4f1ecb06112e78d91c283",
+ "url": "/api/1/revision/37fc9e08d0c4b71807a4f1ecb06112e78d91c283/"
+ }
+ ],
+ "synthetic": false,
+ "type": "git",
+ "url": "/api/1/revision/aafb16d69fd30ff58afdd69036a26047f3aebdc6/"
+ }
+
+.. http:get:: /api/1/revision/(sha1_git)/directory/[(path)/]
+
+ Get information about directory (entry) objects associated to revisions.
+ Each revision is associated to a single "root" directory.
+ This endpoint behaves like :http:get:`/api/1/directory/(sha1_git)/[(path)/]`,
+ but operates on the root directory associated to a given revision.
+
+ :param string sha1_git: hexadecimal representation of the revision *sha1_git* identifier
+ :param string path: optional parameter to get information about the directory entry
+ pointed by that relative path
+
+ :reqheader Accept: the requested response content type,
+ either *application/json* (default) or *application/yaml*
+ :resheader Content-Type: this depends on :http:header:`Accept` header of request
+
+ :>json array content: directory entries as returned by :http:get:`/api/1/directory/(sha1_git)/[(path)/]`
+ :>json string path: path of directory from the revision root one
+ :>json string revision: the unique revision identifier
+ :>json string type: the type of the directory
+
+ **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options`
+
+ :statuscode 200: no error
+ :statuscode 400: an invalid *sha1_git* value has been provided
+ :statuscode 404: requested revision can not be found in the SWH archive
+
+ **Request:**
+
+ .. parsed-literal::
+
+ $ curl -i :swh_web_api:`revision/f1b94134a4b879bc55c3dacdb496690c8ebdc03f/directory/`
+
+ **Response:**
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "content": [
+ {
+ "checksums": {
+ "sha1": "8de896f1d96b05c0cc3ea5233fdc232e90978c52",
+ "sha1_git": "f3a32d36d443cbb63ffb1bff743a890c181f482a",
+ "sha256": "a2ea552b2ed62b7f77cf47dae805d491fdb684ed3bbe297fcc68cbee755a5d10"
+ },
+ "dir_id": "778d9438465328f7c2ffe1c9d791f5b83a194c39",
+ "file_url": "/api/1/revision/f1b94134a4b879bc55c3dacdb496690c8ebdc03f/directory/.gitattributes/",
+ "length": 73,
+ "name": ".gitattributes",
+ "perms": 33188,
+ "status": "visible",
+ "target": "f3a32d36d443cbb63ffb1bff743a890c181f482a",
+ "target_url": "/api/1/content/sha1_git:f3a32d36d443cbb63ffb1bff743a890c181f482a/",
+ "type": "file"
+ },
+ {
+ "checksums": {
+ "sha1": "d493cd8f6de7611b9f0ef2b5cdf80d85adcc7917",
+ "sha1_git": "0b0ee9cc20323d3e4206eb3172f111bb211274e3",
+ "sha256": "4d6aaab1da470f61b92134d8b78a80376ae1ab74ec6a23a045e039065eafafd9"
+ },
+ "dir_id": "778d9438465328f7c2ffe1c9d791f5b83a194c39",
+ "file_url": "/api/1/revision/f1b94134a4b879bc55c3dacdb496690c8ebdc03f/directory/.gitignore/",
+ "length": 452,
+ "name": ".gitignore",
+ "perms": 33188,
+ "status": "visible",
+ "target": "0b0ee9cc20323d3e4206eb3172f111bb211274e3",
+ "target_url": "/api/1/content/sha1_git:0b0ee9cc20323d3e4206eb3172f111bb211274e3/",
+ "type": "file"
+ },
+ ],
+ "path": ".",
+ "revision": "ec72c666fb345ea5f21359b7bc063710ce558e39",
+ "type": "dir"
+ }
+
+.. http:get:: /api/1/revision/(sha1_git)[/prev/(prev_sha1s)]/log/
+
+ Get a list of all SWH revisions heading to a given one, i.e., show the commit log.
+
+ :param string sha1_git: hexadecimal representation of the revision *sha1_git* identifier
+ :param string prev_sha1s: optional parameter representing the navigation breadcrumbs
+ (descendant revisions previously visited). If multiple values, use / as delimiter.
+ If provided, revisions information will be added at the beginning of the returned list.
+ :query int per_page: number of elements in the returned list, for pagination purpose
+
+ :reqheader Accept: the requested response content type,
+ either *application/json* (default) or *application/yaml*
+ :resheader Content-Type: this depends on :http:header:`Accept` header of request
+ :resheader Link: indicates that a subsequent result page is available and contains
+ the url pointing to it
+
+ **Response JSON Array of Objects:**
+
+ array of revisions information as returned by :http:get:`/api/1/revision/(sha1_git)/`
+
+ **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options`
+
+ :statuscode 200: no error
+ :statuscode 400: an invalid *sha1_git* value has been provided
+ :statuscode 404: requested revision can not be found in the SWH archive
+
+ **Request:**
+
+ .. parsed-literal::
+
+ $ curl -i :swh_web_api:`revision/e1a315fa3fa734e2a6154ed7b5b9ae0eb8987aad/log/`
+
+ **Response:**
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ [
+ {
+ "author": {
+ "email": "uwog@bcba8976-2d24-0410-9c9c-aab3bd5fdfd6",
+ "fullname": "uwog ",
+ "id": 1234212,
+ "name": "uwog"
+ },
+ "author_url": "/api/1/person/1234212/",
+ "committer": {
+ "email": "uwog@bcba8976-2d24-0410-9c9c-aab3bd5fdfd6",
+ "fullname": "uwog ",
+ "id": 1234212,
+ "name": "uwog"
+ },
+ "committer_date": "2010-10-09T21:28:27+00:00",
+ "committer_url": "/api/1/person/1234212/",
+ "date": "2010-10-09T21:28:27+00:00",
+ "directory": "d8f68b3628ac6f32b6532688bea3574c378ba403",
+ "directory_url": "/api/1/directory/d8f68b3628ac6f32b6532688bea3574c378ba403/",
+ "history_url": "/api/1/revision/e1a315fa3fa734e2a6154ed7b5b9ae0eb8987aad/log/",
+ "id": "e1a315fa3fa734e2a6154ed7b5b9ae0eb8987aad",
+ "merge": false,
+ "message": "Restore binary compatibility again, 1.2.8 broke it (Fridrich Strba)\n\n\n\ngit-svn-id: http://svn.abisource.com/wv/trunk@29360 bcba8976-2d24-0410-9c9c-aab3bd5fdfd6\n",
+ "metadata": {},
+ "parents": [
+ {
+ "id": "e9a1e0e2805d01095bccea37ddabae5b3853bf74",
+ "url": "/api/1/revision/e9a1e0e2805d01095bccea37ddabae5b3853bf74/"
+ }
+ ],
+ "synthetic": false,
+ "type": "git",
+ "url": "/api/1/revision/e1a315fa3fa734e2a6154ed7b5b9ae0eb8987aad/"
+ },
+ {
+ "author": {
+ "email": "uwog@bcba8976-2d24-0410-9c9c-aab3bd5fdfd6",
+ "fullname": "uwog ",
+ "id": 1234212,
+ "name": "uwog"
+ },
+ "author_url": "/api/1/person/1234212/",
+ "committer": {
+ "email": "uwog@bcba8976-2d24-0410-9c9c-aab3bd5fdfd6",
+ "fullname": "uwog ",
+ "id": 1234212,
+ "name": "uwog"
+ },
+ "committer_date": "2010-10-09T10:42:20+00:00",
+ "committer_url": "/api/1/person/1234212/",
+ "date": "2010-10-09T10:42:20+00:00",
+ "directory": "00d3b261bb4e9253a84409cb7f69ed866fdbff5c",
+ "directory_url": "/api/1/directory/00d3b261bb4e9253a84409cb7f69ed866fdbff5c/",
+ "history_url": "/api/1/revision/e9a1e0e2805d01095bccea37ddabae5b3853bf74/log/",
+ "id": "e9a1e0e2805d01095bccea37ddabae5b3853bf74",
+ "merge": false,
+ "message": "Bump version\n\n\n\ngit-svn-id: http://svn.abisource.com/wv/trunk@29356 bcba8976-2d24-0410-9c9c-aab3bd5fdfd6\n",
+ "metadata": {},
+ "parents": [
+ {
+ "id": "73c589f19c060eb8af7c3fd3b4f50d44dd5218c8",
+ "url": "/api/1/revision/73c589f19c060eb8af7c3fd3b4f50d44dd5218c8/"
+ }
+ ],
+ "synthetic": false,
+ "type": "git",
+ "url": "/api/1/revision/e9a1e0e2805d01095bccea37ddabae5b3853bf74/"
+ },
+ ]
+
+
+.. http:get:: /api/1/revision/origin/(origin_id)/[branch/(branch_name)/][ts/(timestamp)/]
+
+ Get information about a revision, searching for it based on software origin,
+ branch name, and/or visit timestamp.
+
+ This endpoint behaves like :http:get:`/api/1/revision/(sha1_git)/`,
+ but operates on the revision that has been found at a given software origin,
+ close to a given point in time, pointed by a given branch.
+
+ :param int origin_id: a SWH origin identifier
+ :param string branch_name: optional parameter specifying a fully-qualified branch name
+ associated to the software origin, e.g., "refs/heads/master". Defaults to the master branch.
+ :param string timestamp: optional parameter specifying a timestamp close to which the revision
+ pointed by the given branch should be looked up. The timestamp can be expressed either
+ as an ISO date or as a Unix one (in UTC). Defaults to now.
+
+ :reqheader Accept: the requested response content type,
+ either *application/json* (default) or *application/yaml*
+ :resheader Content-Type: this depends on :http:header:`Accept` header of request
+
+ **Response JSON Object:**
+ same object as returned by :http:get:`/api/1/revision/(sha1_git)/`
+
+ **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options`
+
+ :statuscode 200: no error
+ :statuscode 404: no revision matching the given criteria could be found in the SWH archive
+
+ **Request:**
+
+ .. parsed-literal::
+
+ $ curl -i :swh_web_api:`revision/origin/13706355/branch/refs/heads/2.7/`
+
+ **Response:**
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "author": {
+ "email": "victor.stinner@gmail.com",
+ "fullname": "Victor Stinner ",
+ "id": 56592,
+ "name": "Victor Stinner"
+ },
+ "author_url": "/api/1/person/56592/",
+ "committer": {
+ "email": "noreply@github.com",
+ "fullname": "GitHub ",
+ "id": 10932771,
+ "name": "GitHub"
+ },
+ "committer_date": "2017-05-05T03:14:23+02:00",
+ "committer_url": "/api/1/person/10932771/",
+ "date": "2017-05-05T03:14:23+02:00",
+ "directory": "8657d73ae7c4018e24874f952d9b525bb6299027",
+ "directory_url": "/api/1/directory/8657d73ae7c4018e24874f952d9b525bb6299027/",
+ "history_url": "/api/1/revision/8a19eb24c97ef43e9fc7d45af180334ac8093545/log/",
+ "id": "8a19eb24c97ef43e9fc7d45af180334ac8093545",
+ "merge": false,
+ "message": "bpo-23404: make touch becomes make regen-all (#1466)\n\nDon't rebuild generated files based on file modification time\r\nanymore, the action is now explicit. Replace \"make touch\"\r\nwith \"make regen-all\".\r\n\r\nChanges:\r\n\r\n* Remove \"make touch\", Tools/hg/hgtouch.py and .hgtouch\r\n* Add a new \"make regen-all\" command to rebuild all generated files\r\n* Add subcommands to only generate specific files:\r\n\r\n - regen-ast: Include/Python-ast.h and Python/Python-ast.c\r\n - regen-grammar: Include/graminit.h and Python/graminit.c\r\n - regen-opcode-targets: Python/opcode_targets.h\r\n\r\n* Add PYTHON_FOR_REGEN variable\r\n* pgen is now only built by by \"make regen-grammar\"\r\n* Add $(srcdir)/ prefix to paths to source files to handle correctly\r\n compilation outside the source directory",
+ "metadata": {},
+ "parents": [
+ {
+ "id": "e81e355a8e43956802211115e3f99859a1a29ecb",
+ "url": "/api/1/revision/e81e355a8e43956802211115e3f99859a1a29ecb/"
+ }
+ ],
+ "synthetic": false,
+ "type": "git",
+ "url": "/api/1/revision/8a19eb24c97ef43e9fc7d45af180334ac8093545/"
+ }
+
+.. http:get:: /api/1/revision/origin/(origin_id)[/branch/(branch_name)][/ts/(timestamp)]/log
+
+ Show the commit log for a revision, searching for it based on software origin,
+ branch name, and/or visit timestamp.
+
+ This endpoint behaves like :http:get:`/api/1/revision/(sha1_git)[/prev/(prev_sha1s)]/log/`,
+ but operates on the revision that has been found at a given software origin,
+ close to a given point in time, pointed by a given branch.
+
+ :param int origin_id: a SWH origin identifier
+ :param string branch_name: optional parameter specifying a fully-qualified branch name
+ associated to the software origin, e.g., "refs/heads/master". Defaults to the master branch.
+ :param string timestamp: optional parameter specifying a timestamp close to which the revision
+ pointed by the given branch should be looked up. The timestamp can be expressed either
+ as an ISO date or as a Unix one (in UTC). Defaults to now.
+
+ :reqheader Accept: the requested response content type,
+ either *application/json* (default) or *application/yaml*
+ :resheader Content-Type: this depends on :http:header:`Accept` header of request
+
+ **Response JSON Array of Objects:**
+
+ array of revisions information as returned by :http:get:`/api/1/revision/(sha1_git)/`
+
+ **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options`
+
+ :statuscode 200: no error
+ :statuscode 404: no revision matching the given criteria could be found in the SWH archive
+
+ **Request:**
+
+ .. parsed-literal::
+
+ $ curl -i :swh_web_api:`revision/origin/723566/ts/2016-01-17T00:00:00+00:00/log/`
+
+ **Response:**
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ [
+ {
+ "author": {
+ "email": "gitster@pobox.com",
+ "fullname": "Junio C Hamano ",
+ "id": 4974,
+ "name": "Junio C Hamano"
+ },
+ "author_url": "/api/1/person/4974/",
+ "committer": {
+ "email": "gitster@pobox.com",
+ "fullname": "Junio C Hamano ",
+ "id": 4974,
+ "name": "Junio C Hamano"
+ },
+ "committer_date": "2016-02-24T13:31:57-08:00",
+ "committer_url": "/api/1/person/4974/",
+ "date": "2016-02-24T13:31:57-08:00",
+ "directory": "6985b8ccee00205572e706add0359e8f2b4c83b4",
+ "directory_url": "/api/1/directory/6985b8ccee00205572e706add0359e8f2b4c83b4/",
+ "history_url": "/api/1/revision/56f37fda511e1615dc6df86c68f3b841711a7828/log/",
+ "id": "56f37fda511e1615dc6df86c68f3b841711a7828",
+ "merge": false,
+ "message": "Eighth batch for 2.8\n\nSigned-off-by: Junio C Hamano \n",
+ "metadata": {},
+ "parents": [
+ {
+ "id": "c3b1e8d85133e2a19d372b7c166d5b49fcbbfef2",
+ "url": "/api/1/revision/c3b1e8d85133e2a19d372b7c166d5b49fcbbfef2/"
+ }
+ ],
+ "synthetic": false,
+ "type": "git",
+ "url": "/api/1/revision/56f37fda511e1615dc6df86c68f3b841711a7828/"
+ },
+ {
+ "author": {
+ "email": "gitster@pobox.com",
+ "fullname": "Junio C Hamano ",
+ "id": 4974,
+ "name": "Junio C Hamano"
+ },
+ "author_url": "/api/1/person/4974/",
+ "committer": {
+ "email": "gitster@pobox.com",
+ "fullname": "Junio C Hamano ",
+ "id": 4974,
+ "name": "Junio C Hamano"
+ },
+ "committer_date": "2016-02-24T13:26:01-08:00",
+ "committer_url": "/api/1/person/4974/",
+ "date": "2016-02-24T13:26:01-08:00",
+ "directory": "0db4cfbd62218fbf54be4160420b6e9c67cd60a0",
+ "directory_url": "/api/1/directory/0db4cfbd62218fbf54be4160420b6e9c67cd60a0/",
+ "history_url": "/api/1/revision/c3b1e8d85133e2a19d372b7c166d5b49fcbbfef2/log/",
+ "id": "c3b1e8d85133e2a19d372b7c166d5b49fcbbfef2",
+ "merge": true,
+ "message": "Merge branch 'jc/am-i-v-fix'\n\nThe \"v(iew)\" subcommand of the interactive \"git am -i\" command was\nbroken in 2.6.0 timeframe when the command was rewritten in C.\n\n* jc/am-i-v-fix:\n am -i: fix \"v\"iew\n pager: factor out a helper to prepare a child process to run the pager\n pager: lose a separate argv[]\n",
+ "metadata": {},
+ "parents": [
+ {
+ "id": "595bfefa6c31fa6d76b686ed79b024838db5933e",
+ "url": "/api/1/revision/595bfefa6c31fa6d76b686ed79b024838db5933e/"
+ },
+ {
+ "id": "708b8cc9a114ea1e5b90f5f52fd24ecade4e8b40",
+ "url": "/api/1/revision/708b8cc9a114ea1e5b90f5f52fd24ecade4e8b40/"
+ }
+ ],
+ "synthetic": false,
+ "type": "git",
+ "url": "/api/1/revision/c3b1e8d85133e2a19d372b7c166d5b49fcbbfef2/"
+ },
+ ]
+
diff --git a/docs/uri-scheme-api-stat.rst b/docs/uri-scheme-api-stat.rst
index 76034020..0b6bf6ef 100644
--- a/docs/uri-scheme-api-stat.rst
+++ b/docs/uri-scheme-api-stat.rst
@@ -1,65 +1,67 @@
Archive statistics
------------------
.. http:get:: /api/1/stat/counters
Get statistics about the content of the archive.
:>json number content: current number of content objects (aka files) in the SWH archive
:>json number directory: current number of directory objects in the SWH archive
:>json number directory_entry_dir: current number of SWH directory entries
pointing to others SWH directories in the SWH archive
:>json number directory_entry_file: current number of SWH directory entries
pointing to SWH content objects in the SWH archive
:>json number directory_entry_rev: current number of SWH directory entries
pointing to SWH revision objects (e.g. git submodules) in the SWH archive
:>json number entity: current number of SWH entities (a SWH entity is either
a *group_of_entities*, a *group_of_persons*, a *project*, a *person*, an *organization*,
or a *hosting* service) in the SWH archive
:>json number occurrence: current number of SWH occurences (an occurrence may be assimilated
to a branch found during a SWH crawl of a repository) in the SWH archive
:>json number origin: current number of SWH origins (an origin is a "place" where code
source can be found, e.g. a git repository, a tarball, ...) in the SWH archive
:>json number person: current number of SWH persons (code source authors or commiters)
in the SWH archive
:>json number release: current number of SWH releases objects in the SWH archive
:>json number revision: current number of SWH revision objects (aka commits) in the SWH archive
:>json number skipped_content: current number of content objects (aka files) which where
not inserted in the SWH archive
:reqheader Accept: the requested response content type,
either *application/json* (default) or *application/yaml*
:resheader Content-Type: this depends on :http:header:`Accept` header of request
+ **Allowed HTTP Methods:** :http:method:`get`, :http:method:`head`, :http:method:`options`
+
:statuscode 200: no error
- **Request**:
+ **Request:**
.. parsed-literal::
$ curl -i :swh_web_api:`stat/counters/`
- **Response**:
+ **Response:**
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"content": 3837301367,
"directory": 3385342732,
"directory_entry_dir": 2696063206,
"directory_entry_file": 3969668591,
"directory_entry_rev": 8201450,
"entity": 7101551,
"entity_history": 7148571,
"occurrence": 538691292,
"occurrence_history": 554791126,
"origin": 65642044,
"person": 17211993,
"release": 6666960,
"revision": 879725958,
"revision_history": 908684112,
"skipped_content": 19383
}
diff --git a/docs/uri-scheme-api.rst b/docs/uri-scheme-api.rst
index 5567e5e4..1a03747c 100644
--- a/docs/uri-scheme-api.rst
+++ b/docs/uri-scheme-api.rst
@@ -1,15 +1,18 @@
.. _swh-web-api-urls:
SWH Web API URLs
================
.. include:: uri-scheme-api-content.rst
.. include:: uri-scheme-api-directory.rst
.. include:: uri-scheme-api-origin.rst
-.. include:: uri-scheme-api-stat.rst
+.. include:: uri-scheme-api-person.rst
+.. include:: uri-scheme-api-release.rst
+.. include:: uri-scheme-api-revision.rst
+.. include:: uri-scheme-api-stat.rst
diff --git a/docs/uri-scheme-browse-content.rst b/docs/uri-scheme-browse-content.rst
index 237fa301..1a5cac66 100644
--- a/docs/uri-scheme-browse-content.rst
+++ b/docs/uri-scheme-browse-content.rst
@@ -1,83 +1,83 @@
Content
^^^^^^^
.. http:get:: /browse/content/[(algo_hash):](hash)/
HTML view that displays a SWH content identified by its hash value.
If the content to display is textual, it will be highlighted client-side
if possible using highlightjs_. In order for that operation to be
performed, a programming language must first be associated to the content.
The following procedure is used in order to find the language:
1) First try to find a language from the content filename
(provided as query parameter when navigating from a directory view).
2) If no language has been found from the filename,
try to find one from the content mime type.
The mime type is retrieved from the content metadata stored
in the SWH archive or is computed server-side using Python
magic module.
When that view is called in the context of a navigation coming from
a directory view, a breadcrumb will be displayed on top of the rendered
content in order to easily navigate up to the associated root directory.
In that case, the path query parameter will be used and filled with the path
of the file relative to the root directory.
:param string algo_hash: optional parameter to indicate the algorithm used
to compute the content checksum (can be either *sha1*,
*sha1_git*, *sha256* or *blake2s256*, default to *sha1*)
:param string hash: hexadecimal representation for the checksum from which
to retrieve the associated content in the SWH archive
:query string path: describe the path of the content relative to a root
directory (used to add context aware navigation links when navigating
from a directory view)
:statuscode 200: no error
:statuscode 400: an invalid query string has been provided
:statuscode 404: requested content can not be found in the SWH archive
- **Examples**:
+ **Examples:**
.. parsed-literal::
:swh_web_browse:`content/sha1_git:f5d0b39a0cdddb91a31a537052b7d8d31a4aa79f/`
:swh_web_browse:`content/blake2s256:1cc1e3124957c9be8a454c58e92eb925cf4aa9823984bd01451c5b7e0fee99d1/`
:swh_web_browse:`content/sha1:1cb1447c1c7ddc1b03eac88398e40bd914d46b62/`
:swh_web_browse:`content/sha256:8ceb4b9ee5adedde47b31e975c1d90c73ad27b6b165a1dcd80c7c545eb65b903/`
.. http:get:: /browse/content/[(algo_hash):](hash)/raw/
HTML view that produces a raw display of a SWH content identified by its hash value.
The behaviour of that view depends on the mime type of the requested content.
If the mime type is from the text family, the view will return a response whose
content type is 'text/plain' that will be rendered by the browser. Otherwise,
the view will return a response whose content type is 'application/octet-stream'
and the browser will then offer to download the file.
In the context of a navigation coming from a directory view, the filename query
parameter will be used in order to provide the real name of the file when
one wants to save it locally.
:param string algo_hash: optionnal parameter to indicate the algorithm used
to compute the content checksum (can be either *sha1*,
*sha1_git*, *sha256* or *blake2s256*, default to *sha1*)
:param string hash: hexadecimal representation for the checksum from which
to retrieve the associated content in the SWH archive
:query string filename: indicate the name of the file holding the requested
content (used when one wants to save the content to a local file)
:statuscode 200: no error
:statuscode 400: an invalid query string has been provided
:statuscode 404: requested content can not be found in the SWH archive
- **Examples**:
+ **Examples:**
.. parsed-literal::
:swh_web_browse:`content/sha1_git:f5d0b39a0cdddb91a31a537052b7d8d31a4aa79f/raw/?filename=LICENSE`
:swh_web_browse:`content/blake2s256:1cc1e3124957c9be8a454c58e92eb925cf4aa9823984bd01451c5b7e0fee99d1/raw/?filename=MAINTAINERS`
:swh_web_browse:`content/sha1:1cb1447c1c7ddc1b03eac88398e40bd914d46b62/raw/`
:swh_web_browse:`content/sha256:8ceb4b9ee5adedde47b31e975c1d90c73ad27b6b165a1dcd80c7c545eb65b903/raw/?filename=COPYING`
.. _highlightjs: https://highlightjs.org/
\ No newline at end of file
diff --git a/docs/uri-scheme-browse-directory.rst b/docs/uri-scheme-browse-directory.rst
index a7aa54a6..bfd6ed04 100644
--- a/docs/uri-scheme-browse-directory.rst
+++ b/docs/uri-scheme-browse-directory.rst
@@ -1,31 +1,31 @@
Directory
^^^^^^^^^
.. http:get:: /browse/directory/(sha1_git)/[(path)/]
HTML view for browsing the content of a SWH directory reachable from
the provided root one (including itself) identified by its `sha1_git` value.
The content of the directory is first sorted in lexicographical order
and the sub-directories are displayed before the regular files.
The view enables to navigate from the requested directory to
directories reachable from it in a recursive way but also
up to the root directory.
A breadcrumb located in the top part of the view allows
to keep track of the paths navigated so far.
:param string sha1_git: hexadecimal representation for the *sha1_git* identifier
of the directory to browse
:param string path: optional parameter used to specify the path of a directory
reachable from the provided root one
:statuscode 200: no error
:statuscode 400: an invalid *sha1_git* value has been provided
:statuscode 404: requested directory can not be found in the SWH archive
- **Examples**:
+ **Examples:**
.. parsed-literal::
:swh_web_browse:`directory/977fc4b98c0e85816348cebd3b12026407c368b6/`
:swh_web_browse:`directory/9650ed370c0330d2cd2b6fd1e9febf649ffe538d/kernel/sched/`
diff --git a/docs/uri-scheme-browse-origin.rst b/docs/uri-scheme-browse-origin.rst
index 752b42a0..5d290240 100644
--- a/docs/uri-scheme-browse-origin.rst
+++ b/docs/uri-scheme-browse-origin.rst
@@ -1,481 +1,454 @@
Origin
^^^^^^
Origin metadata
"""""""""""""""
.. http:get:: /browse/origin/(origin_id)/
HTML view that displays a SWH origin identified by its id.
The view displays the origin metadata and contains links
for browsing its directories and contents for each SWH visit.
:param int origin_id: the id of a SWH origin
:statuscode 200: no error
:statuscode 404: requested origin can not be found in the SWH archive
- **Examples**:
+ **Examples:**
.. parsed-literal::
:swh_web_browse:`origin/2/`
:swh_web_browse:`origin/13706355/`
.. http:get:: /browse/origin/(origin_type)/url/(origin_url)/
HTML view that displays a SWH origin identified by its type and url.
The view displays the origin metadata and contains links
for browsing its directories and contents for each SWH visit.
:param string origin_type: the type of the SWH origin (*git*, *svn*, ...)
:param string origin_url: the url of the origin (e.g. https://github.com///)
:statuscode 200: no error
:statuscode 404: requested origin can not be found in the SWH archive
- **Examples**:
+ **Examples:**
.. parsed-literal::
:swh_web_browse:`origin/git/url/https://github.com/torvalds/linux/`
:swh_web_browse:`origin/git/url/https://github.com/python/cpython/`
Origin directory
""""""""""""""""
.. http:get:: /browse/origin/(origin_id)/directory/[(path)/]
HTML view for browsing the content of a directory reachable from the root directory
(including itself) associated to the latest visit of a SWH origin.
The content of the directory is first sorted in lexicographical order
and the sub-directories are displayed before the regular files.
The view enables to navigate from the requested directory to
directories reachable from it in a recursive way but also
up to the origin root directory.
A breadcrumb located in the top part of the view allows
to keep track of the paths navigated so far.
The view also enables to easily switch between the origin branches
through a dropdown menu.
The origin branch (default to master) from which to retrieve the directory
content can also be specified by using the branch query parameter.
:param int origin_id: the id of a SWH origin
:param string path: optional parameter used to specify the path of a directory
reachable from the origin root one
:query string branch: specify the origin branch from which
to retrieve the directory
:query string revision: specify the origin revision, identified by the hexadecimal
representation of its *sha1_git* value, from which to retrieve the directory
:statuscode 200: no error
:statuscode 404: requested origin can not be found in the SWH archive
or the provided path does not exist from the origin root directory
- **Examples**:
+ **Examples:**
.. parsed-literal::
:swh_web_browse:`origin/2/directory/`
:swh_web_browse:`origin/2/directory/net/ethernet/`
:swh_web_browse:`origin/13706355/directory/`
:swh_web_browse:`origin/13706355/directory/Python/`
:swh_web_browse:`origin/13706355/directory/?branch=refs/heads/2.7`
.. http:get:: /browse/origin/(origin_id)/visit/(visit_id)/directory/[(path)/]
HTML view for browsing the content of a directory reachable from the root directory
(including itself) associated to a specific visit (identified by its id) of a SWH origin.
The content of the directory is first sorted in lexicographical order
and the sub-directories are displayed before the regular files.
The view enables to navigate from the requested directory to
directories reachable from it in a recursive way but also
up to the origin root directory.
A breadcrumb located in the top part of the view allows
to keep track of the paths navigated so far.
The view also enables to easily switch between the origin branches
through a dropdown menu.
The origin branch (default to master) from which to retrieve the directory
content can also be specified by using the branch query parameter.
:param int origin_id: the id of a SWH origin
:param int visit_id: the id of the origin visit
:param string path: optional parameter used to specify the path of a directory
reachable from the origin root one
:query string branch: specify the origin branch from which
to retrieve the directory
:query string revision: specify the origin revision, identified by the hexadecimal
representation of its *sha1_git* value, from which to retrieve the directory
:statuscode 200: no error
:statuscode 404: requested origin can not be found in the SWH archive,
requested visit id does not exist or the provided path does
not exist from the origin root directory
- **Examples**:
+ **Examples:**
.. parsed-literal::
:swh_web_browse:`origin/2/visit/2/directory/`
:swh_web_browse:`origin/2/visit/2/directory/net/ethernet/`
:swh_web_browse:`origin/13706355/visit/1/directory/`
:swh_web_browse:`origin/13706355/visit/1/directory/Python/`
:swh_web_browse:`origin/13706355/visit/1/directory/?branch=refs/heads/2.7`
.. http:get:: /browse/origin/(origin_id)/ts/(timestamp)/directory/[(path)/]
HTML view for browsing the content of a directory reachable from the root directory
(including itself) associated to a specific visit (identified by its timestamp) of a SWH origin.
The content of the directory is first sorted in lexicographical order
and the sub-directories are displayed before the regular files.
The view enables to navigate from the requested directory to
directories reachable from it in a recursive way but also
up to the origin root directory.
A breadcrumb located in the top part of the view allows
to keep track of the paths navigated so far.
The view also enables to easily switch between the origin branches
through a dropdown menu.
The origin branch (default to master) from which to retrieve the directory
content can also be specified by using the branch query parameter.
:param int origin_id: the id of a SWH origin
:param int timestamp: the Unix timestamp of the origin visit
:param path: optional parameter used to specify the path of a directory
reachable from the origin root one
:type path: string
:query string branch: specify the origin branch from which
to retrieve the directory
:query string revision: specify the origin revision, identified by the hexadecimal
representation of its *sha1_git* value, from which to retrieve the directory
:statuscode 200: no error
:statuscode 404: requested origin can not be found in the SWH archive,
requested visit timestamp does not exist or the provided path does
not exist from the origin root directory
- **Examples**:
+ **Examples:**
.. parsed-literal::
:swh_web_browse:`origin/2/ts/1493926809/directory/`
:swh_web_browse:`origin/2/ts/1493926809/directory/net/ethernet/`
:swh_web_browse:`origin/13706355/ts/1474620651/directory/`
:swh_web_browse:`origin/13706355/ts/1474620651/directory/Python/`
:swh_web_browse:`origin/13706355/ts/1474620651/directory/?branch=refs/heads/2.7`
Origin content
""""""""""""""
.. http:get:: /browse/origin/(origin_id)/content/(path)/
HTML view that produces a display of a SWH content
associated to the latest visit of a SWH origin.
If the content to display is textual, it will be highlighted client-side
- if possible using highlightjs_. In order for that operation to be
- performed, a programming language must first be associated to the content.
- The following procedure is used in order to find the language:
-
- 1) First try to find a language from the content filename
-
- 2) If no language has been found from the filename,
- try to find one from the content mime type.
- The mime type is retrieved from the content metadata stored
- in the SWH archive or is computed server-side using Python
- magic module.
+ if possible using highlightjs_. The procedure to perform that task is described
+ in :http:get:`/browse/content/[(algo_hash):](hash)/`.
The view displays a breadcrumb on top of the rendered
content in order to easily navigate up to the origin root directory.
The view also enables to easily switch between the origin branches
through a dropdown menu.
The origin branch (default to master) from which to retrieve the content
can also be specified by using the branch query parameter.
:param int origin_id: the id of a SWH origin
:param string path: path of a content reachable from the origin root directory
:query string branch: specify the origin branch from which
to retrieve the content
:query string revision: specify the origin revision, identified by the hexadecimal
representation of its *sha1_git* value, from which to retrieve the content
:statuscode 200: no error
:statuscode 404: requested origin can not be found in the SWH archive,
or the provided content path does not exist from the origin root directory
- **Examples**:
+ **Examples:**
.. parsed-literal::
:swh_web_browse:`origin/723566/content/git.c/`
:swh_web_browse:`origin/16297443/content/js/src/json.cpp/`
:swh_web_browse:`origin/723566/content/git.c/?branch=refs/heads/next`
.. http:get:: /browse/origin/(origin_id)/visit/(visit_id)/content/(path)/
HTML view that produces a display of a SWH content
associated to a specific visit (identified by its id) of a SWH origin.
If the content to display is textual, it will be highlighted client-side
- if possible using highlightjs_. In order for that operation to be
- performed, a programming language must first be associated to the content.
- The following procedure is used in order to find the language:
-
- 1) First try to find a language from the content filename
-
- 2) If no language has been found from the filename,
- try to find one from the content mime type.
- The mime type is retrieved from the content metadata stored
- in the SWH archive or is computed server-side using Python
- magic module.
+ if possible using highlightjs_. The procedure to perform that task is described
+ in :http:get:`/browse/content/[(algo_hash):](hash)/`.
The view displays a breadcrumb on top of the rendered
content in order to easily navigate up to the origin root directory.
The view also enables to easily switch between the origin branches
through a dropdown menu.
The origin branch (default to master) from which to retrieve the content
can also be specified by using the branch query parameter.
:param int origin_id: the id of a SWH origin
:param int visit_id: the id of the origin visit
:param string path: path of a content reachable from the origin root directory
:query string branch: specify the origin branch from which
to retrieve the content
:query string revision: specify the origin revision, identified by the hexadecimal
representation of its *sha1_git* value, from which to retrieve the content
:statuscode 200: no error
:statuscode 404: requested origin can not be found in the SWH archive,
requested visit id does not exist or the provided content path does
not exist from the origin root directory
- **Examples**:
+ **Examples:**
.. parsed-literal::
:swh_web_browse:`origin/723566/visit/1/content/git.c/`
:swh_web_browse:`origin/16297443/visit/3/content/js/src/json.cpp/`
:swh_web_browse:`origin/723566/visit/1/content/git.c/?branch=refs/heads/next`
.. http:get:: /browse/origin/(origin_id)/ts/(timestamp)/content/(path)/
HTML view that produces a display of a SWH content
associated to a specific visit (identified by its timestamp) of a SWH origin.
If the content to display is textual, it will be highlighted client-side
- if possible using highlightjs_. In order for that operation to be
- performed, a programming language must first be associated to the content.
- The following procedure is used in order to find the language:
-
- 1) First try to find a language from the content filename
-
- 2) If no language has been found from the filename,
- try to find one from the content mime type.
- The mime type is retrieved from the content metadata stored
- in the SWH archive or is computed server-side using Python
- magic module.
+ if possible using highlightjs_. The procedure to perform that task is described
+ in :http:get:`/browse/content/[(algo_hash):](hash)/`.
The view displays a breadcrumb on top of the rendered
content in order to easily navigate up to the origin root directory.
The view also enables to easily switch between the origin branches
through a dropdown menu.
The origin branch (default to master) from which to retrieve the content
can also be specified by using the branch query parameter.
:param int origin_id: the id of a SWH origin
:param int timestamp: the Unix timestamp of the origin visit
:param string path: path of a content reachable from the origin root directory
:query string branch: specify the origin branch from which
to retrieve the content
:query string revision: specify the origin revision, identified by the hexadecimal
representation of its *sha1_git* value, from which to retrieve the content
:statuscode 200: no error
:statuscode 404: requested origin can not be found in the SWH archive,
requested visit timestamp does not exist or the provided content path does
not exist from the origin root directory
- **Examples**:
+ **Examples:**
.. parsed-literal::
:swh_web_browse:`origin/723566/ts/1473933564/content/git.c/`
:swh_web_browse:`origin/16297443/ts/1490126182/content/js/src/json.cpp/`
:swh_web_browse:`origin/723566/ts/1473933564/content/git.c/?branch=refs/heads/next`
Origin history
""""""""""""""
.. http:get:: /browse/origin/(origin_id)/log/
HTML view that produces a display of revisions history heading
to the last revision found during the latest visit of a SWH origin.
In other words, it shows the commit log associated to the latest
visit of a SWH origin.
The following data are displayed for each log entry:
* author of the revision
* link to the revision metadata
* message associated the revision
* date of the revision
* link to browse the associated source tree in the origin context
N log entries are displayed per page (default is 20). In order to navigate
in a large history, two buttons are present at the bottom of the view:
* *Newer*: fetch and display if available the N more recent log entries
than the ones currently displayed
* *Older*: fetch and display if available the N older log entries
than the ones currently displayed
The view also enables to easily switch between the origin branches
through a dropdown menu.
The origin branch (default to master) from which to retrieve the content
can also be specified by using the branch query parameter.
:param int origin_id: the id of a SWH origin
:query string revs_breadcrumb: used internally to store
the navigation breadcrumbs (i.e. the list of descendant revisions
visited so far). It must be a string in the form
"[//.../]" where rev_i corresponds to a
revision sha1_git.
:query int per_page: the number of log entries to display per page
(default is 20, max is 50)
:query string branch: specify the origin branch from which
to retrieve the commit log
:query string revision: specify the origin revision, identified by the hexadecimal
representation of its *sha1_git* value, from which to retrieve the commit log
:statuscode 200: no error
:statuscode 404: requested origin can not be found in the SWH archive
- **Examples**:
+ **Examples:**
.. parsed-literal::
:swh_web_browse:`origin/12215444/log/`
:swh_web_browse:`origin/2081083/log/`
:swh_web_browse:`origin/12081083/log/?branch=refs/heads/release`
.. http:get:: /browse/origin/(origin_id)/visit/(visit_id)/log/
HTML view that produces a display of revisions history heading
to the last revision found during a specific visit of a SWH origin.
In other words, it shows the commit log associated to a specific
visit of a SWH origin.
The following data are displayed for each log entry:
* author of the revision
* link to the revision metadata
* message associated the revision
* date of the revision
* link to browse the associated source tree in the origin context
N log entries are displayed per page (default is 20). In order to navigate
in a large history, two buttons are present at the bottom of the view:
* *Newer*: fetch and display if available the N more recent log entries
than the ones currently displayed
* *Older*: fetch and display if available the N older log entries
than the ones currently displayed
The view also enables to easily switch between the origin branches
through a dropdown menu.
The origin branch (default to master) from which to retrieve the content
can also be specified by using the branch query parameter.
:param int origin_id: the id of a SWH origin
:param int visit_id: the id of the origin visit
:query string revs_breadcrumb: used internally to store
the navigation breadcrumbs (i.e. the list of descendant revisions
visited so far). It must be a string in the form
"[//.../]" where rev_i corresponds to a
revision sha1_git.
:query int per_page: the number of log entries to display per page
(default is 20, max is 50)
:query string branch: specify the origin branch from which
to retrieve the commit log
:query string revision: specify the origin revision, identified by the hexadecimal
representation of its *sha1_git* value, from which to retrieve the commit log
:statuscode 200: no error
:statuscode 404: requested origin can not be found in the SWH archive
- **Examples**:
+ **Examples:**
.. parsed-literal::
:swh_web_browse:`origin/12215444/visit/2/log/`
:swh_web_browse:`origin/12081083/visit/10/log/`
:swh_web_browse:`origin/12081083/visit/10/log/?branch=refs/heads/release`
.. http:get:: /browse/origin/(origin_id)/ts/(timestamp)/log/
HTML view that produces a display of revisions history heading
to the last revision found during a specific visit (identified by its
timestamp) of a SWH origin.
In other words, it shows the commit log associated to a specific
visit (identified by its timestamp) of a SWH origin.
The following data are displayed for each log entry:
* author of the revision
* link to the revision metadata
* message associated the revision
* date of the revision
* link to browse the associated source tree in the origin context
N log entries are displayed per page (default is 20). In order to navigate
in a large history, two buttons are present at the bottom of the view:
* *Newer*: fetch and display if available the N more recent log entries
than the ones currently displayed
* *Older*: fetch and display if available the N older log entries
than the ones currently displayed
The view also enables to easily switch between the origin branches
through a dropdown menu.
The origin branch (default to master) from which to retrieve the content
can also be specified by using the branch query parameter.
:param int origin_id: the id of a SWH origin
:param int timestamp: the Unix timestamp of the origin visit
:query string revs_breadcrumb: used internally to store
the navigation breadcrumbs (i.e. the list of descendant revisions
visited so far). It must be a string in the form
"[//.../]" where rev_i corresponds to a
revision sha1_git.
:query int per_page: the number of log entries to display per page
(default is 20, max is 50)
:query string branch: specify the origin branch from which
to retrieve the commit log
:query string revision: specify the origin revision, identified by the hexadecimal
representation of its *sha1_git* value, from which to retrieve the commit log
:statuscode 200: no error
:statuscode 404: requested origin can not be found in the SWH archive
- **Examples**:
+ **Examples:**
.. parsed-literal::
:swh_web_browse:`origin/12215444/ts/1459651262/log/`
:swh_web_browse:`origin/12081083/ts/1438116814/log/`
:swh_web_browse:`origin/12081083/ts/1438116814/log/?branch=refs/heads/release`
.. _highlightjs: https://highlightjs.org/