diff --git a/swh/web/ui/templates/api-endpoints.html b/swh/web/ui/templates/api-endpoints.html index f6f3815f2..d57130f96 100644 --- a/swh/web/ui/templates/api-endpoints.html +++ b/swh/web/ui/templates/api-endpoints.html @@ -1,60 +1,60 @@ {% extends "layout.html" %} {% block title %}API endpoints overview{% endblock %} {% block content %}
This lists the current API endpoints for version 1. For a more general description, please refer to the main documentation.
{% for route, doc in doc_routes %} {% if 'tags' in doc and doc['tags'] is not none %} {% else %} {% endif %} {% endfor %}
Route Status Description
{{ route }}{{ ', '.join(doc['tags']) }}opened{{ doc['docstring'] | safe_docstring_display | safe }}
{% endblock %} diff --git a/swh/web/ui/templates/apidoc.html b/swh/web/ui/templates/apidoc.html index 4168bc97b..090df060f 100644 --- a/swh/web/ui/templates/apidoc.html +++ b/swh/web/ui/templates/apidoc.html @@ -1,123 +1,123 @@ {% extends "layout.html" %} {% block title %} API overview {% endblock %} {% block content %} {% if docstring %}

Description

{{ docstring | safe_docstring_display | safe }}
{% endif %} {% if response_data and response_data is not none %}

Request

{{ request.method }} {{ request.url }}
{% if headers_data and headers_data is not none %}

Headers

{% for header_name, header_value in headers_data.items() %}
{{ header_name }} {{ header_value | urlize_header_links | safe }}
{% endfor %} {% endif %}

Result

{{ response_data | escape_author_fields | urlize_api_links | safe }}
{% endif %}
{% for url in urls %} {% endfor %}
URL Allowed Methods
{{ url['rule'] }} {{ url['methods'] | sort | join(', ') }}

{% if args and args|length > 0 %}

Args

{% for arg in args %}
{{ arg['name'] }}: {{ arg['type'] }}
{{ arg['doc'] | safe_docstring_display | safe }}
{% endfor %}
{% endif %} {% if params and params|length > 0 %}

Params

{% for param in params %}
{{ param['name'] }}: string
{{ param['doc'] | safe_docstring_display | safe }}
{% endfor %}
{% endif %} {% if excs and excs|length > 0 %}

Raises

{% for exc in excs %}
{{ exc['exc'] }}
{{ exc['doc'] | safe_docstring_display | safe }}
{% endfor %}
{% endif %} {% if headers %}

Headers

{% for header in headers %}
{{ header['name'] }}: string
{{ header['doc'] | safe_docstring_display | safe }}
{% endfor %}
{% endif %} {% if return %}

Returns

{{ return['type'] }}
{{ return['doc'] | safe_docstring_display | safe }}
{% endif %} {% if examples %}

Examples

{% for example in examples %}
{{ example }}
{% endfor %}
{% endif %} {% endblock %} diff --git a/swh/web/ui/templates/includes/apidoc-header.html b/swh/web/ui/templates/includes/apidoc-header.html index 34b9ad928..8a2f9038c 100644 --- a/swh/web/ui/templates/includes/apidoc-header.html +++ b/swh/web/ui/templates/includes/apidoc-header.html @@ -1,109 +1,109 @@

Welcome to Software Heritage project's API documentation.

Table of Contents

Version

Current version is 1.

Schema

Api access is over https and accessed through https://archive.softwareheritage.org/api/1/.

Data is sent and received in json by default.

Examples:

Mimetype override

The response output can be sent as yaml provided the client specifies it using the header field.

Examples:

Parameters

Some API endpoints can be used with local parameters. The url then needs to be adapted accordingly.

For example:

https://archive.softwareheritage.org/api/1/<endpoint-name>?<field0>=<value0>&<field1>=<value1>

where:

Global parameter

One parameter is defined for all api endpoints fields. It permits to filter the output fields per key.

For example, to only list the number of contents, revisions, directories on the statistical endpoints, one uses:

Examples:

Note: If the keys provided to filter on do not exist, they are ignored.

Client errors

There are 2 kinds of error.

In that case, the http error code will reflect. Furthermore, the response is a dictionary with one key 'error' detailing the problem.

Bad request

This means that the input is incorrect.

Example:

The api content expects an hash identifier so the error will mention that an hash identifier is expected.

Not found

This means that the request is ok but we do not found the information the user requests.

Examples:

The hash identifier is ok but nothing is found for that identifier.

Terminology

You will find below the terminology the project SWH uses. More details can be found on swh's wiki glossary page.

Content

A (specific version of a) file stored in the archive, identified by its cryptographic hashes (SHA1, "git-like" SHA1, SHA256) and its size.

Also known as: Blob Note.

(Cryptographic) hash

A fixed-size "summary" of a stream of bytes that is easy to compute, and hard to reverse.

Also known as: Checksum, Digest.

Directory

A set of named pointers to contents (file entries), directories (directory entries) and revisions (revision entries).

Origin

A location from which a coherent set of sources has been obtained.

Also known as: Data source.

Examples:

Project

An organized effort to develop a software product.

Projects might be nested following organizational structures (sub-project, sub-sub-project), are associated to a number of human-meaningful metadata, and release software products via Origins.

Release

A revision that has been marked by a project as noteworthy with a specific, usually mnemonic, name (for instance, a version number).

Also known as: Tag (Git-specific terminology).

Examples:

Revision

A "point in time" snapshot in the development history of a project.

Also known as: Commit

Examples:

Opened endpoints

Accessible through https://archive.softwareheritage.org/api/1/.