Datatracker API Notes

Framework

This section describes the autogenrated read-only API towards the database tables. See also the 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:

https://svn.tools.ietf.org/svn/tools/ietfdb/trunk/ietf/doc/models.py
https://svn.tools.ietf.org/svn/tools/ietfdb/trunk/ietf/group/models.py
http://svn.tools.ietf.org/svn/tools/ietfdb/trunk/ietf/iesg/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):

https://datatracker.ietf.org/api/v1/group/group/
https://trac.tools.ietf.org/tools/ietfdb/browser/trunk/ietf/group/models.py

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

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:

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

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.

Personal API Keys

The datatracker has some API endpoints that uses Personal API keys, rather than username/password login, see for example details for /api/iesg/position further down on this page. 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:

{"e":"AQAB","kid":"BktSrsuM65vXGjy0iKDxDOG5zs3LWbJk3J5yaSjOUOA","kty":"RSA","n":"3PlUkbbBu3gu71yyZ2yNssQEU3dyDCcrRUzQr9xxojLuMLNrB6md6TEFOWglTWgk2sqAIo3-MwR5UUWjkrbo9wbrq18ATAdliDksQnShBYokOd91-QV4ZWtIIrSyF_jj4k_koVgKLtaMRpdjBq-EmPvQn4ZsQOCokSsB0GTClEBrUlQPXeXBkz0t4oBMstT1bBjtl_25I3gNQYo0l6xKVRcpvgicoeDcGkj42o393OD5Ug8yoejcXwiViK0YcQSfoaPPwEwQqX1C0Xwk4ogPaonrQ5l3T85HN5sAItkQ8pYYcGfJWIuhqqpyV3lgBMvVtRpHfdnnunzfaoaM56MTJQ"}

or alternatively:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA3PlUkbbBu3gu71yyZ2yN
ssQEU3dyDCcrRUzQr9xxojLuMLNrB6md6TEFOWglTWgk2sqAIo3+MwR5UUWjkrbo
9wbrq18ATAdliDksQnShBYokOd91+QV4ZWtIIrSyF/jj4k/koVgKLtaMRpdjBq+E
mPvQn4ZsQOCokSsB0GTClEBrUlQPXeXBkz0t4oBMstT1bBjtl/25I3gNQYo0l6xK
VRcpvgicoeDcGkj42o393OD5Ug8yoejcXwiViK0YcQSfoaPPwEwQqX1C0Xwk4ogP
aonrQ5l3T85HN5sAItkQ8pYYcGfJWIuhqqpyV3lgBMvVtRpHfdnnunzfaoaM56MT
JQIDAQAB
-----END PUBLIC KEY-----

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