From 57ad64fae6d69569e46e3c73bff2d07987a34273 Mon Sep 17 00:00:00 2001 From: Chris Hill-Scott Date: Fri, 15 Apr 2016 10:48:31 +0100 Subject: [PATCH 1/3] Get the docs rendering in the app MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit replaces the old _API Documentation_ page with the Markdown version that Catherine has been working on. I’ve checked that there’s nothing obviously wrong or placeholder-y still in there, so I think we’re good to go. --- app/main/views/api_keys.py | 5 - app/main/views/index.py | 16 ++- app/templates/views/documentation.html | 141 +------------------------ requirements.txt | 1 + 4 files changed, 19 insertions(+), 144 deletions(-) diff --git a/app/main/views/api_keys.py b/app/main/views/api_keys.py index f50bd0390..aad602179 100644 --- a/app/main/views/api_keys.py +++ b/app/main/views/api_keys.py @@ -6,11 +6,6 @@ from app import api_key_api_client from app.utils import user_has_permissions -@main.route("/documentation") -def documentation(): - return render_template('views/documentation.html') - - @main.route("/services//api-keys") @login_required @user_has_permissions('manage_api_keys') diff --git a/app/main/views/index.py b/app/main/views/index.py index 9b00d14e8..28959a9ef 100644 --- a/app/main/views/index.py +++ b/app/main/views/index.py @@ -1,8 +1,10 @@ -from flask import render_template, url_for, redirect, jsonify +import markdown +from flask import render_template, url_for, redirect, Markup from app.main import main from flask_login import login_required from flask.ext.login import current_user +from mdx_gfm import GithubFlavoredMarkdownExtension @main.route('/') @@ -36,3 +38,15 @@ def pricing(): @main.route('/terms') def terms(): return render_template('views/terms-of-use.html') + + +@main.route('/documentation') +def documentation(): + with open('docs/index.md') as source: + return render_template( + 'views/documentation.html', + body=Markup(markdown.markdown( + source.read(), + extensions=[GithubFlavoredMarkdownExtension()] + )) + ) diff --git a/app/templates/views/documentation.html b/app/templates/views/documentation.html index 60bcf046d..2fba0f113 100644 --- a/app/templates/views/documentation.html +++ b/app/templates/views/documentation.html @@ -1,6 +1,4 @@ {% 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 @@ -8,143 +6,10 @@ {% block maincolumn_content %} -

- Developer documentation -

-
-
- -

- How to integrate GOV.UK Notify into your service -

- -

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

- -

- API authentication -

- -

- Notify uses JSON Web Tokens (JWT) for authentication. - JWT tokens have a series of claims, standard and application specific. -

-
-
-

Notify standard claims:

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

Notify application specific:

- {{""" -{ - iss: 'string', // service id - iat: 0, // creation time in epoch seconds (UTC) -} - """|syntax_highlight_json}} -
-
- -

- API endpoints -

- -

To create a text notification

-
-
- {{ "POST /notifications/sms"|syntax_highlight_json }} - - {{ - """ -{ - 'to': '+447700900404', - 'template': 1 -} - """|syntax_highlight_json - }} -
-
-

- Where ‘to’ is the phone number and ‘template’ is the template ID to send. -

- -

- Response: -

-
-
- {{""" -{ - 'data':{ - 'notification': { - 'id':1 - } - } -} - """|syntax_highlight_json }} - - -

To get the status of a text notification

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

- API client libraries -

- -

A python client library is support by the Notify team:

- -

- GOV.UK Notify Python client -

- -

- This provides example code for calling the API and for constructing the API tokens. -

- -

API code

- -

Notify API code is open sourced at:

- -

- GOV.UK Notify API -

- -

API endpoint

- -

- https://api.notifications.service.gov.uk/ -

- -
+
+ {{ body }} +
{% endblock %} diff --git a/requirements.txt b/requirements.txt index c1383edab..baee19ae2 100644 --- a/requirements.txt +++ b/requirements.txt @@ -11,6 +11,7 @@ Flask-Bcrypt==0.6.2 credstash==1.8.0 boto3==1.2.3 Pygments==2.0.2 +py-gfm==0.1.2 git+https://github.com/alphagov/notifications-python-client.git@0.5.0#egg=notifications-python-client==0.5.0 From f7c15dfbaf5b0c9d98ee777ab8fdb683e9538c10 Mon Sep 17 00:00:00 2001 From: Chris Hill-Scott Date: Fri, 15 Apr 2016 10:56:47 +0100 Subject: [PATCH 2/3] Add some basic typography, tweak the Markdown This commit adds some basic type sizes, weights and spacing for HTML elements scoped inside a `.documentation` container. It also tweaks some of the Markdown so that it renders the same as it does on Github. --- app/assets/stylesheets/main.scss | 1 + .../stylesheets/views/documenation.scss | 64 +++++++++++++++ app/templates/views/documentation.html | 4 +- docs/index.md | 78 ++++++++++--------- 4 files changed, 107 insertions(+), 40 deletions(-) create mode 100644 app/assets/stylesheets/views/documenation.scss diff --git a/app/assets/stylesheets/main.scss b/app/assets/stylesheets/main.scss index 2504e5ff1..98910957e 100644 --- a/app/assets/stylesheets/main.scss +++ b/app/assets/stylesheets/main.scss @@ -52,6 +52,7 @@ $path: '/static/images/'; @import 'views/job'; @import 'views/edit-template'; +@import 'views/documenation'; // TODO: break this up @import 'app'; diff --git a/app/assets/stylesheets/views/documenation.scss b/app/assets/stylesheets/views/documenation.scss new file mode 100644 index 000000000..d86486aee --- /dev/null +++ b/app/assets/stylesheets/views/documenation.scss @@ -0,0 +1,64 @@ +.documentation { + + h1, + h2, + h3, + h4, + h5, + h6 { + margin: $gutter 0 $gutter-half 0; + } + + h1 { + @include heading-48; + font-weight: bold; + } + + h2 { + @include heading-36; + font-weight: bold; + } + + h3 { + @include heading-24; + font-weight: bold; + } + + h4, + h5, + h6 { + @include bold-19; + } + + p, + ul { + margin: 0 0 20px 0; + } + + ul { + list-style: disc; + margin: 0 0 20px 20px; + } + + ol { + list-style: decimal; + margin: 0 0 20px 20px; + } + + blockquote { + border-left: 8px solid $border-colour; + padding: 0 0 0 20px; + margin: 0 0 20px 0; + } + + .highlight { + margin: 0 0 20px 0; + background: #F8F8F8; + } + + strong, + em { + font-weight: bold; + } + +} diff --git a/app/templates/views/documentation.html b/app/templates/views/documentation.html index 2fba0f113..28bacadb9 100644 --- a/app/templates/views/documentation.html +++ b/app/templates/views/documentation.html @@ -7,8 +7,8 @@ {% block maincolumn_content %}
-
- {{ body }} +
+ {{ body }}
diff --git a/docs/index.md b/docs/index.md index 12b1376c8..428f4abbb 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,9 +1,11 @@ -About this document -========================== +# API documenation + +## About this document + This document is for central government developers, technical architects, and service managers who want to use the GOV.UK Notify platform to send notifications to users of their digital service. -About GOV.UK Notify -==================== +## About GOV.UK Notify + GOV.UK Notify is a cross-government platform, currently in beta, that lets government services send notifications by sms or email. There are two ways to send notifications: @@ -13,8 +15,7 @@ There are two ways to send notifications: To find out more about GOV.UK Notify, see the [Government as a Platform](https://governmentasaplatform.blog.gov.uk/) blog. -Before you start -================== +## Before you start To use GOV.UK Notify, you need: @@ -23,44 +24,45 @@ To use GOV.UK Notify, you need: -Quick start guide to GOV.UK Notify -=================================== +## Quick start guide to GOV.UK Notify To get started: -1. Register for a [GOV.UK Notify](https://www.notifications.service.gov.uk/) account. You will need your mobile phone for 2-factor authentication. -2. Add a new service. + 1. Register for a [GOV.UK Notify](https://www.notifications.service.gov.uk/) account. You will need your mobile phone for 2-factor authentication. - At first your service will be in trial mode. In trial mode you will only be able to send test sms and email notifications to your own mobile number or email address. When you’re fully integrated and ready to go live, send a request to the GOV.UK Notify team. + 2. Add a new service. -3. Add a template so you can send sms and email notifications. + At first your service will be in trial mode. In trial mode you will only be able to send test sms and email notifications to your own mobile number or email address. When you’re fully integrated and ready to go live, send a request to the GOV.UK Notify team. - **Note:** A template is required even if you send notifications by integrating with the GOV.UK Notify API. + 3. Add a template so you can send sms and email notifications. + + **Note:** A template is required even if you send notifications by integrating with the GOV.UK Notify API. - You can personalise the template using double brackets for placeholders. For example: + You can personalise the template using double brackets for placeholders. For example: - Dear ((name)), + > Dear ((name)), + > + > Your ((item)) is due for renewal on ((date)). - Your ((item)) is due for renewal on ((date)). + 4. You can upload a csv file containing a header row matching the placeholders in your template, and data rows with values to use for the placeholders. -4. You can upload a csv file containing a header row matching the placeholders in your template, and data rows with values to use for the placeholders. -5. Send an sms or email notification. -6. If you intend to use the GOV.UK Notify API, create a new API key. This will be used to connect to the GOV.UK Notify API. + 5. Send an sms or email notification. - You can provide all your developers with test keys so they can experiment in the Sandbox environment. But keep the number of keys for real integrations to a minimum number of people on your team. + 6. If you intend to use the GOV.UK Notify API, create a new API key. This will be used to connect to the GOV.UK Notify API. + + You can provide all your developers with test keys so they can experiment in the Sandbox environment. But keep the number of keys for real integrations to a minimum number of people on your team. -Integrate the GOV.UK Notify API into your service -=================================================== +## Integrate the GOV.UK Notify API into your service GOV.UK Notify provides an API that allows you to create text and email notifications and get the status of notifications you have sent. -API integration ------------------- +### API integration ![Notfy](Notify.png) There are two ways to integrate the API into your service: + * use one of the client libraries provided by GOV.UK Notify: * [python library](https://github.com/alphagov/notifications-python-client) * [PHP library] (https://github.com/alphagov/notifications-php-client) @@ -68,20 +70,20 @@ There are two ways to integrate the API into your service: * develop your own integration to produce requests in the correct format -GOV.UK Notify uses [JSON Web Tokens (JWT)](https://jwt.io/) for authentication and identification. The GOV.UK Notify client library encodes and decodes JSON Web Tokens when making requests to the GOV.UK Notify API. If you don't use this library, you must manually create tokens yourself. +GOV.UK Notify uses [JSON Web Tokens (JWT)](https://jwt.io/) for authentication and identification. The GOV.UK Notify client library encodes and decodes JSON Web Tokens when making requests to the GOV.UK Notify API. If you don’t use this library, 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. A JSON Web Token contains, in encrypted format: -* your service ID - identifies your service -* your API key (in JSON Web Token terms this is called the client ID) - used to sign tokens during requests for API resources + +* your service ID – identifies your service +* your API key (in JSON Web Token terms this is called the client ID) – used to sign tokens during requests for API resources Use the [GOV.UK Notify](https://www.notifications.service.gov.uk/) web application to find your service ID and create API keys. **Important:** API keys are secret, so save them somewhere safe. Do not commit API keys to public source code repositories. -JSON Web Tokens: claims ------------------- +### JSON Web Tokens: claims JSON Web Tokens have a series of standard and application-specific claims. @@ -103,8 +105,7 @@ GOV.UK Notify application-specific claims: The signing algorithm is the HMAC signature, using the provided key SHA256 hashing algorithm. -API client libraries ---------------------- +### API client libraries GOV.UK Notify supports a python client library: @@ -113,10 +114,10 @@ GOV.UK Notify supports a python client library: This provides example code for calling the API and for constructing the API tokens. -API endpoints ----------------- +### API endpoints You can use the GOV.UK Notify API to: + * send a notification * retrieve one notification * retrieve all notifications @@ -153,10 +154,11 @@ POST /notifications/email ``` where: + * `to` is the phone number (required) * `template` is the template ID to send (required) - **Note:** Access the template ID from the [GOV.UK Notify](https://www.notifications.service.gov.uk/) web application: go to **Text message templates**, click on **Edit template** and recover the template id from the url eg `/templates//edit` + **Note:** Access the template ID from the [GOV.UK Notify](https://www.notifications.service.gov.uk/) web application: go to **Text message templates**, click on **Edit template** and recover the template id from the url eg `/templates//edit` * `personalisation` (optional) specifies the values for the placeholders in your templates @@ -199,6 +201,7 @@ GET /notifications/{id} } ``` where: + * `status` is the the status of the notification; this can be `sending`, `delivered`, or `failed` * `template_type` is `sms` or `email` * `sent_at` is the full timestamp, in UTC, at which the notification was sent @@ -206,7 +209,7 @@ where: * `message` is the content of message * `sender` may be the provider -The above fields are populated once the message has been processed; initially you get back the [response](#coderesponse) indicated above. +The above fields are populated once the message has been processed; initially you get back the [response](#coderesponse) indicated above. To get the status of all notifications: ``` @@ -240,7 +243,7 @@ GET /notifications 'job_id':1, 'sender':'email-partner' } - }...] + }…] } ``` This list is split into pages. To scroll through the pages run: @@ -250,8 +253,7 @@ GET /notifications?&page=2 ``` -GOV.UK Notify API code ------------------------- +### GOV.UK Notify API code The GOV.UK Notify API code is open sourced at: From e89063e2850f9f03bf25a73ed1aa27366f919092 Mon Sep 17 00:00:00 2001 From: Chris Hill-Scott Date: Fri, 15 Apr 2016 12:11:07 +0100 Subject: [PATCH 3/3] Move the image so the app can serve it --- .../assets/images/notify-diagram.png | Bin docs/index.md | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/Notify.png => app/assets/images/notify-diagram.png (100%) diff --git a/docs/Notify.png b/app/assets/images/notify-diagram.png similarity index 100% rename from docs/Notify.png rename to app/assets/images/notify-diagram.png diff --git a/docs/index.md b/docs/index.md index 428f4abbb..017ba4446 100644 --- a/docs/index.md +++ b/docs/index.md @@ -59,7 +59,7 @@ GOV.UK Notify provides an API that allows you to create text and email notificat ### API integration -![Notfy](Notify.png) +![Notfy](/static/images/notify-diagram.png) There are two ways to integrate the API into your service: