{# Copyright The IETF Trust 2007, All Rights Reserved #}
{% extends "base.html" %}
{% load staticfiles %}
{% block title %}API Notes{% 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>

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

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

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

    </p>

    <h3>Documents</h3>

    <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

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

    <p>
      and then match the listed "resource_uri" of the results to the states listed for each
      document when you ask for
      <pre>
      $ curl 'https://datatracker.ietf.org/api/v1/doc/document/?limit=0&name__contains=-v6ops-'
      </pre>
    </p>

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

    <p>
      etc.
    </p>

    <h3>API Keys</h3>

    <p>

      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 Key</a>
      page when you are logged in.

    </p>

    <h3>Signing</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>

    <h3 id="iesg-position-api">IESG ballot position API</h3>

    <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: <tt>yes, noobj, block, discuss, abstain, recuse, norecord</tt>. </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:</li>
    </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>



    <h3 id="session-video-url-api">Set session video URL</h3>

    <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:</li>
    </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>

{% endblock %}