datatracker/ietf/templates/submit/api_submission_info.html

{% extends "base.html" %}
{# Copyright The IETF Trust 2015-2022, All Rights Reserved #}
{% load origin ietf_filters %}
{% block title %}Draft submission API instructions{% endblock %}
{% block content %}
    {% origin %}
    <h1 class="mb-3">Draft submission API instructions</h1>
    <p>
        A simplified 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>Document replacement information cannot be supplied.</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 draft names replaced by this submission (optional)
        </li>
    </ul>
    <p>
        When a 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 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 draft is being or waiting to be processed.
        Any other state indicates that the draft completed validation. If the validation failed or if the
        draft was canceled after validation, the state will be <code>cancel</code>.
    </p>
    <p>
        Human-readable details of the 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 a 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 %}