doc.html

{% extends "nm2-base.html" %}
{% load i18n %}

{% block content %}

<h1>Debian New Member - API documentation</h2>

<h2>Authentication</h2>

<p>If you are using a browser Debian SSO authentication works as usual. If
you are using a script and public access is not enough for you, you can use
<a href="{% url 'apikeys:list' %}">API keys</a>. For example:
<pre>
curl -H "Api-Key: YourAPIKeyValue" {% url 'api:status' %}
</pre>
</p>

<h2>{% url 'api:people' %}</h2>

<p>Lists people known to the system.</p>

<p>GET parameters can be used to filter results:</p>

<table class="table table-sm">
    <thead>
        <tr><th>key</th><th>value</th></tr>
    </thead>
    <tbody>
        <tr><td>cn</td><td>First name</td></tr>
        <tr><td>mn</td><td>Middle name</td></tr>
        <tr><td>sn</td><td>Last name</td></tr>
        <tr><td>email</td><td>E-Mail</td></tr>
        <tr><td>uid</td><td>Debian account name</td></tr>
        <tr><td>fpr</td><td>OpenPGP key fingerprint</td></tr>
        <tr><td>status</td><td>Status in the project (as a tag like 'dd_u' or 'dm')</td></tr>
        <tr><td>fd_comment</td><td>FD comments (ignored unless authenticated as
                FD member or DAM)</td></tr>
    </tbody>
</table>

<p>All matches are case insensitive full string matches, except for 'status'
which matches exactly, and 'fpr' which matches case insensitively at the end of
the fingerprint.</p>

<p>For cn, mn, sn, email and uid, you can use <code>/value/</code> to match with a
case insensitive regular expression.</p>

<p>Results will only contain an 'email' field if the request is made by
authenticated people.</p>

<p>Example:</p>
<pre>
$ curl https://nm.debian.org/api/people?cn=/nric/
{
 "r": [
  {
   "status": "dd_u", 
   "uid": "gareuselesinge", 
   "created": "1136678400", 
   "url": "/public/person/gareuselesinge", 
   "mn": null, 
   "sn": "Tassi", 
   "fpr": "60D04388E3853643807B9507EE491C3E0123F2F2", 
   "status_changed": "1136678400", 
   "fullname": "Enrico Tassi", 
   "cn": "Enrico"
  }, 
  {
   "status": "dd_u", 
   "uid": "enrico", 
   "created": "1003968000", 
   "url": "/public/person/enrico", 
   "mn": null, 
   "sn": "Zini", 
   "fpr": "66B4DFB68CB24EBBD8650BC4F4B4B0CC797EBFAB", 
   "status_changed": "1003968000", 
   "fullname": "Enrico Zini", 
   "cn": "Enrico"
  }
 ]
}
</pre>

<h2>{% url 'api:status' %}</h2>

<p>Query the status of one, many or all people in the database</p>

<p>GET parameters can be used to control the results:</p>

<table class="table table-sm">
    <thead>
      <tr><th>Auth required</th><th>key</th><th>value</th></tr>
    </thead>
    <tbody>
    <tr><td>yes</td><td>status</td>
      <td>Get a list of all the people with the given status. You can use a
        comma-separated list of statuses, like <code>dd_nu,dd_u</code>.</td></tr>
    <tr><td>no</td><td>person</td>
      <td>Get the status of the person with the given SSO username. You can use
        a comma-separated list of SSO usernames.</td></tr>
    </tbody>
</table>

<p>If no parameter is specified, it returns a list of all known people. This
requires authentication.</p>

<p>Alternatively, you can POST a JSON list of SSO usernames, and get a reply
with the status of those people. This does not require authentication.</p>

<p>Example:</p>

<pre>
$ curl https://nm.debian.org/api/status --data '["enrico@debian.org","example-guest@users.alioth.debian.org"]'
{
 "people": {
  "enrico@debian.org": {
   "status": "dd_u", 
   "is_am": true
  },
  "example-guest@users.alioth.debian.org": {
   "status": "dm", 
  }
 }
}
</pre>


{% endblock %}