Datatracker API Notes

Framework API

This section describes the autogenerated read-only API towards the database tables. See also the Internet-Draft submission API description and the IESG ballot position API description

The datatracker API uses tastypie 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. Browse the code tree for the models file in each app (such as ietf/doc/models.py, ietf/group/models.py, …).

The API top endpoint is at https://datatracker.ietf.org/api/v1. 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):

Data is currently provided in JSON and XML format. Adding new formats is fairly easy, if it should be found desirable.

Framework API: Documents

Documents are listed at /api/v1/doc/document/.

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:

https://datatracker.ietf.org/api/v1/doc/document/draft-ietf-eppext-keyrelay/

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:

api/v1/doc/document/?name=draft-ietf-eppext-keyrelay

To search for documents based on state, you need to know that documents have multiple orthogonal states:

You could use this in at least two alternative ways:

  1. You could either fetch and remember the different state groups of interest to you with queries like 
    $ 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'
    and then match the listed "resource_uri" of the results to the states listed for each document when you ask for 
    $ curl 'https://datatracker.ietf.org/api/v1/doc/document/?limit=0&name__contains=-v6ops-'
  2. 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: 
    $ 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' ...
    etc.

Simplified Documents API

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 doc.json, e.g., /doc/draft-ietf-poised95-std-proc-3/doc.json. You can also specify an RFC: /doc/rfc2026/doc.json. No API key is needed to access this.

The simplified document API takes no parameters, and is invoked with a HTTP GET.

IESG Ballot Position API

A simplified IESG ballot position interface, intended for automation, is available at /api/iesg/position. Access is limited to area directors.

The interface requires the use of a personal API key, which can be created at /accounts/apikey

The ballot position API takes the following parameters:

  • apikey (required) which is the personal API key hash
  • doc (required) which is the balloted document name
  • position (required) which is the position slug, one of: yes, noobj, block, discuss, abstain, recuse, norecord .
  • discuss (required if position is discuss) which is the discuss text
  • comment (optional) which is comment text

It returns an appropriate http result code, and a brief explanatory text message.

Here is an example: 

$ 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

Set Session Video URL

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 /api/meeting/session/video/url. Access is limited to recording managers.

The interface requires the use of a personal API key, which can be created at /accounts/apikey

The ballot position API takes the following parameters:

  • apikey (required) which is the personal API key hash
  • meeting (required) which is the meeting number
  • group (required) which is the group acronym
  • item (required) which is the chronological sequence number of the session (1 for a group's first session, 2 for the second, etc.)
  • url (required) which is the url that points to the video recording

It returns an appropriate http result code, and a brief explanatory text message.

Here is an example: 

$ 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

OpenID Connect

The datatracker supports OpenID Connect, but not dynamic registration. The OpenID Connect Issuer is https://datatracker.ietf.org/api/openid/

Datatracker Version

The datatracker version and release/patch date is available as a JSON blob at /api/version .

Personal API Keys

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 /api/iesg/position above. Personal API keys are available from your Account API Keys page when you are logged in.

Personal API keys have some characteristics you should be aware of:

  • 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.
  • 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.
  • 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 30 days. If you receive the error message "Too long since last regular login" you should do a regular login in order to activate access.

Signing Keys

When sending notifications to other APIs, the datatracker may sign information with a RFC 7515: JSON Web Signature (JWS) , using a public/private keypair with this public key:

{"crv":"P-256","kid":"rDq1i7qNqAmBkR2ymAEDaXO0RXAPzQAxsJXvh6TKyws","kty":"EC","x":"JtR62VGvG7b-qRxxJxk_2fPcPptqJsXMluVlZuukOlQ","y":"b0PSGnRDY2skQvjaX_42jMaYKWVRQgqVOBLVzth8MX4"}

or alternatively: 

b'-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEJtR62VGvG7b+qRxxJxk/2fPcPptq\nJsXMluVlZuukOlRvQ9IadENjayRC+Npf/jaMxpgpZVFCCpU4EtXO2Hwxfg==\n-----END PUBLIC KEY-----\n'

To verify a signature and get the verified data using Python with the jwcrypto module, you could do: 

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