384 lines
17 KiB
HTML
384 lines
17 KiB
HTML
{# Copyright The IETF Trust 2007, All Rights Reserved #}
|
|
{% extends "base.html" %}
|
|
{% load static %}
|
|
{% block title %}API Notes{% endblock %}
|
|
{% block bodyAttrs %}data-bs-spy="scroll" data-bs-target="#affix"{% endblock %}
|
|
{% block content %}
|
|
|
|
<h2>Datatracker API Notes</h2>
|
|
<div class="col-md-11 bio-text">
|
|
<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.ietf.org/svn/tools/ietfdb/trunk/ietf/doc/models.py">https://svn.ietf.org/svn/tools/ietfdb/trunk/ietf/doc/models.py</a>
|
|
<br>
|
|
<a href="http://svn.ietf.org/svn/tools/ietfdb/trunk/ietf/group/models.py">https://svn.ietf.org/svn/tools/ietfdb/trunk/ietf/group/models.py</a>
|
|
<br>
|
|
<a href="http://svn.ietf.org/svn/tools/ietfdb/trunk/ietf/iesg/models.py">http://svn.ietf.org/svn/tools/ietfdb/trunk/ietf/iesg/models.py</a>
|
|
<br>
|
|
…
|
|
|
|
</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):
|
|
|
|
</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.ietf.org/trac/ietfdb/browser/trunk/ietf/group/models.py">https://trac.ietf.org/trac/ietfdb/browser/trunk/ietf/group/models.py</a>
|
|
|
|
</p>
|
|
<p>
|
|
|
|
Data is currently provided in JSON and XML format. Adding new formats is
|
|
fairly easy, if it should be found desriable.
|
|
|
|
</p>
|
|
</div>
|
|
|
|
<h4 id="framework-documents" class="anchor-target">Framework API: Documents</h4>
|
|
<div>
|
|
<p>
|
|
|
|
Documents are listed at
|
|
<a href="https://datatracker.ietf.org/api/v1/doc/document/">/api/v1/doc/document/</a>.
|
|
|
|
</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:
|
|
|
|
</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>
|
|
|
|
</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:
|
|
|
|
</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>
|
|
|
|
</p>
|
|
<p>
|
|
|
|
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>
|
|
|
|
<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>
|
|
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 either fetch and remember the different state groups of interest to you
|
|
with queries like
|
|
</p>
|
|
|
|
<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'
|
|
</pre>
|
|
|
|
|
|
<p>
|
|
and then match the listed "resource_uri" of the results to the states listed for each
|
|
document when you ask for
|
|
</p>
|
|
|
|
<pre>
|
|
$ curl 'https://datatracker.ietf.org/api/v1/doc/document/?limit=0&name__contains=-v6ops-'
|
|
</pre>
|
|
|
|
<p>
|
|
Or alternatively you could do a series of queries asking for matches to the RFC Editor
|
|
state first, then the IESG state, then the Stream state, and exclude earlier hits:
|
|
</p>
|
|
<pre>
|
|
$ curl 'https://datatracker.ietf.org/api/v1/doc/document/?limit=0&name__contains=-v6ops-&states__type__slug__in=draft-rfceditor' ...
|
|
$ curl 'https://datatracker.ietf.org/api/v1/doc/document/?limit=0&name__contains=-v6ops-&states__type__slug__in=draft-iesg' ...
|
|
</pre>
|
|
|
|
|
|
<p>
|
|
etc.
|
|
</p>
|
|
</div>
|
|
|
|
<h3 id="simplified-documents" class="anchor-target">Simplified documents API</h3>
|
|
<div>
|
|
<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="bi bi-box-arrow-up-right"></span></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="bi bi-box-arrow-up-right"></span></a>.
|
|
No API key is needed to access this.
|
|
|
|
</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>
|
|
|
|
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>
|
|
$ 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>
|
|
|
|
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>
|
|
$ 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="openid-connect" class="anchor-target">OpenID Connect</h3>
|
|
<div>
|
|
<p>
|
|
The datatracker supports <a href="https://openid.net/connect/">OpenID Connect</a>, but
|
|
not dynamic registration. The OpenID Connect Issuer is
|
|
<code> {{ settings.IDTRACKER_BASE_URL }}{% url 'ietf.api.urls.oidc_issuer' %} </code>
|
|
|
|
</p>
|
|
</div>
|
|
|
|
<h3 id="datatracker-version" class="anchor-target">Datatracker Version</h3>
|
|
<div>
|
|
<p>
|
|
The datatracker version and release/patch date is available as a JSON blob at
|
|
<code><a href="{% url 'ietf.api.views.version' %}">{% url 'ietf.api.views.version' %}</a></code>.
|
|
</p>
|
|
</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://datatracker.ietf.org/doc/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>
|
|
To verify a signature and get the verified data using Python with the
|
|
<a href="https://jwcrypto.readthedocs.io/en/latest/">jwcrypto</a> module,
|
|
you could do:
|
|
</p>
|
|
<pre>
|
|
from jwcrypto import jwk, jws
|
|
|
|
# ... receive json web signed data as 'data', used below ...
|
|
|
|
key = jwk.JWK()
|
|
key.import_from_pem(API_PUBLIC_KEY_PEM) # the key above
|
|
jwstoken = jws.JWS()
|
|
jwstoken.deserialize(data)
|
|
jwstoken.verify(key)
|
|
payload = jwstoken.payload
|
|
</pre>
|
|
</div>
|
|
|
|
</div>
|
|
|
|
<div class="col-md-1 d-print-none bs-docs-sidebar" id="affix">
|
|
<ul class="nav nav-pills nav-stacked small fixed" data-bs-spy="affix">
|
|
|
|
<li><a href="#framework">Framework API</a></li>
|
|
<li><a href="#framework-documents"> 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="#openid-connect">OpenID Connect</a></li>
|
|
<li><a href="#datatracker-version">Datatracker Version</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 %}
|
|
|