Schedule Helper
This document defines the Schedule Helper resource.
The Schedule Helper is a helper endpoint that schedules a Message to be sent at a later time via POST or cancels the scheduling via DELETE.
The Schedule Helper POST body contains a datetime field for the time you want to schedule the message to be sent, and the DELETE body is empty.
Typically, the response to a successful Schedule Helper POST or DELETE is a confirmation message and a 200 server code. Some servers may only allow you to schedule 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:schedule_helper.
Fields
The field names for this resource, with standard names, punctuation and capitalization, and values where appropriate.
Note: As with the entire OSDI specification, the specific fields a compliant system implements will vary between each system, as will the fields each system requires when creating or updating resources, which fields are writeable, and the operations you are allowed to perform on each resource.
Schedule Helper Fields
A list of fields specific for POSTing via the Schedule Helper.
| Name | Type | Description |
|---|---|---|
| scheduled_start_date | datetime | The date and time the message should be scheduled to to start sending text to the targets. |
| scheduled_stop_date | datetime | The date and time the message is scheduled to be stopped. |
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: Scheduling a Message (POST)
Posting to the schedule helper endpoint with a blank body will allow you to schedule a message to be sent.
Request
POST https://osdi-sample-system.org/api/v1/messages/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/schedule
Header:
OSDI-API-Token:[your api key here]
{
"scheduled_start_date": "2015-03-14T12:00:00Z",
"scheduled_end_date": "2015-03-17T12:00:00Z",
}
Response
200 OK
Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate
{
"notice": "Your message has been scheduled."
}
Scenario: Canceling a Scheduled Message (DELETE)
Sending a DELETE to the schedule helper endpoint with a blank body will cancel the scheduling for the message.
Request
DELETE https://osdi-sample-system.org/api/v1/messages/d91b4b2e-ae0e-4cd3-9ed7-d0ec501b0bc3/schedule
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 scheduling has been canceled."
}