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

{% block page_title %}
  API documentation – GOV.UK Notify
{% endblock %}

{% block maincolumn_content %}

<h1 class="heading-large">
    Developer documentation
</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': '+447700900404',
  '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>
        {{"""
{
   'data':{
      'notification': {
         'id':1
      }
   }
}
        """|syntax_highlight_json }}


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

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

        {{"""
{
   'data':{
      '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.notifications.service.gov.uk/
        </p>

    </div>
</div>

{% endblock %}