notifications-admin/app/templates/views/documentation.html

{% extends "withnav_template.html" %}
{% from "components/page-footer.html" import page_footer %}
{% from "components/api-key.html" import api_key %}

{% block page_title %}
GOV.UK Notify | API keys and documentation
{% endblock %}

{% block maincolumn_content %}

<h1 class="heading-large">
    Developer documentation
</h1>

<div class="grid-row">
    <div class="column-two-thirds">

        <h2 class="heading-medium">
            How to integrate GOV.UK Notify into your service
        </h2>

        <p>
            Notify provides an API that allows the creation of text notifications and the ability to get the status of a
            sent notification.
        </p>

        <h3 class="heading-medium">
            API authentication
        </h3>

        <p>
            Notify uses <a href="https://jwt.io/">JSON Web Tokens (JWT)</a> for authentication.
            JWT tokens have a series of claims, standard and application specific.
        </p>

        <p>Notify standard claims:</p>

        <pre>
            typ: JWT
            alg: HS256
        </pre>

        <p>Notify application specific:</p>
        <pre>
            iss: service id
            iat: creation time in  epoch seconds (UTC)
            req: signed request
            pay: signed payload (POST requests only)
        </pre>

        <p>Notify API tokens sign both the request being made, and for POST requests, the payload.</p>

        <p>
            The signing algorithm is HMAC signature, using provided key SHA256 hashing algorithm.
        </p>

        <p>Request signing is of the form HTTP METHOD PATH.</p>

        <code>GET /notification/1234</code>

        <p></p>

        <p>Payload signing requires the actual payload to be signed, NOT the JSON object. Serialize the object first
            then sign the serialized object.</p>

        <h3 class="heading-medium">
            API endpoints
        </h3>

        <p>To create a text notification</p>

        <code>POST /notifications/sms</code>

        <p>
            <pre>
                {
                    'to': '+441234123123',
                    'template': 1
                }
            </pre>
        Where 'to' is the phone number and 'template' is the template id to send.
        </p>

        <p>
            Response:
            <pre>
                {
                    'notification':
                    {
                        'to': '+441234123123',
                        'createdAt': '2016-01-01T09:00:00.999999Z',
                        'status': 'created',
                        'id': 1,
                        'message': '....',
                        'method': 'sms',
                        'jobId': 1
                    }
                }
            </pre>
        </p>

        <p>To get the status of a text notification</p>

        <p>
            <code>
                GET /notifications/{id}
            </code>
        </p>

        <p>
            <pre>
            {
                'notification':
                {
                    'status': 'sent',
                    'createdAt': '2016-01-01T09:00:00.999999Z',
                    'to': '+447827992607',
                    'method': 'sms',
                    'sentAt': '2016-01-01T09:01:00.999999Z',
                    'id': 1,
                    'message': '...',
                    'jobId': 1,
                    'sender': 'sms-partner'
                }
            }
            </pre>
        </p>

        <h2 class="heading-medium">
            API client libraries
        </h2>

        <p>A python client library is support by the Notify team:</p>

        <p>
            <a href="https://github.com/alphagov/notifications-python-client">GOV.UK Notify Python client</a>
        </p>

        <p>
            This provides example code for calling the API and for constructing the API tokens.
        </p>

        <h2 class="heading-medium">API code</h2>

        <p>Notify API code is open sourced at:</p>

        <p>
            <a href="https://github.com/alphagov/notifications-api">GOV.UK Notify API</a>
        </p>

        <h2 class="heading-medium">API endpoint</h2>

        <p>
            https://www.notify.works/api/endpoint
        </p>

        <p>
            <a href="{{ url_for('.api_keys', service_id=service_id) }}">API keys for your service</a>
        </p>

    </div>
</div>

{% endblock %}