diff --git a/docs/uri-scheme-api-content.rst b/docs/uri-scheme-api-content.rst index 2779f22b..423080c9 100644 --- a/docs/uri-scheme-api-content.rst +++ b/docs/uri-scheme-api-content.rst @@ -1,275 +1,275 @@ Content ------- .. 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 response content type depends on :mailheader:`Accept` header: + :reqheader Accept: the requested response content type, either *application/json* (default) or *application/yaml* - :resheader Content-Type: this depends on :mailheader:`Accept` header of request + :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 :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**: .. parsed-literal:: $ curl -i :swh_web_api:`content/sha1_git:fe95a46679d128ff167b7c55df5d02356c5a1ae1/` **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 :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**: .. parsed-literal:: $ curl -i :swh_web_api:`content/sha1:dc2830a9e72f23c1dfebef4413003221baa5fb62/raw/` **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 response content type depends on :mailheader:`Accept` header: + :reqheader Accept: the requested response content type, either *application/json* (default) or *application/yaml* - :resheader Content-Type: this depends on :mailheader:`Accept` header of request + :resheader Content-Type: this depends on :http:header:`Accept` header of request :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**: .. parsed-literal:: $ curl -i :swh_web_api:`content/sha1:dc2830a9e72f23c1dfebef4413003221baa5fb62/filetype/` **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 response content type depends on :mailheader:`Accept` header: + :reqheader Accept: the requested response content type, either *application/json* (default) or *application/yaml* - :resheader Content-Type: this depends on :mailheader:`Accept` header of request + :resheader Content-Type: this depends on :http:header:`Accept` header of request :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**: .. parsed-literal:: $ curl -i :swh_web_api:`content/sha1:dc2830a9e72f23c1dfebef4413003221baa5fb62/language/` **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 response content type depends on :mailheader:`Accept` header: + :reqheader Accept: the requested response content type, either *application/json* (default) or *application/yaml* - :resheader Content-Type: this depends on :mailheader:`Accept` header of request + :resheader Content-Type: this depends on :http:header:`Accept` header of request :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**: .. parsed-literal:: $ curl -i :swh_web_api:`content/sha1:dc2830a9e72f23c1dfebef4413003221baa5fb62/license/` **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 7d7d37bd..46d48676 100644 --- a/docs/uri-scheme-api-directory.rst +++ b/docs/uri-scheme-api-directory.rst @@ -1,85 +1,85 @@ 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 response content type depends on :mailheader:`Accept` header: + :reqheader Accept: the requested response content type, either *application/json* (default) or *application/yaml* - :resheader Content-Type: this depends on :mailheader:`Accept` header of request + :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 (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) 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)/` 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* :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**: .. parsed-literal:: $ curl -i :swh_web_api:`directory/977fc4b98c0e85816348cebd3b12026407c368b6/` **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 6ac98f79..19d67226 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 response content type depends on :mailheader:`Accept` header: + :reqheader Accept: the requested response content type, either *application/json* (default) or *application/yaml* - :resheader Content-Type: this depends on :mailheader:`Accept` header of request + :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**: .. parsed-literal:: $ curl -i :swh_web_api:`origin/1/` **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 response content type depends on :mailheader:`Accept` header: + :reqheader Accept: the requested response content type, either *application/json* (default) or *application/yaml* - :resheader Content-Type: this depends on :mailheader:`Accept` header of request + :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**: .. parsed-literal:: $ curl -i :swh_web_api:`origin/git/url/https://github.com/python/cpython/` **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 response content type depends on :mailheader:`Accept` header: + :reqheader Accept: the requested response content type, either *application/json* (default) or *application/yaml* - :resheader Content-Type: this depends on :mailheader:`Accept` header of request + :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)/` 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 :statuscode 200: no error :statuscode 404: requested origin can not be found in the SWH archive **Request**: .. parsed-literal:: $ curl -i :swh_web_api:`origin/1/visits/` **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 response content type depends on :mailheader:`Accept` header: + :reqheader Accept: the requested response content type, either *application/json* (default) or *application/yaml* - :resheader Content-Type: this depends on :mailheader:`Accept` header of request + :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 :statuscode 200: no error :statuscode 404: requested origin or visit can not be found in the SWH archive **Request**: .. parsed-literal:: $ curl -i :swh_web_api:`origin/1500/visit/1/` **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-stat.rst b/docs/uri-scheme-api-stat.rst index 4e2057af..76034020 100644 --- a/docs/uri-scheme-api-stat.rst +++ b/docs/uri-scheme-api-stat.rst @@ -1,65 +1,65 @@ 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 response content type depends on :mailheader:`Accept` header: + :reqheader Accept: the requested response content type, either *application/json* (default) or *application/yaml* - :resheader Content-Type: this depends on :mailheader:`Accept` header of request + :resheader Content-Type: this depends on :http:header:`Accept` header of request :statuscode 200: no error **Request**: .. parsed-literal:: $ curl -i :swh_web_api:`stat/counters/` **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/swh/web/doc_config.py b/swh/web/doc_config.py index 118f7288..87cf4a4c 100644 --- a/swh/web/doc_config.py +++ b/swh/web/doc_config.py @@ -1,21 +1,25 @@ # Copyright (C) 2017 The Software Heritage developers # See the AUTHORS file at the top-level directory of this distribution # License: GNU General Public License version 3, or any later version # See top-level LICENSE file for more information +from sphinxcontrib import httpdomain _swh_web_base_url = 'https://archive.softwareheritage.org' _swh_web_api_endpoint = 'api' _swh_web_api_version = 1 _swh_web_api_url = '%s/%s/%s/' % (_swh_web_base_url, _swh_web_api_endpoint, _swh_web_api_version) _swh_web_browse_endpoint = 'browse' _swh_web_browse_url = '%s/%s/' % (_swh_web_base_url, _swh_web_browse_endpoint) def customize_sphinx_conf(sphinx_conf): + # fix for sphinxcontrib.httpdomain 1.3 + if 'Link' not in httpdomain.HEADER_REFS: + httpdomain.HEADER_REFS['Link'] = httpdomain.IETFRef(5988, '5') sphinx_conf.extlinks['swh_web_api'] = (_swh_web_api_url + '%s', None) sphinx_conf.extlinks['swh_web_browse'] = (_swh_web_browse_url + '%s', None)