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 %}
  Developer documentation – GOV.UK Notify
{% endblock %}

{% block maincolumn_content %}

<h1 class="heading-large">
    Set up API integration
</h1>

<div class="grid-row">
    <div class="column-three-quarters">

        <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>
    </div>
</div>
        <p>Notify standard claims:</p>

        {{'''
{
  "typ": "JWT",
  "alg": "HS256"
}
        '''|syntax_highlight_json}}

        <p>Notify application specific:</p>
        {{"""
{
  iss: 'string', // service id
  iat: 0, // creation time in  epoch seconds (UTC)
  req: 'string', // signed request
  pay: 'string', // signed payload (POST requests only)
}
        """|syntax_highlight_json}}
<div class="grid-row">
    <div class="column-three-quarters">
        <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>

        {{ "GET /notification/1234"|syntax_highlight_json }}

        <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>
    </div>
</div>
        {{ "POST /notifications/sms"|syntax_highlight_json }}

        {{
          """
{
  'to': '+441234123123',
  'template': 1
}
          """|syntax_highlight_json
        }}
<div class="grid-row">
    <div class="column-three-quarters">
        <p>
          Where ‘to’ is the phone number and ‘template’ is the template ID to send.
        </p>

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


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

        {{ "GET /notifications/{id}"|syntax_highlight_json }}

        {{"""
{
  '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'
  }
}
        """|syntax_highlight_json }}

<div class="grid-row">
    <div class="column-three-quarters">
        <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://api.notify.works
        </p>

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

    </div>
</div>

{% endblock %}