Merge pull request #134 from GSA/api-documents

Update API documentation

docs/api-usage.md

@@ -2,33 +2,43 @@
 
 ## Connecting to the API
 
-To make life easier, the [UK API client libraries](https://www.notifications.service.gov.uk/documentation) are compatible with Notify.
+To make life easier, the [UK API client libraries](https://www.notifications.service.gov.uk/documentation) are compatible with Notify and the [UK API Documentation](https://docs.notifications.service.gov.uk/rest-api.html) is applicable.
 
 For a usage example, see [our Python demo](https://github.com/GSA/notify-python-demo).
 
-An API key can be created at https://notifications-admin.app.cloud.gov/services/YOUR_SERVICE_ID/api/keys. However, in order to successfully send messages, you will need to receive a secret header token from the Notify team.
+An API key can be created at https://HOSTNAME/services/YOUR_SERVICE_ID/api/keys. This is the same API key that is referenced as `USER_API_TOKEN` below.
+
+## Postman Documentation
+
+Internal-only  [documentation for exploring the API using Postman](https://docs.google.com/document/d/1S5c-LxuQLhAtZQKKsECmsllVGmBe34Z195sbRVEzUgw/edit#heading=h.134fqdup8d3m)
 
 
 ## Using OpenAPI documentation
 
+An [OpenAPI](https://www.openapis.org/) specification [file](./openapi.yml) can be found at https://notify-staging.app.cloud.gov/docs/openapi.yml.
+
+See [writing-public-apis.md](./writing-public-apis.md) for links to tools to make it easier to use the OpenAPI spec within VSCode.
+
 ### Retrieving a jwt-encoded bearer token for use
 
-On a mac, run
+On a mac, run:
 
 #### Admin UI token
 
+The admin UI token is required for any of the `internal-api` tagged methods. To create one and copy it to your pasteboard, run:
+
 ```
 flask command create-admin-jwt | tail -n 1 | pbcopy
 ```
 
 #### User token
 
+A user token is required for any of the `external-api` tagged methods. To create one and copy it to your pasteboard, run:
+
 ```
 flask command create-user-jwt --token=<USER_API_TOKEN> | tail -n 1 | pbcopy
 ```
 
-to copy a token to your pasteboard. This token will expire in 30 seconds
-
 ### Disable token expiration checking in development
 
 Because jwt tokens expire so quickly, the development server can be set to allow tokens older than 30 seconds:

docs/openapi.yml

@@ -167,6 +167,47 @@ components:
                 type: string
               version:
                 type: number
+    templateObject:
+      type: object
+      properties:
+        body:
+          type: string
+        created_at:
+          type: string
+        created_by:
+          type: string
+        id:
+          type: string
+        letter_contact_block:
+          type: object
+        name:
+          type: string
+        personalisation:
+          type: object
+        postage:
+          type: string
+        subject:
+          type: string
+        type:
+          type: string
+        updated_at:
+          type: string
+        version:
+          type: integer
+      required:
+        - body
+        - created_at
+        - created_by
+        - id
+        - letter_contact_block
+        - name
+        - personalisation
+        - postage
+        - subject
+        - type
+        - updated_at
+        - version
+      additionalProperties: false
 paths:
   /_status?simple=1:
     get:
@@ -449,6 +490,54 @@ paths:
                     type: array
                     items:
                       $ref: "#/components/schemas/userObject"
+  /v2/templates:
+    get:
+      security:
+        - bearerAuth: []
+      description: 'Get list of templates'
+      tags:
+        - external-api
+      parameters:
+        - name: type
+          in: query
+          schema:
+            type: string
+            enum: ["sms", "email"]
+          examples:
+            "SMS Templates":
+              value: "sms"
+            "Email Templates":
+              value: "email"
+            "All Templates":
+              value: ""
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  templates:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/templateObject"
+  /v2/template/{uuid}:
+    get:
+      security:
+        - bearerAuth: []
+      description: 'Get details for a single template'
+      tags:
+        - external-api
+      parameters:
+        - $ref: "#/components/parameters/uuidPath"
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/templateObject"
   /v2/notifications/sms:
     post:
       security: