106 lines
4 KiB
HTML
106 lines
4 KiB
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 %} |