darkhelm/notifications-admin
1
0
Fork 0
mirror of https://github.com/GSA/notifications-admin.git synced 2025-12-10 23:23:27 -05:00
Code Issues Packages Projects Releases Wiki Activity

Docs: tidy up indentation in JSON examples

Browse Source
This commit is contained in:
Henry Hadlow
2016-05-12 15:37:42 +01:00
parent 860b4fd8cc
commit 8e85b22157
1 changed files with 99 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files

191
docs/index.md
View File

@@ -32,14 +32,14 @@ To find out more about GOV.UK Notify, see the [Government as a Platform](https:/
<h2 id="beforestart">Before you start</h2>
1. Register for a [GOV.UK Notify](https://www.notifications.service.gov.uk/) account.
1. Register for a [GOV.UK Notify](https://www.notifications.service.gov.uk/) account.
You'll need an email address from a local or central government organisation and your mobile phone for 2-factor authentication.
2. Add a template so you can send text and email notifications.
2. Add a template so you can send text and email notifications.
**Note:** A template is required even if you send notifications with the GOV.UK Notify API.
You can personalise the template using double brackets for placeholders. For example:
> Dear ((name)),
@@ -49,8 +49,8 @@ To find out more about GOV.UK Notify, see the [Government as a Platform](https:/
3. Create an API key. This will be used to connect to the GOV.UK Notify API.
Each service can have multiple API keys. This allows you to integrate several systems, each with its own key. You can also have separate keys for your development and test environments.
**Important:** API keys are secret, so save them somewhere safe. Don't commit API keys to public source code repositories.
**Important:** API keys are secret, so save them somewhere safe. Don't commit API keys to public source code repositories.
<h2 id="integrate_Notify">Integrate the GOV.UK Notify API into your service</h2>
@@ -58,13 +58,13 @@ There are 2 ways to integrate the API into your service:
* use one of the client libraries provided by GOV.UK Notify (see the Usage section in the Readme files):
* [Python library](https://github.com/alphagov/notifications-python-client)
* [PHP library] (https://github.com/alphagov/notifications-php-client)
* [Java library] (https://github.com/alphagov/notifications-java-client)
* [PHP library](https://github.com/alphagov/notifications-php-client)
* [Java library](https://github.com/alphagov/notifications-java-client)
* develop your own integration to produce requests in the correct format
<h3 id="AuthRequests">Authenticate requests</h3>
GOV.UK Notify uses [JSON Web Tokens (JWT)](https://jwt.io/introduction/) for authentication and identification. The GOV.UK Notify client libraries encode and decode JSON Web Tokens when making requests to the GOV.UK Notify API. If you don’t use one of these libraries, you must manually create tokens yourself.
GOV.UK Notify uses [JSON Web Tokens (JWT)](https://jwt.io/introduction/) for authentication and identification. The GOV.UK Notify client libraries encode and decode JSON Web Tokens when making requests to the GOV.UK Notify API. If you don’t use one of these libraries, you must manually create tokens yourself.
For examples of how to encode and decode JSON Web Tokens, see [authentication.py](https://github.com/alphagov/notifications-python-client/blob/master/notifications_python_client/authentication.py) in the GOV.UK Notify Python client library, or the appropriate [PHP] (https://github.com/alphagov/notifications-php-client) or [Java] (https://github.com/alphagov/notifications-java-client) client library.
@@ -95,7 +95,7 @@ GOV.UK Notify application-specific claims (these form the JSON Web Token payload
}
```
The header and payload are Base64Url encoded.
The header and payload are Base64Url encoded.
The verify signature is created using the HMAC SHA256 hashing algorithm.
@@ -103,7 +103,7 @@ The verify signature is created using the HMAC SHA256 hashing algorithm.
GOV.UK Notify supports the following client libraries:
* [GOV.UK Notify Python library](https://github.com/alphagov/notifications-python-client)
* [GOV.UK Notify Python library](https://github.com/alphagov/notifications-python-client)
* [GOV.UK Notify PHP library] (https://github.com/alphagov/notifications-php-client)
* [GOV.UK Notify Java library] (https://github.com/alphagov/notifications-java-client)
@@ -113,8 +113,8 @@ These provide example code for calling the API and for creating API tokens.
You can use the GOV.UK Notify API to:
* send a [text](#sendtext) or [email](#sendemail) notification
* [retrieve the status of one notification](#get_single_notif)
* send a [text](#sendtext) or [email](#sendemail) notification
* [retrieve the status of one notification](#get_single_notif)
* [retrieve the status of all notifications](#get_all_notif)
<h3 id="sendnotifications">Send notifications: POST</h3>
@@ -128,7 +128,7 @@ POST /notifications/sms
```
{
'to': '+447700900404',
'template': f6895ff7-86e0-4d38-80ab-c9525856c3ff,
'template': f6895ff7-86e0-4d38-80ab-c9525856c3ff,
'personalisation': {
'name': 'myname',
'date': '2016'
@@ -158,7 +158,7 @@ where:
* `to` is a required string that indicates the recipient's phone number or email address
* `template` is a required string that indicates the Template ID to use
**Note:** To access the Template ID from the [GOV.UK Notify](https://www.notifications.service.gov.uk/) web application, go to **Text message templates** or **Email templates** and click on **API info**.
* `personalisation` is an optional array that specifies the placeholders and values in your templates
@@ -169,11 +169,11 @@ where:
The response (status code 201) will be:
```
{
'data':{
'notification': {
'id':1
}
}
'data':{
'notification': {
'id':1
}
}
}
```
@@ -190,31 +190,34 @@ The response (status code 200) will be:
```
{
'notification':
{
'status': 'delivered',
'to': '07515 987 456',
'template': {'id': '5e427b42-4e98-46f3-a047-32c4a87d26bb',
'name': 'First template',
'template_type': 'sms'},
'created_at': '2016-04-26T15:29:36.891512+00:00',
'updated_at': '2016-04-26T15:29:38.724808+00:00',
'sent_at': '2016-04-26T15:29:37.230976+00:00',
'job': {'id': 'f9043884-acac-46db-b2ea-f08cd8ec6d67',
'original_file_name': 'Test run'},
'sent_at': '2016-04-26T15:29:37.230976+00:00',
'id': 'f163deaf-2d3f-4ec6-98fc-f23fa511518f',
'content_char_count': 490,
'service': '5cf87313-fddd-4482-a2ea-48e37320efd1',
'reference': None,
'sent_by': 'mmg'
}
'notification': {
'status': 'delivered',
'to': '07515 987 456',
'template': {
'id': '5e427b42-4e98-46f3-a047-32c4a87d26bb',
'name': 'First template',
'template_type': 'sms'
},
'created_at': '2016-04-26T15:29:36.891512+00:00',
'updated_at': '2016-04-26T15:29:38.724808+00:00',
'sent_at': '2016-04-26T15:29:37.230976+00:00',
'job': {
'id': 'f9043884-acac-46db-b2ea-f08cd8ec6d67',
'original_file_name': 'Test run'
},
'sent_at': '2016-04-26T15:29:37.230976+00:00',
'id': 'f163deaf-2d3f-4ec6-98fc-f23fa511518f',
'content_char_count': 490,
'service': '5cf87313-fddd-4482-a2ea-48e37320efd1',
'reference': None,
'sent_by': 'mmg'
}
}
```
See [below](#fieldsforGET) for explanations of the fields.
<a name="get_all_notif"></a>
To retrieve the status of all notifications:
To retrieve the status of all notifications:
```
GET /notifications
```
@@ -222,53 +225,63 @@ GET /notifications
The response (status code 200) will be:
```
{'notifications':
[ {
'status': 'delivered',
'to': '07515 987 456',
'template': {'id': '5e427b42-4e98-46f3-a047-32c4a87d26bb',
'name': 'First template',
'template_type': 'sms'},
'job': {'id': '5cc9d7ae-ceb7-4565-8345-4931d71f8c2e',
'original_file_name': 'Test run'},
'created_at': '2016-04-26T15:30:49.968969+00:00',
'updated_at': '2016-04-26T15:30:50.853844+00:00',
'sent_at': '2016-04-26T15:30:50.383634+00:00',
'id': '04ae9bdc-92aa-4d6c-a0da-48587c03d4c7',
'content_char_count': 446
'service': '5cf87313-fddd-4482-a2ea-48e37320efd1',
'reference': None,
'sent_by': 'mmg'
},
{
'status': 'delivered',
'to': '07515 987 456',
'template': {'id': '5e427b42-4e98-46f3-a047-32c4a87d26bb',
'name': 'First template',
'template_type': 'sms'},
'job': {'id': 'f9043884-acac-46db-b2ea-f08cd8ec6d67',
'original_file_name': 'Test run'},
'created_at': '2016-04-26T15:29:36.891512+00:00',
'updated_at': '2016-04-26T15:29:38.724808+00:00',
'sent_at': '2016-04-26T15:29:37.230976+00:00',
'id': 'f163deaf-2d3f-4ec6-98fc-f23fa511518f',
'content_char_count': 490,
'service': '5cf87313-fddd-4482-a2ea-48e37320efd1',
'reference': None,
'sent_by': 'mmg'
},
...
]
'links': {'last': '/notifications?page=3&template_type=sms&status=delivered',
'next': '/notifications?page=2&template_type=sms&status=delivered'},
'total': 162,
'page_size': 50
}
{'notifications':
[{
'status': 'delivered',
'to': '07515 987 456',
'template': {
'id': '5e427b42-4e98-46f3-a047-32c4a87d26bb',
'name': 'First template',
'template_type': 'sms'
},
'job': {
'id': '5cc9d7ae-ceb7-4565-8345-4931d71f8c2e',
'original_file_name': 'Test run'
},
'created_at': '2016-04-26T15:30:49.968969+00:00',
'updated_at': '2016-04-26T15:30:50.853844+00:00',
'sent_at': '2016-04-26T15:30:50.383634+00:00',
'id': '04ae9bdc-92aa-4d6c-a0da-48587c03d4c7',
'content_char_count': 446,
'service': '5cf87313-fddd-4482-a2ea-48e37320efd1',
'reference': None,
'sent_by': 'mmg'
},
{
'status': 'delivered',
'to': '07515 987 456',
'template': {
'id': '5e427b42-4e98-46f3-a047-32c4a87d26bb',
'name': 'First template',
'template_type': 'sms'
},
'job': {
'id': 'f9043884-acac-46db-b2ea-f08cd8ec6d67',
'original_file_name': 'Test run'
},
'created_at': '2016-04-26T15:29:36.891512+00:00',
'updated_at': '2016-04-26T15:29:38.724808+00:00',
'sent_at': '2016-04-26T15:29:37.230976+00:00',
'id': 'f163deaf-2d3f-4ec6-98fc-f23fa511518f',
'content_char_count': 490,
'service': '5cf87313-fddd-4482-a2ea-48e37320efd1',
'reference': None,
'sent_by': 'mmg'
},
…
],
'links': {
'last': '/notifications?page=3&template_type=sms&status=delivered',
'next': '/notifications?page=2&template_type=sms&status=delivered'
},
'total': 162,
'page_size': 50
}
```
<a name="fieldsforGET"></a>
where:
* `status` is the status of the notification; this can be `sending`, `delivered`, or `failed`
* `status` is the status of the notification; this can be `sending`, `delivered`, or `failed`
* `to` is the recipient's phone number or email address
* `template`:
* `id` is the Template ID
@@ -279,13 +292,13 @@ where:
* `sent_at` is the full timestamp, in Coordinated Universal Time (UTC), at which GOV.UK Notify sent the notification
* `job` is empty if you are using the API to send notifications:
* `id` is the job ID
* `original_file_name` is the name of the CSV file, if used
* `original_file_name` is the name of the CSV file, if used
* `id` is the unique identifier for the process of sending and retrieving one or more notifications
* `content_char_count` indicates the full character count of the text notification, including placeholders (populated for text notifications only)
* `service` is your Service ID
* `reference` is used in the Notifications API so you can ignore it (populated for email notifications only)
* `sent_by` is the name of the provider
* `links`:
* `links`:
* `last` is the url of the last page of notifications
* `next` is the url of the next page of notifications
* `total` is the total number of notifications sent by the service using the given template type
@@ -325,10 +338,4 @@ Error code | Body | Meaning
The GOV.UK Notify API code is open sourced at:
[GOV.UK Notify API](https://github.com/alphagov/notifications-api)
[GOV.UK Notify API](https://github.com/alphagov/notifications-api)