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.
Related Resources
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."
}
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."
}