diff --git a/swh/web/ui/templates/includes/apidoc-header-toc.html b/swh/web/ui/templates/includes/apidoc-header-toc.html new file mode 100644 index 000000000..8716a2ef0 --- /dev/null +++ b/swh/web/ui/templates/includes/apidoc-header-toc.html @@ -0,0 +1,26 @@ +
  • Version
  • +
  • Schema
  • +
  • Mimetype override
  • +
  • Parameters + +
  • +
  • Client errors + +
  • +
  • Terminology + +
  • +
  • Opened endpoints
  • diff --git a/swh/web/ui/templates/includes/apidoc-header.html b/swh/web/ui/templates/includes/apidoc-header.html index 75e67d051..969a3a693 100644 --- a/swh/web/ui/templates/includes/apidoc-header.html +++ b/swh/web/ui/templates/includes/apidoc-header.html @@ -1,128 +1,106 @@

    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 as json by default.

    Examples:

    curl -i https://archive.softwareheritage.org/api/1/stat/counters/

    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 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

    Open api endpoints is accessed at https://archive.softwareheritage.org/api/1/.

    diff --git a/swh/web/ui/templates/layout.html b/swh/web/ui/templates/layout.html index 985f2a323..6839fbf27 100644 --- a/swh/web/ui/templates/layout.html +++ b/swh/web/ui/templates/layout.html @@ -1,65 +1,70 @@ {% block title %}{% endblock %} - The Software Heritage Archive

    {{ self.title() }}

    {% with messages = get_flashed_messages(with_categories=true) %} {% if messages %}
    {% for category, message in messages %} {% endfor %}
    {% endif %} {% endwith %}
    {% block content %}{% endblock %}