darkhelm/notifications-api
1
0
Fork 0
mirror of https://github.com/GSA/notifications-api.git synced 2025-12-11 07:42:20 -05:00
Code Issues Packages Projects Releases Wiki Activity

Add links to postman documentation and other additions to api docs

Browse Source
This commit is contained in:
Ryan Ahearn
2022-12-02 11:44:56 -05:00
parent 34def50f69
commit b32dbdf199
1 changed files with 15 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
docs/api-usage.md
View File

@@ -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: