Updated documentation for api keys and for the developer documentation page.

app/templates/views/api-keys.html

@@ -12,14 +12,14 @@
   </h1>
 
   <p>
-    To connect to the API you will need to send your service ID, encrypted with
-    an API key. The API key stays secret.
+    To connect to the API you will need to create an API Key. Each service can have multiple API Keys to allow
+    for test and live environments.
   </p>
 
   <p>
-    There are client libraries available which can do this for you. See
-    <a href="{{ url_for(".documentation", service_id=service_id) }}">the
-    developer documentation</a> for more information.
+    API usage is described in
+    <a href="{{ url_for('.documentation', service_id=service_id) }}">the
+    developer documentation</a>.
   </p>
 
   <h2 class="api-key-name">

app/templates/views/documentation.html

@@ -3,47 +3,162 @@
 {% from "components/api-key.html" import api_key %}
 
 {% block page_title %}
-  GOV.UK Notify | API keys and documentation
+GOV.UK Notify | API keys and documentation
 {% endblock %}
 
 {% block maincolumn_content %}
 
-    <div class="grid-row">
-      <div class="column-two-thirds">
+<div class="grid-row">
+    <div class="column-two-thirds">
 
         <h1 class="heading-xlarge">
-          Developer documentation
+            Developer documentation
         </h1>
 
         <h2 class="heading-medium">
-          How to integrate GOV.UK Notify into your service
+            How to integrate GOV.UK Notify into your service
         </h2>
 
         <p>
-          blah blah blah this is where we tell you how the API works
+            Notify provides an API that allows the creation of text notifications and the ability to get the status of a
+            sent notification.
         </p>
 
-        <h2 class="heading-medium">Repositories</h2>
+        <h3 class="heading-medium">
+            API authentication
+        </h3>
 
         <p>
-          <a href="https://github.com/alphagov/notifications-api">GOV.UK Notify API</a>
+            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>
-          <a href="https://github.com/alphagov/notify-api-client">GOV.UK Notify Python client</a>
+            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/notify-api-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
+            https://www.notify.works/api/endpoint
         </p>
 
         <p>
-          <a href="{{ url_for('.api_keys', service_id=service_id) }}">API keys for your service</a>
+            <a href="{{ url_for('.api_keys', service_id=service_id) }}">API keys for your service</a>
         </p>
 
-      </div>
     </div>
+</div>
 
 {% endblock %}