diff --git a/Makefile.local b/Makefile.local
index 0b2ea349a..a9e609683 100644
--- a/Makefile.local
+++ b/Makefile.local
@@ -1,9 +1,13 @@
SWH_WEB_UI=./bin/swh-web-ui-dev
FLAG=-v
NOSEFLAGS=-v -s
+TOOL=pandoc
run-dev:
$(SWH_WEB_UI) $(FLAG) --config ./resources/test/webapp.yml
run: # works with the default ~/.config/swh/webapp.yml file
$(SWH_WEB_UI) $(FLAG)
+
+doc:
+ cd swh/web/ui/templates/includes/ && pandoc -o api-header.html api-header.md
diff --git a/swh/web/ui/static/css/style.css b/swh/web/ui/static/css/style.css
index 119cac8d3..c507f438b 100644
--- a/swh/web/ui/static/css/style.css
+++ b/swh/web/ui/static/css/style.css
@@ -1,82 +1,82 @@
/*
version: 0.1
date: 21/09/15
author: swh
email: swh
website: softwareheritage.org
version history: /style.css
*/
body { font-family: sans-serif; background: #eee; }
a, h1, h2 { color: #377ba8; }
h1, h2 { font-family: 'Georgia', serif; margin: 0; }
h1 { border-bottom: 2px solid #eee; }
h2 { font-size: 1.2em; }
.page { margin: 2em auto; width: 35em; border: 5px solid #ccc;
padding: 0.8em; background: white; }
.entries { list-style: none; margin: 0; padding: 0; }
.entries li { margin: 0.8em 1.2em; }
.entries li h2 { margin-left: -1em; }
.add-entry { font-size: 0.9em; border-bottom: 1px solid #ccc; }
.add-entry dl { font-weight: bold; }
.metanav { text-align: right; font-size: 0.8em; padding: 0.3em;
margin-bottom: 1em; background: #fafafa; }
.flash { background: #cee5F5; padding: 0.5em;
border: 1px solid #aacbe2; }
.error { background: #f0d6d6; padding: 0.5em; }
.file-found { color: #23BA49; }
.file-notfound { color: #FF4747; }
/* Bootstrap custom styling to correctly render multiple
* form-controls in an input-group:
* github.com/twbs/bootstrap/issues/12732 */
.input-group-field {
display: table-cell;
vertical-align: middle;
border-radius:4px;
min-width:1%;
white-space: nowrap;
}
.input-group-field .form-control {
border-radius: inherit !important;
}
.input-group-field:not(:first-child):not(:last-child) {
border-radius:0;
}
.input-group-field:not(:first-child):not(:last-child) .form-control {
border-left-width: 0;
border-right-width: 0;
}
.input-group-field:last-child {
border-top-left-radius:0;
border-bottom-left-radius:0;
}
.input-group > span:not(:last-child) > button {
border-radius: 0;
}
.multi-input-group > .input-group-btn {
vertical-align: bottom;
padding: 0;
}
.dataTables_filter input {
width: 70%;
float: right;
}
-.api-doc-route-upcoming h2 {
+.api-doc-route-upcoming h4 {
color: orange;
}
-.api-doc-route-deprecated h2 {
+.api-doc-route-deprecated h4 {
color: red;
}
diff --git a/swh/web/ui/templates/api.html b/swh/web/ui/templates/api.html
index b38e45818..c650e47ef 100644
--- a/swh/web/ui/templates/api.html
+++ b/swh/web/ui/templates/api.html
@@ -1,18 +1,21 @@
{% extends "layout.html" %}
{% block title %}API Overview{% endblock %}
{% block content %}
+
<div class="api-doc">
+ {% include 'includes/api-header.html' %}
{% for route, doc in doc_routes %}
{% if 'tags' in doc and doc['tags'] is not none %}
<div class="api-doc-route{% for tag in doc['tags'] %} api-doc-route-{{ tag }}{% endfor %}">
- <h2> {{ route }} </h2> ({{ ', '.join(doc['tags']) }})
+ <h4> {{ route }} </h4>
+ ({{ ', '.join(doc['tags']) }})
{% else %}
<div class="api-doc-route">
- <h2> <a href="{{ route }}">{{ route }}</a> </h2>
+ <h4> <a href="{{ route }}">{{ route }}</a> </h4>
{% endif %}
{% autoescape off %}{{ doc['docstring'] | safe_docstring_display }}{% endautoescape %}
</div>
</br>
{% endfor %}
</div>
{% endblock %}
diff --git a/swh/web/ui/templates/includes/api-header.html b/swh/web/ui/templates/includes/api-header.html
new file mode 100644
index 000000000..2ca3de372
--- /dev/null
+++ b/swh/web/ui/templates/includes/api-header.html
@@ -0,0 +1,178 @@
+<p>Welcome to Software Heritage project's API.</p>
+<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-generate-toc again -->
+<p><strong>Table of Contents</strong></p>
+<ul>
+<li><a href="#schema">Schema</a>
+<ul>
+<li><a href="#mimetype-override">Mimetype override</a></li>
+<li><a href="#parameters">Parameters</a>
+<ul>
+<li><a href="#global-parameter">Global parameter</a></li>
+</ul></li>
+<li><a href="#client-errors">Client errors</a>
+<ul>
+<li><a href="#bad-request">Bad request</a></li>
+<li><a href="#not-found">Not found</a></li>
+</ul></li>
+<li><a href="#terminology">Terminology</a>
+<ul>
+<li><a href="#content">Content</a></li>
+<li><a href="#cryptographic-hash">(Cryptographic) hash</a></li>
+<li><a href="#directory">Directory</a></li>
+<li><a href="#origin">Origin</a></li>
+<li><a href="#project">Project</a></li>
+<li><a href="#release">Release</a></li>
+<li><a href="#revision">Revision</a></li>
+</ul></li>
+<li><a href="#opened-endpoints">Opened endpoints</a></li>
+</ul></li>
+</ul>
+<!-- markdown-toc end -->
+<h3 id="version">Version</h3>
+<p>Current version is 1.</p>
+<h3 id="schema">Schema</h3>
+<p>Api access is over https and accessed through <a href="https://archive.softwareheritage.org/api/">https://archive.softwareheritage.org/api/1/</a>.</p>
+<p>Data is sent and received as json.</p>
+<p>Example:</p>
+<pre class="shell"><code>$ curl -i https://archive.softwareheritage.org/api/1/stat/counters/
+HTTP/1.1 200 OK
+Date: Mon, 16 Jan 2017 10:57:56 GMT
+Server: Apache
+Content-Type: application/json
+Content-Length: 395
+Vary: Accept-Encoding
+Access-Control-Allow-Origin: *
+Connection: close
+
+{
+ "directory_entry_rev": 3039473,
+ "person": 13903080,
+ "entity": 7103795,
+ "skipped_content": 17864,
+ "entity_history": 7147753,
+ "revision_history": 720840448,
+ "revision": 703277184,
+ "directory": 2616883200,
+ "release": 5692900,
+ "origin": 49938216,
+ "directory_entry_dir": 2140887552,
+ "occurrence_history": 254274832,
+ "occurrence": 241899344,
+ "content": 3155739136,
+ "directory_entry_file": 3173807104
+}</code></pre>
+<h4 id="mimetype-override">Mimetype override</h4>
+<p>The response output can be sent as yaml provided the client specifies it using the header field.</p>
+<p>For example:</p>
+<pre class="shell"><code>curl -i -H 'Accept: application/yaml' https://archive.softwareheritage.org/api/1/stat/counters/
+HTTP/1.1 200 OK
+Date: Mon, 16 Jan 2017 12:31:50 GMT
+Server: Apache
+Content-Type: application/yaml
+Content-Length: 372
+Access-Control-Allow-Origin: *
+Connection: close
+
+{content: 3155758336,
+ directory: 2616955136,
+ directory_entry_dir: 2140925824,
+ directory_entry_file: 3173833984,
+ directory_entry_rev: 3039473,
+ entity: 7103741,
+ entity_history: 7148121,
+ occurrence: 241887488,
+ occurrence_history: 254277584,
+ origin: 49939848,
+ person: 13898394,
+ release: 5693922,
+ revision: 703275840,
+ revision_history: 720842176,
+ skipped_content: 17864}</code></pre>
+<h3 id="parameters">Parameters</h3>
+<p>Some API endpoints can be used with with local parameters. The url then needs to be adapted accordingly.</p>
+<p>For example:</p>
+<pre class="text"><code>https://archive.softwareheritage.org/api/1/<endpoint-name>?<field0>=<value0>&<field1>=<value1></code></pre>
+<p>where:</p>
+<ul>
+<li>field0 is an appropriate field for the <endpoint-name> and value0</li>
+<li>field1 is an appropriate field for the <endpoint-name> and value1</li>
+</ul>
+<h4 id="global-parameter">Global parameter</h4>
+<p>One parameter is defined for all api endpoints <code>fields</code>. It permits to filter the output fields per key.</p>
+<p>For example, to only list the number of contents, revisions, directories on the statistical endpoints, one uses:</p>
+<pre class="shell"><code>$ curl https://archive.softwareheritage.org/api/1/stat/counters/\?fields\=content,directory,revision | jq
+{
+ "content": 3155739136,
+ "revision": 703277184,
+ "directory": 2616883200
+}</code></pre>
+<p>Note: If the keys provided to filter on do not exist, they are ignored.</p>
+<h3 id="client-errors">Client errors</h3>
+<p>There are 2 kinds of error.</p>
+<p>In that case, the http error code will reflect that error and a json response is sent with the detailed error.</p>
+<h4 id="bad-request">Bad request</h4>
+<p>This means that the input is incorrect.</p>
+<p>Example:</p>
+<pre class="shell"><code>curl -i https://archive.softwareheritage.org/api/1/content/1/
+HTTP/1.1 400 BAD REQUEST
+Date: Mon, 16 Jan 2017 11:28:08 GMT
+Server: Apache
+Content-Type: application/json
+Content-Length: 44
+Connection: close
+
+{"error": "Invalid checksum query string 1"}</code></pre>
+<p>Here, the api content expects an hash identifier.</p>
+<h4 id="not-found">Not found</h4>
+<p>This means that the request is ok but we do not found the information the user requests.</p>
+<p>Example:</p>
+<pre class="shell"><code>curl -i https://archive.softwareheritage.org/api/1/content/04740277a81c5be6c16f6c9da488ca073b770d7f/
+HTTP/1.1 404 NOT FOUND
+Date: Mon, 16 Jan 2017 11:31:46 GMT
+Server: Apache
+Content-Type: application/json
+Content-Length: 77
+Connection: close
+
+{"error": "Content with 04740277a81c5be6c16f6c9da488ca073b770d7f not found."}</code></pre>
+<h3 id="terminology">Terminology</h3>
+<p>You will find below the terminology the project swh uses. More details can be found on <a href="https://wiki.softwareheritage.org/index.php?title=Glossary">swh's wiki glossary page</a>.</p>
+<h4 id="content">Content</h4>
+<p>A (specific version of a) file stored in the archive, identified by its cryptographic hashes (SHA1, "git-like" SHA1, SHA256) and its size.</p>
+<p>Also known as: Blob Note.</p>
+<h4 id="cryptographic-hash">(Cryptographic) hash</h4>
+<p>A fixed-size "summary" of a stream of bytes that is easy to compute, and hard to reverse.</p>
+<p>Also known as: Checksum, Digest.</p>
+<h4 id="directory">Directory</h4>
+<p>A set of named pointers to contents (file entries), directories (directory entries) and revisions (revision entries).</p>
+<h4 id="origin">Origin</h4>
+<p>A location from which a coherent set of sources has been obtained.</p>
+<p>Also known as: Data source.</p>
+<p>Examples:</p>
+<ul>
+<li>a Git repository</li>
+<li>a directory containing tarballs</li>
+<li>the history of a Debian package on snapshot.debian.org.</li>
+</ul>
+<h4 id="project">Project</h4>
+<p>An organized effort to develop a software product.</p>
+<p>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.</p>
+<h4 id="release">Release</h4>
+<p>A revision that has been marked by a project as noteworthy with a specific, usually mnemonic, name (for instance, a version number).</p>
+<p>Also known as: Tag (Git-specific terminology).</p>
+<p>Examples:</p>
+<ul>
+<li>a Git tag with its name</li>
+<li>a tarball with its name</li>
+<li>a Debian source package with its version number.</li>
+</ul>
+<h4 id="revision">Revision</h4>
+<p>A "point in time" snapshot in the development history of a project.</p>
+<p>Also known as: Commit</p>
+<p>Examples:</p>
+<ul>
+<li>a Git commit</li>
+</ul>
+<h3 id="opened-endpoints">Opened endpoints</h3>
+<p>(may have to move to /api/1/)</p>
+<p>Below, you will find the opened endpoints. This will permit you to read information on the origin we load up until now.</p>
diff --git a/swh/web/ui/templates/includes/api-header.md b/swh/web/ui/templates/includes/api-header.md
new file mode 100644
index 000000000..7f89a6622
--- /dev/null
+++ b/swh/web/ui/templates/includes/api-header.md
@@ -0,0 +1,255 @@
+Welcome to Software Heritage project's API.
+
+<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-generate-toc again -->
+**Table of Contents**
+
+- [Schema](#schema)
+ - [Mimetype override](#mimetype-override)
+ - [Parameters](#parameters)
+ - [Global parameter](#global-parameter)
+ - [Client errors](#client-errors)
+ - [Bad request](#bad-request)
+ - [Not found](#not-found)
+ - [Terminology](#terminology)
+ - [Content](#content)
+ - [(Cryptographic) hash](#cryptographic-hash)
+ - [Directory](#directory)
+ - [Origin](#origin)
+ - [Project](#project)
+ - [Release](#release)
+ - [Revision](#revision)
+ - [Opened endpoints](#opened-endpoints)
+
+<!-- markdown-toc end -->
+
+
+### Version
+
+Current version is 1.
+
+### Schema
+
+Api access is over https and accessed through [https://archive.softwareheritage.org/api/1/](https://archive.softwareheritage.org/api/).
+
+Data is sent and received as json.
+
+Example:
+``` shell
+$ curl -i https://archive.softwareheritage.org/api/1/stat/counters/
+HTTP/1.1 200 OK
+Date: Mon, 16 Jan 2017 10:57:56 GMT
+Server: Apache
+Content-Type: application/json
+Content-Length: 395
+Vary: Accept-Encoding
+Access-Control-Allow-Origin: *
+Connection: close
+
+{
+ "directory_entry_rev": 3039473,
+ "person": 13903080,
+ "entity": 7103795,
+ "skipped_content": 17864,
+ "entity_history": 7147753,
+ "revision_history": 720840448,
+ "revision": 703277184,
+ "directory": 2616883200,
+ "release": 5692900,
+ "origin": 49938216,
+ "directory_entry_dir": 2140887552,
+ "occurrence_history": 254274832,
+ "occurrence": 241899344,
+ "content": 3155739136,
+ "directory_entry_file": 3173807104
+}
+```
+
+#### Mimetype override
+
+The response output can be sent as yaml provided the client specifies
+it using the header field.
+
+For example:
+``` shell
+curl -i -H 'Accept: application/yaml' https://archive.softwareheritage.org/api/1/stat/counters/
+HTTP/1.1 200 OK
+Date: Mon, 16 Jan 2017 12:31:50 GMT
+Server: Apache
+Content-Type: application/yaml
+Content-Length: 372
+Access-Control-Allow-Origin: *
+Connection: close
+
+{content: 3155758336,
+ directory: 2616955136,
+ directory_entry_dir: 2140925824,
+ directory_entry_file: 3173833984,
+ directory_entry_rev: 3039473,
+ entity: 7103741,
+ entity_history: 7148121,
+ occurrence: 241887488,
+ occurrence_history: 254277584,
+ origin: 49939848,
+ person: 13898394,
+ release: 5693922,
+ revision: 703275840,
+ revision_history: 720842176,
+ skipped_content: 17864}
+```
+
+### Parameters
+
+Some API endpoints can be used with with local parameters. The url
+then needs to be adapted accordingly.
+
+For example:
+
+``` text
+https://archive.softwareheritage.org/api/1/<endpoint-name>?<field0>=<value0>&<field1>=<value1>
+```
+
+where:
+
+- field0 is an appropriate field for the <endpoint-name> and value0
+- field1 is an appropriate field for the <endpoint-name> and value1
+
+#### 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:
+
+``` shell
+$ curl https://archive.softwareheritage.org/api/1/stat/counters/\?fields\=content,directory,revision | jq
+{
+ "content": 3155739136,
+ "revision": 703277184,
+ "directory": 2616883200
+}
+```
+
+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 that error and a json
+response is sent with the detailed error.
+
+#### Bad request
+
+This means that the input is incorrect.
+
+Example:
+``` shell
+curl -i https://archive.softwareheritage.org/api/1/content/1/
+HTTP/1.1 400 BAD REQUEST
+Date: Mon, 16 Jan 2017 11:28:08 GMT
+Server: Apache
+Content-Type: application/json
+Content-Length: 44
+Connection: close
+
+{"error": "Invalid checksum query string 1"}
+```
+
+Here, the api content expects an hash identifier.
+
+#### Not found
+
+This means that the request is ok but we do not found the information
+the user requests.
+
+Example:
+
+``` shell
+curl -i https://archive.softwareheritage.org/api/1/content/04740277a81c5be6c16f6c9da488ca073b770d7f/
+HTTP/1.1 404 NOT FOUND
+Date: Mon, 16 Jan 2017 11:31:46 GMT
+Server: Apache
+Content-Type: application/json
+Content-Length: 77
+Connection: close
+
+{"error": "Content with 04740277a81c5be6c16f6c9da488ca073b770d7f not found."}
+```
+
+### Terminology
+
+You will find below the terminology the project swh uses.
+More details can be found
+on
+[swh's wiki glossary page](https://wiki.softwareheritage.org/index.php?title=Glossary).
+
+#### 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:
+
+- a Git repository
+- a directory containing tarballs
+- the history of a Debian package on snapshot.debian.org.
+
+#### 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:
+
+- a Git tag with its name
+- a tarball with its name
+- a Debian source package with its version number.
+
+#### Revision
+
+A "point in time" snapshot in the development history of a project.
+
+Also known as: Commit
+
+Examples:
+
+- a Git commit
+
+### Opened endpoints
+
+(may have to move to /api/1/)
+
+Below, you will find the opened endpoints. This will permit you to
+read information on the origin we load up until now.