Send Helper

This document defines the Send Helper resource.

The Send Helper is a helper endpoint that sends a Message via POST or stops an already sending Message via DELETE.

The Send Helper POST and DELETE body is empty.

Typically, the response to a successful Send Helper POST or DELETE is a confirmation message and a 200 server code. Some servers may only allow you to send messages after some conditions are met (such as the message has a target list). Errors should be returned if your POST or DELETE is not successful.

Sections:

Endpoints and URL structures

OSDI does not specify specific endpoints and link structures for compliant systems to use. Rather, because OSDI is a HAL+JSON API, endpoints and structures are defined in the links section of each returned resource, starting with the API Entry Point link.

HAL’s link structure lets an API consumer move through API levels, resources, and collections by parsing and following links. While most systems will not change the value of their links often and obey RESTful design principles, the value of each link when that resource is retrieved is the only canonical value, and it can change at any time.

The link relation label for the Send Helper is osdi:send_helper.

Back to top…

Back to top…

Scenarios

The scenarios below show common create (POST) operations that can be performed on this helper. While the canonical definitions of fields are above, these examples should be complete as well.

Scenario: Sending a Message (POST)

Posting to the send helper endpoint with a blank body will allow you to send a message.

Request

POST https://osdi-sample-system.org/api/v1/messages/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/send

Header:
OSDI-API-Token:[your api key here]

{}

Response

200 OK

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate

{
    "notice": "Your message has been sent."
}

Back to top…

Scenario: Stopping a Message from sending (DELETE)

Sending a DELETE to the send helper endpoint with a blank body will stop the message from sending mid-send, if it hasn’t already all gone out.

Request

DELETE https://osdi-sample-system.org/api/v1/messages/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/send

Header:
OSDI-API-Token:[your api key here]

{}

Response

200 OK

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate

{
    "notice": "Your message has been stopped."
}

Back to top…