API Details¶

The Seed Stage-Based Messaging Store provides REST like API with JSON payloads.

The root URL for all of the endpoints is:

https://<stage-based-messaging-store-domain>/api/

Authenticating to the API¶

Please see the Authentication and Authorization document.

Pagination¶

When the results set is larger than a configured amount, the data is broken up into pages using the limit and offset parameters.

Paginated endpoints will provide information about the total amount of items available along with links to the previous and next pages (where available) in the returned JSON data.

GET /(any)/

Query Parameters:
	limit – the amount of record to limit a page of results to. offset – the starting position of the query in relation to the complete set of unpaginated items
Response JSON Object:
	count (int) – the total number of results available previous (string) – the URL to the previous page of results (if available) next (string) – the URL to the next page of results (if available)

Example request:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "count": 50,
    "next": "http://sbm.example.org/api/v1/enpoint/?limit=10&offset=30",
    "previous": "http://smb.example.org/api/v1/endpoint/?limit=10&offset=10",
    "results": []
}

Endpoints¶

The endpoints provided by the Seed Stage-Based Messaging Store are split into two categories, core endpoints and helper endpoints

Core¶

The root URL for all of the core endpoints includes the version prefix (https://<stage-based-messaging-store-domain>/api/v1/)

POST /user/token/¶

Creates a user and token for the given email address.

If a user already exists for the given email address, the existing user account is used to generate a new token.

Request JSON Object:
	email (string) – the email address of the user to create or use.
Response JSON Object:
	token (string) – the auth token generated for the given user.
Status Codes:	201 Created – token successfully created. 400 Bad Request – an email address was not provided or was invalid. 401 Unauthorized – the token is invalid/missing.

Example request:

POST /user/token/ HTTP/1.1
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

{
    "email": "bob@example.org"
}

Example response:

HTTP/1.1 201 Created
Content-Type: application/json

{
    "token": "c05fbab6d5f912429052830c77eeb022249324cb"
}

Content¶

GET /schedule/¶: Returns a list of Schedules.

POST /schedule/¶: Creates a new Schedule.

GET /schedule/(int: schedule_id)/¶: Retuns the Schedule record for a given schedule_id.

PUT /schedule/(int: schedule_id)/¶: Updates the Schedule record for a given schedule_id.

DELETE /schedule/(int: schedule_id)/¶: Deletes the Schedule record for a given schedule_id.

GET /messageset/¶: Returns a list of MessageSets.

POST /messageset/¶: Creates a new MessageSet.

GET /messageset/(int: messageset_id)/¶: Retuns the MessageSet record for a given messageset_id.

PUT /messageset/(int: messageset_id)/¶: Updates the MessageSet record for a given messageset_id.

DELETE /messageset/(int: messageset_id)/¶: Deletes the MessageSet record for a given messageset_id.

GET /messageset/(int: messageset_id)/messages/¶: Returns a list of Messages for a given messageset_id.

GET /message/¶: Returns a list of Messages.

POST /message/¶: Create a new Message record.

GET /message/(int: message_id)/¶: Returns the Message record for a given message_id.

PUT /message/(int: message_id)/¶: Updates the Message record for a given message_id.

DELETE /message/(int: message_id)/¶: Deletes the Message record for a given message_id.

GET /message/(int: message_id)/content/¶: Returns the content for a given message_id.

GET /binarycontent/¶: Returns a list of BinaryContent records.

POST /binarycontent/¶: Creates a new BinaryContent record.

GET /binarycontent/(int: binarycontent_id)/¶: Returns the BinaryContent record for a given binarycontent_id.

PUT /binarycontent/(int: binarycontent_id)/¶: Updates the BinaryContent record for a given binarycontent_id.

DELETE /binarycontent/(int: binarycontent_id)/¶: Deletes the BinaryContent record for a given binarycontent_id.

Subscriptions¶

GET /subscriptions/¶: Returns a list of Subscriptions.

POST /subscriptions/¶: Creates a new Subscription record.

GET /subscriptions/(int: subscription_id)/¶: Returns the Subscription record for a given subscription_id.

PUT /subscriptions/(int: subscription_id)/¶: Updates the Subscription record for a given subscription_id.

DELETE /subscriptions/(int: subscription_id)/¶: Deletes the Subscription record for a given subscription_id.

POST /subscriptions/(int: subscription_id)/send¶

Triggers a send for the next Subscription message for the given subscription_id.

The actual sending is processed asynchronously by a Celery worker.

Response JSON Object:
	accepted (boolean) – Whether send for subscription_id is accepted. reason (string) – An optional reason why the request was not accepted.
Status Codes:	201 Created – request to send the next message accepted. 400 Bad Request – invalid subscription_id given.

POST /subscriptions/request¶

Creates a new subscription.

This endpoint is called as a webhook request from the project Hub service when a new registration is created that requires a subscription.

As such the entire payload is expected to be provided as an object in the data parameter.

Request JSON Object:
	data (json) – a JSON representation of a Subscription object.
Response JSON Object:
	accepted (boolean) – Whether new subscription was created.
Status Codes:	201 Created – subscription created. 400 Bad Request – invalid request.

Helpers¶

The root URL for the helper endpoints does not include a version prefix (https://<stage-based-messaging-store-domain>/api/)

GET /metrics/

Returns a list of all the available metric keys provided by this service.

Status Codes:	200 OK – no error 401 Unauthorized – the token is invalid/missing.

POST /metrics/

Starts a task that fires all scheduled metrics.

Status Codes:	200 OK – no error 401 Unauthorized – the token is invalid/missing.

GET /health/

Returns a basic health check status.

Status Codes:	200 OK – no error 401 Unauthorized – the token is invalid/missing.