altf4arnold/datatracker
1
0
Fork 0
Code Issues Pull requests Actions 3 Packages Projects Releases Wiki Activity

Added a description of the /doc//doc.json API to the /api/ index page, and also added a table-of-contents column.

Browse source 
- Legacy-Id: 15813
This commit is contained in:
Henrik Levkowetz 2018-12-13 15:26:11 +00:00
parent 3d75bad19f
commit 9ea42824e8
1 changed files with 254 additions and 213 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

467
ietf/templates/api/index.html
View file

@ -2,142 +2,144 @@
{% extends "base.html" %}
{% load staticfiles %}
{% block title %}API Notes{% endblock %}
{% block bodyAttrs %}data-spy="scroll" data-target="#affix"{% endblock %}
{% block content %}
<h2>Datatracker API Notes</h2>
<div class="col-md-1"></div>
<div class="col-md-11 bio-text">
<h3>Framework</h3>
<p>
This section describes the autogenrated read-only API towards the database tables. See also
the <a href="{% url 'ietf.submit.views.api_submit' %}">draft submission API description</a> and the
<a href="#iesg-position-api">IESG ballot position API description</a>
</p>
<p>
The datatracker API uses <a href="https://django-tastypie.readthedocs.org/">tastypie</a>
to generate an API which mirrors the Django ORM (Object Relational Mapping)
for the database. Each Django model class maps down to the SQL database
tables and up to the API. The Django models classes are defined in the
models.py files of the datatracker:
</p>
<h3 id="framework" class="anchor-target">Framework API</h3>
<div>
<p>
This section describes the autogenrated read-only API towards the database tables. See also
the <a href="{% url 'ietf.submit.views.api_submit' %}">draft submission API description</a> and the
<a href="#iesg-position-api">IESG ballot position API description</a>
</p>
<p>
The datatracker API uses <a href="https://django-tastypie.readthedocs.org/">tastypie</a>
to generate an API which mirrors the Django ORM (Object Relational Mapping)
for the database. Each Django model class maps down to the SQL database
tables and up to the API. The Django models classes are defined in the
models.py files of the datatracker:
</p>
<p>
<a href="http://svn.tools.ietf.org/svn/tools/ietfdb/trunk/ietf/doc/models.py">https://svn.tools.ietf.org/svn/tools/ietfdb/trunk/ietf/doc/models.py</a>
<br>
<a href="http://svn.tools.ietf.org/svn/tools/ietfdb/trunk/ietf/group/models.py">https://svn.tools.ietf.org/svn/tools/ietfdb/trunk/ietf/group/models.py</a>
<br>
<a href="http://svn.tools.ietf.org/svn/tools/ietfdb/trunk/ietf/iesg/models.py">http://svn.tools.ietf.org/svn/tools/ietfdb/trunk/ietf/iesg/models.py</a>
<br>
&hellip;
<p>
<a href="http://svn.tools.ietf.org/svn/tools/ietfdb/trunk/ietf/doc/models.py">https://svn.tools.ietf.org/svn/tools/ietfdb/trunk/ietf/doc/models.py</a>
<br>
<a href="http://svn.tools.ietf.org/svn/tools/ietfdb/trunk/ietf/group/models.py">https://svn.tools.ietf.org/svn/tools/ietfdb/trunk/ietf/group/models.py</a>
<br>
<a href="http://svn.tools.ietf.org/svn/tools/ietfdb/trunk/ietf/iesg/models.py">http://svn.tools.ietf.org/svn/tools/ietfdb/trunk/ietf/iesg/models.py</a>
<br>
&hellip;
</p>
<p>
</p>
<p>
The API top endpoint is at <a href="https://datatracker.ietf.org/api/v1/">https://datatracker.ietf.org/api/v1/</a>. The top
endpoint lists inferior endpoints, and thus permits some autodiscovery,
but there's really no substitute for looking at the actual ORM model classes.
Comparing a class in models.py with the equivalent endpoint may give
some clue (note that in the case of Group, it's a subclass of GroupInfo):
The API top endpoint is at <a href="https://datatracker.ietf.org/api/v1/">https://datatracker.ietf.org/api/v1/</a>. The top
endpoint lists inferior endpoints, and thus permits some autodiscovery,
but there's really no substitute for looking at the actual ORM model classes.
Comparing a class in models.py with the equivalent endpoint may give
some clue (note that in the case of Group, it's a subclass of GroupInfo):
</p>
<p>
</p>
<p>
<a href="https://datatracker.ietf.org/api/v1/group/group/">https://datatracker.ietf.org/api/v1/group/group/</a>
<br>
<a href="https://trac.tools.ietf.org/tools/ietfdb/browser/trunk/ietf/group/models.py">https://trac.tools.ietf.org/tools/ietfdb/browser/trunk/ietf/group/models.py</a>
<a href="https://datatracker.ietf.org/api/v1/group/group/">https://datatracker.ietf.org/api/v1/group/group/</a>
<br>
<a href="https://trac.tools.ietf.org/tools/ietfdb/browser/trunk/ietf/group/models.py">https://trac.tools.ietf.org/tools/ietfdb/browser/trunk/ietf/group/models.py</a>
</p>
<p>
</p>
<p>
Data is currently provided in JSON and XML format. Adding new formats is
fairly easy, if it should be found desriable.
Data is currently provided in JSON and XML format. Adding new formats is
fairly easy, if it should be found desriable.
</p>
</p>
</div>
<h3>Documents</h3>
<h4 id="framework-documents" class="anchor-target">Framework API: Documents</h4>
<div>
<p>
<p>
Documents are listed at
<a href="https://datatracker.ietf.org/api/v1/doc/document/">/api/v1/doc/document/</a>.
Documents are listed at
<a href="https://datatracker.ietf.org/api/v1/doc/document/">/api/v1/doc/document/</a>.
</p>
<p>
</p>
<p>
In general, individual database objects are represented in the api with a path
composed of the model collection, the object name, and the object key. Most
objects have simple numerical keys, but documents have the document name as
key. Take draft-ietf-eppext-keyrelay. Documents have a model 'Document' which
is described in the 'doc' models.py file. Assembling the path components
'doc', 'document' (lowercase!) and 'draft-ietf-eppext-keyrelay', we get the
URL:
In general, individual database objects are represented in the api with a path
composed of the model collection, the object name, and the object key. Most
objects have simple numerical keys, but documents have the document name as
key. Take draft-ietf-eppext-keyrelay. Documents have a model 'Document' which
is described in the 'doc' models.py file. Assembling the path components
'doc', 'document' (lowercase!) and 'draft-ietf-eppext-keyrelay', we get the
URL:
</p>
<p>
</p>
<p>
<a href="https://datatracker.ietf.org/api/v1/doc/document/draft-ietf-eppext-keyrelay/">
https://datatracker.ietf.org/api/v1/doc/document/draft-ietf-eppext-keyrelay/
</a>
https://datatracker.ietf.org/api/v1/doc/document/draft-ietf-eppext-keyrelay/
</a>
</p>
<p>
</p>
<p>
If you instead do a search for this document, you will get a machine-readable
search result, which is composed of some meta-information about the search,
and a list with one element:
If you instead do a search for this document, you will get a machine-readable
search result, which is composed of some meta-information about the search,
and a list with one element:
</p>
<p>
</p>
<p>
<a href="https://datatracker.ietf.org/api/v1/doc/document/?name=draft-ietf-eppext-keyrelay">
api/v1/doc/document/?name=draft-ietf-eppext-keyrelay
</a>
api/v1/doc/document/?name=draft-ietf-eppext-keyrelay
</a>
</p>
<p>
</p>
<p>
To search for documents based on state, you need to know that documents have
multiple orthogonal states:
To search for documents based on state, you need to know that documents have
multiple orthogonal states:
</p>
<ul>
<li>
If a document has an rfc-editor state, you can select for it by asking for e.g.
<a href="https://datatracker.ietf.org/api/v1/doc/document/?limit=0&name__contains=-v6ops-&states__type__slug__in=draft-rfceditor">
v6ops documents which match 'states__type__slug__in=draft-rfceditor'
</a>
</li>
</p>
<ul>
<li>
If a document has an rfc-editor state, you can select for it by asking for e.g.
<a href="https://datatracker.ietf.org/api/v1/doc/document/?limit=0&name__contains=-v6ops-&states__type__slug__in=draft-rfceditor">
v6ops documents which match 'states__type__slug__in=draft-rfceditor'
</a>
</li>
<li>
If a document has an IESG state, you can select for it by asking for e.g.
<a href="https://datatracker.ietf.org/api/v1/doc/document/?name__contains=-v6ops&states__type__slug__in=draft-iesg">
v6ops documents which match 'states__type__slug__in=draft-iesg'
</a>
</li>
<li>
If a document has an IESG state, you can select for it by asking for e.g.
<a href="https://datatracker.ietf.org/api/v1/doc/document/?name__contains=-v6ops&states__type__slug__in=draft-iesg">
v6ops documents which match 'states__type__slug__in=draft-iesg'
</a>
</li>
<li>
If a document has a WG state, you can select for it by asking for
documents which match 'states__type__slug__in=draft-stream-ietf'
(but without additional filters, that's going to be a lot of documents)
</li>
<li>
If a document has a WG state, you can select for it by asking for
documents which match 'states__type__slug__in=draft-stream-ietf'
(but without additional filters, that's going to be a lot of documents)
</li>
<li>
States which match 'states__type__slug__in=draft' describe the basic
Active/Expired/Dead whatever state of the draft.
</li>
</ul>
<li>
States which match 'states__type__slug__in=draft' describe the basic
Active/Expired/Dead whatever state of the draft.
</li>
</ul>
<p>
You could use this in at least two alternative ways:
</p>
<p>
You could use this in at least two alternative ways:
</p>
<p>
You could either fetch and remember the different state groups of interest to you
with queries like
</p>
<p>
You could either fetch and remember the different state groups of interest to you
with queries like
</p>
<pre>
<pre>
$ curl 'https://datatracker.ietf.org/api/v1/doc/state/?format=json&limit=0&type__slug__in=draft-rfceditor'
$ curl 'https://datatracker.ietf.org/api/v1/doc/state/?format=json&limit=0&type__slug__in=draft-iesg'
$ curl 'https://datatracker.ietf.org/api/v1/doc/state/?format=json&limit=0&type__slug__in=draft-stream-ietf'
@ -166,139 +168,178 @@
<p>
etc.
</p>
</div>
<h3 id="personal-api-keys" class="anchor-target">Personal API Keys</h3>
<h3 id="simplified-documents" class="anchor-target">Simplified documents API</h3>
<div>
<p>
<p>
A simplified Documents API, intended for cases where only a limited set of
document attributes are necessary for an application is
available for all documents at the relative url <code>doc.json</code>, e.g.,
<code>{% url 'ietf.doc.views_doc.document_json' name='draft-ietf-poised95-std-proc-3' %}</code>
<a href="{% url 'ietf.doc.views_doc.document_json' name='draft-ietf-poised95-std-proc-3' %}"><span class="fa fa-external-link"/></a>.
You can also specify an RFC: <code>{% url 'ietf.doc.views_doc.document_json' name='rfc2026' %}</code>
<a href="{% url 'ietf.doc.views_doc.document_json' name='rfc2026' %}"><span class="fa fa-external-link"/></a>.
No API key is needed to access this.
The datatracker has some API endpoints that uses Personal API keys,
rather than username/password login, see for example details for
<code>{% url 'ietf.doc.views_ballot.api_set_position' %}</code> further
down on this page. Personal API keys are available from your <a
href="{% url 'ietf.ietfauth.views.apikey_index'%}"> Account API Keys</a>
page when you are logged in.
</p>
<p>
Personal API keys have some characteristics you should be aware of:
</p>
<ul>
<li>
Each API key is valid only for a specific endpoint. If you try to use a key for
a different API endpoint than it's created for, it will not work.
</li>
<li>
The API keys will cause you to be given access with the datatracker
roles you have, thus giving you appropriate access to the various
API endpoints according to the role limitations indicated for each
endpoint.
</li>
<li>
An API key will only give you access to its related endpoint if you have logged
in to the datatracker using your regular login and password during the last
{{ settings.UTILS_APIKEY_GUI_LOGIN_LIMIT_DAYS }} days. If you receive the
error message "<code>Too long since last regular login</code>" you should do
a regular login in order to activate access.
</li>
</ul>
<h3 id="signing-keys" class="anchor-target">Signing Keys</h3>
<p>
When sending notifications to other APIs, the datatracker may sign
information with a <a href="https://tools.ietf.org/html/rfc7515">RFC
7515: JSON Web Signature (JWS)</a>, using a public/private keypair with
this public key:
</p>
<p><code>{{key.export_public}}</code></p>
<p>or alternatively:</p>
<pre>{{key.export_to_pem}}</pre>
</p>
<p>
The simplified document API takes no parameters, and is invoked with a HTTP GET.
</p>
</div>
<h3 id="iesg-position-api" class="anchor-target">IESG ballot position API</h3>
<div>
<p>
<p>
A simplified IESG ballot position interface, intended for automation, is
available at <code>{% url 'ietf.doc.views_ballot.api_set_position' %}
</code>. Access is limited to area directors.
A simplified IESG ballot position interface, intended for automation, is
available at <code>{% url 'ietf.doc.views_ballot.api_set_position' %}
</code>. Access is limited to area directors.
</p>
<p>
The interface requires the use of a personal API key, which can be created at
<a href="{% url 'ietf.ietfauth.views.apikey_index' %}">{% url 'ietf.ietfauth.views.apikey_index' %}</a>
</p>
<p>
The ballot position API takes the following parameters:
</p>
<ul>
<li><code>apikey</code> (required) which is the personal API key hash</li>
<li><code>doc</code> (required) which is the balloted document name</li>
<li><code>position</code> (required) which is the position slug, one of: <span class="samp">yes, noobj, block, discuss, abstain, recuse, norecord</span>. </li>
<li><code>discuss</code> (required if position is 'discuss') which is the discuss text</li>
<li><code>comment</code> (optional) which is comment text</li>
</ul>
<p>
It returns an appropriate http result code, and a brief explanatory text message.
</p>
<p>
Here is an example:
</p>
<pre>
</p>
<p>
The interface requires the use of a personal API key, which can be created at
<a href="{% url 'ietf.ietfauth.views.apikey_index' %}">{% url 'ietf.ietfauth.views.apikey_index' %}</a>
</p>
<p>
The ballot position API takes the following parameters:
</p>
<ul>
<li><code>apikey</code> (required) which is the personal API key hash</li>
<li><code>doc</code> (required) which is the balloted document name</li>
<li><code>position</code> (required) which is the position slug, one of: <span class="samp">yes, noobj, block, discuss, abstain, recuse, norecord</span>. </li>
<li><code>discuss</code> (required if position is 'discuss') which is the discuss text</li>
<li><code>comment</code> (optional) which is comment text</li>
</ul>
<p>
It returns an appropriate http result code, and a brief explanatory text message.
</p>
<p>
Here is an example:
</p>
<pre>
$ curl -S -F "apikey=AwAAABVR3D5GHkVMhspKSxBCVknGMmqikNIhT85kSnghjaV_pYy26WV92mm-jpdi" -F "doc=draft-ietf-lamps-eai-addresses" -F "position=noobj" -F "comment=Comment text" https://datatracker.ietf.org/api/iesg/position
Done
</pre>
</div>
<h3 id="session-video-url-api" class="anchor-target">Set session video URL</h3>
<div>
<p>
<p>
This interface is intended for Meetecho, to provide a way to set the
URL of a video recording for a given session. It is available at
<code>{% url 'ietf.meeting.views.api_set_session_video_url' %}</code>.
Access is limited to recording managers.
This interface is intended for Meetecho, to provide a way to set the
URL of a video recording for a given session. It is available at
<code>{% url 'ietf.meeting.views.api_set_session_video_url' %}</code>.
Access is limited to recording managers.
</p>
<p>
The interface requires the use of a personal API key, which can be created at
<a href="{% url 'ietf.ietfauth.views.apikey_index' %}">{% url 'ietf.ietfauth.views.apikey_index' %}</a>
</p>
<p>
The ballot position API takes the following parameters:
</p>
<ul>
<li><code>apikey</code> (required) which is the personal API key hash</li>
<li><code>meeting</code> (required) which is the meeting number</li>
<li><code>group</code> (required) which is the group acronym</li>
<li><code>item</code> (required) which is the chronological sequence number of the session (1 for a group's first session, 2 for the second, etc.)</li>
<li><code>url</code> (required) which is the url that points to the video recording</li>
</ul>
<p>
It returns an appropriate http result code, and a brief explanatory text message.
</p>
<p>
Here is an example:
</p>
<pre>
</p>
<p>
The interface requires the use of a personal API key, which can be created at
<a href="{% url 'ietf.ietfauth.views.apikey_index' %}">{% url 'ietf.ietfauth.views.apikey_index' %}</a>
</p>
<p>
The ballot position API takes the following parameters:
</p>
<ul>
<li><code>apikey</code> (required) which is the personal API key hash</li>
<li><code>meeting</code> (required) which is the meeting number</li>
<li><code>group</code> (required) which is the group acronym</li>
<li><code>item</code> (required) which is the chronological sequence number of the session (1 for a group's first session, 2 for the second, etc.)</li>
<li><code>url</code> (required) which is the url that points to the video recording</li>
</ul>
<p>
It returns an appropriate http result code, and a brief explanatory text message.
</p>
<p>
Here is an example:
</p>
<pre>
$ curl -S -F "apikey=DgAAAMLSi3coaE5TjrRs518xO8eBRlCmFF3eQcC8_SjUTtRGLGiJh7-1SYPT5WiS" -F "meeting=101" -F "group=mptcp" -F "item=1" -F "url=https://foo.example/beer/mptcp" https://datatracker.ietf.org/api/meeting/session/video/url
Done
</pre>
</div>
<h3 id="personal-api-keys" class="anchor-target">Personal API Keys</h3>
<div>
<p>
The datatracker has some API endpoints that uses Personal API keys,
rather than having general access or requiring username/password
login, see for example details for
<code>{% url 'ietf.doc.views_ballot.api_set_position' %}</code>
<a href="#iesg-position-api">above</a>.
Personal API keys are available from your
<a href="{% url 'ietf.ietfauth.views.apikey_index'%}">Account API Keys</a>
page when you are logged in.
</p>
<p>
Personal API keys have some characteristics you should be aware of:
</p>
<ul>
<li>
Each API key is valid only for a specific endpoint. If you try to use a key for
a different API endpoint than it's created for, it will not work.
</li>
<li>
The API keys will cause you to be given access with the datatracker
roles you have, thus giving you appropriate access to the various
API endpoints according to the role limitations indicated for each
endpoint.
</li>
<li>
An API key will only give you access to its related endpoint if you have logged
in to the datatracker using your regular login and password during the last
{{ settings.UTILS_APIKEY_GUI_LOGIN_LIMIT_DAYS }} days. If you receive the
error message "<code>Too long since last regular login</code>" you should do
a regular login in order to activate access.
</li>
</ul>
</div>
<h3 id="signing-keys" class="anchor-target">Signing Keys</h3>
<div>
<p>
When sending notifications to other APIs, the datatracker may sign
information with a <a href="https://tools.ietf.org/html/rfc7515">RFC
7515: JSON Web Signature (JWS)</a>, using a public/private keypair with
this public key:
</p>
<p><code>{{key.export_public}}</code></p>
<p>or alternatively:</p>
<pre>{{key.export_to_pem}}</pre>
</div>
</div>
<div class="col-md-1 hidden-print bs-docs-sidebar" id="affix">
<ul class="nav nav-pills nav-stacked small fixed" data-spy="affix">
<li><a href="#framework">Framework API</a></li>
<li><a href="#framework-documents">&nbsp; Framework API: Documents</a></li>
<li><a href="#simplified-documents">Simplified documents API</a></li>
<li><a href="#iesg-position-api">IESG ballot position API</a></li>
<li><a href="#session-video-url-api">Set session video URL API</a></li>
<li><a href="#personal-api-keys">Personal API keys</a></li>
<li><a href="#signing-keys">Signing keys</a></li>
</ul>
</div>
{% endblock %}