api_submission_info.html

{% extends "base.html" %}
{# Copyright The IETF Trust 2015-2022, All Rights Reserved #}
{% load origin ietf_filters %}
{% block title %}I-D submission API instructions{% endblock %}
{% block content %}
    {% origin %}
    <h1 class="mb-3">Internet-Draft submission API instructions</h1>
    <p>
        A simplified Internet-Draft submission interface, intended for automation,
        is available at <code>{% url 'ietf.submit.views.api_submission' %}</code>.
    </p>
    <p>
        The interface accepts only XML uploads that can be processed on the server, and
        requires the user to have a datatracker account.  A successful submit still requires
        the same email confirmation round-trip as submissions done through the regular
        <a href="{% url 'ietf.submit.views.upload_submission' %}">submission tool</a>.
    </p>
    <p>
        This interface does not provide all the options which the regular submission tool does.
        Some limitations:
    </p>
    <ul>
        <li>Only XML-only uploads are supported, not text or combined.</li>
        <li>
            The server expects <code>multipart/form-data</code>, supported by <code>curl</code> but <b>not</b> by <code>wget</code>.
        </li>
    </ul>
    <p>
        It takes the following parameters:
    </p>
    <ul>
        <li>
            <code>user</code> which is the user login (required)
        </li>
        <li>
            <code>xml</code>, which is the submitted file (required)
        </li>
        <li>
            <code>replaces</code>, a comma-separated list of Internet-Draft names replaced by this submission (optional)
        </li>
    </ul>
    <p>
        When an Internet-Draft is submitted, basic checks are performed immediately and an HTTP response
        is sent including an appropriate http result code and JSON data describing the outcome.
    </p>
    <p>
        On success, the JSON data format is
    </p>
    <pre class="border p-3 mb-3">
{
  "id": "123",
  "name": "draft-just-submitted",
  "rev": "00",
  "status_url": "{% absurl 'ietf.submit.views.api_submission_status' submission_id='123' %}"
}</pre>
    <p>
        On error, the JSON data format is
    </p>
    <pre class="border p-3 mb-3">
{
  "error": "Description of the error"
}</pre>
    <p>
        If the basic checks passed and a successful response is sent, the Internet-Draft is queued for further
        processing. Its status can be monitored by issuing GET requests to the <code>status_url</code>
        indicated in the JSON response. This URL will respond with JSON data in the format
    </p>
    <pre class="border p-3 mb-3">
{
  "id": "123",
  "state": "validating"
}</pre>
    <p>
        The state <code>validating</code> indicates that the Internet-Draft is being or waiting to be processed.
        Any other state indicates that the Internet-Draft completed validation. If the validation failed or if the
        Internet-Draft was canceled after validation, the state will be <code>cancel</code>.
    </p>
    <p>
        Human-readable details of the Internet-Draft's status and history can be found at
        {% absurl 'ietf.submit.views.submission_status' submission_id='123' %}
        (replacing <code>123</code> with the <code>id</code> for the submission).)
    </p>
    <p>
        Here is an example of submitting an Internet-Draft and polling its status through the API:
    </p>
    <pre class="border p-3">
$ curl -s -F "user=user.name@example.com" -F "xml=@~/draft-user-example.xml" -F "replaces=draft-user-replaced-draft"  {% absurl 'ietf.submit.views.api_submission' %} | jq
{
  "id": "126375",
  "name": "draft-user-example",
  "rev": "00",
  "status_url": "{% absurl 'ietf.submit.views.api_submission_status' submission_id='126375' %}"
}

$ curl -s {% absurl 'ietf.submit.views.api_submission_status' submission_id='126375' %} | jq
{
  "id": "126375",
  "state": "validating"
}

$ curl -s {% absurl 'ietf.submit.views.api_submission_status' submission_id='126375' %} | jq
{
  "id": "126375",
  "state": "auth"
}</pre>
{% endblock %}