From 9ea42824e8110e713171fc5b8b4e5b627f3428d1 Mon Sep 17 00:00:00 2001 From: Henrik Levkowetz Date: Thu, 13 Dec 2018 15:26:11 +0000 Subject: [PATCH] Added a description of the /doc//doc.json API to the /api/ index page, and also added a table-of-contents column. - Legacy-Id: 15813 --- ietf/templates/api/index.html | 467 ++++++++++++++++++---------------- 1 file changed, 254 insertions(+), 213 deletions(-) diff --git a/ietf/templates/api/index.html b/ietf/templates/api/index.html index 144072efb..17aedb6c4 100644 --- a/ietf/templates/api/index.html +++ b/ietf/templates/api/index.html @@ -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 %}

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

+

Framework API

+
+

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

+ 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): + 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 + 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. + Data is currently provided in JSON and XML format. Adding new formats is + fairly easy, if it should be found desriable. -

+

+
-

Documents

+

Framework API: Documents

+
+

-

+ Documents are listed at + /api/v1/doc/document/. - 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: - 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/ - + 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: + 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 - + 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: + 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 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 -

+

+ 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'
@@ -166,139 +168,178 @@
     

       etc.
     

+
-

Personal API Keys

+

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., + {% url 'ietf.doc.views_doc.document_json' name='draft-ietf-poised95-std-proc-3' %} + . + You can also specify an RFC: {% url 'ietf.doc.views_doc.document_json' name='rfc2026' %} + . + 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 - {% url 'ietf.doc.views_ballot.api_set_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 - {{ settings.UTILS_APIKEY_GUI_LOGIN_LIMIT_DAYS }} 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: - -

-

{{key.export_public}}

- -

or alternatively:

- - 
{{key.export_to_pem}}
+

+

+ 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 {% url 'ietf.doc.views_ballot.api_set_position' %} + . Access is limited to area directors. - A simplified IESG ballot position interface, intended for automation, is - available at {% url 'ietf.doc.views_ballot.api_set_position' %} - . Access is limited to area directors. - -

-

- The interface requires the use of a personal API key, which can be created at - {% url 'ietf.ietfauth.views.apikey_index' %} -

-

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

- 
+      

+      

+        The interface requires the use of a personal API key, which can be created at
+        {% url 'ietf.ietfauth.views.apikey_index' %}
+      

+      

+        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 + {% url 'ietf.meeting.views.api_set_session_video_url' %}. + 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 - {% url 'ietf.meeting.views.api_set_session_video_url' %}. - Access is limited to recording managers. - -

-

- The interface requires the use of a personal API key, which can be created at - {% url 'ietf.ietfauth.views.apikey_index' %} -

-

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

- 
+      

+      

+        The interface requires the use of a personal API key, which can be created at
+        {% url 'ietf.ietfauth.views.apikey_index' %}
+      

+      

+        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
     

+
+

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 + {% url 'ietf.doc.views_ballot.api_set_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 + {{ settings.UTILS_APIKEY_GUI_LOGIN_LIMIT_DAYS }} 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: + +

+

{{key.export_public}}

+ +

or alternatively:

+ + 
{{key.export_to_pem}}
+
+
+ +
+ + {% endblock %}