Dipity Timelines REST API Documentation

Resource Index

Getting Started

After obtaining developer keys, simply make API calls to the Dipity REST server located at api.dipity.com. Please review the requirements that apply to all REST API calls, which are described below.

Required Parameters

Calls to any Dipity REST resource require the query parameters key and sig. The key parameter is the API key listed on the developer keys page.

The sig parameter is a signature used to verify the authenticity of the request for the provided key. A signature is computed according to the following steps:

  1. Start with the secret, obtained from the developer keys page
  2. Sort the list of parameters provided for the REST call according to the parameter name
  3. Append to the secret the first parameter name then the first parameter value continuing with the remaining parameters
  4. Compute the MD5 checksum of the resulting string

The checksum computed in the final step is the value to provide for the sig parameter.

Entity Representations

When a REST resource returns an entity, it may be represented in a number of different formats that can be selected by the client. The client may specify the desired representation by setting the Accept: HTTP header. The following representations are currently supported:

  • text/xml
  • application/json

If no Accept: header is provided in the request, the an entity will be returned as a text/xml representation.

HTTP Methods

The REST API supports the four major HTTP method verbs GET, POST, PUT, and DELETE for manipulating resources. Since some HTTP libraries and proxies have difficulties with methods like PUT and DELETE, the API supports an alternate approach. Resources that require PUT or DELETE will accept a POST method request, with a HTTP header of X-HTTP-Method-Override: of PUT or DELETE, respectively.

Resource Documentation

Create Timeline

Creates a new, empty timeline. To populate the timeline with events, call Add Event To Timeline.

Request

URI:
/rest/timelines
Method:
POST
Content-Type:
multipart/form-data

Parameters

title
The title of the timeline. Required.
description
A description of the timeline. Optional.
public
Indicates if the timeline is publicly visible. Required.
category
The category that the timeline is filed under. Optional.

Response

201 Created
The timeline was successfully created.
403 Forbidden
An invalid category was specified.

Retrieve Timeline

Retrieves the timeline's properties.

Request

URI:
/rest/timelines/{timeline id}
Method:
GET
Content-Type:
application/x-www-url-encoded

Parameters

No resource-specific parameters.

Response

200 OK
The timeline data is returned in the response entity.
404 Not Found
The timeline resource specified does not exist or is not accessible to the principal making the request.

Entity

title
The title of the timeline.
description
A description of the timeline.
public
Indicates if the timeline is publicly visible.
category
The category that the timeline is filed under.

Update Timeline

Updates the timeline's properties.

Request

URI:
/rest/timelines/{timeline id}
Method:
PUT
Content-Type:
multipart/form-data

Parameters

title
The title of the timeline. Required.
description
A description of the timeline. Optional.
public
Indicates if the timeline is publicly visible. Required.
category
The category that the timeline is filed under. Optional.

Response

204 No Content
The timeline was successfully updated.
403 Forbidden
An invalid category was specified.
404 Not Found
The timeline resource specified does not exist or is not accessible to the principal making the request.

Delete Timeline

Deletes the timeline.

Request

URI:
/rest/timelines/{timeline id}
Method:
DELETE
Content-Type:
application/x-www-url-encoded

Parameters

No resource-specific parameters.

Response

204 No Content
The timeline resource was successfully deleted.
404 Not Found
The timeline resource specified does not exist or is not accessible to the principal making the request.

Upload Timeline Image

Adds or updates an image file to a timeline. After the image is successfully uploaded, the resource's image_url property is updated with a URL to the uploaded image.

Request

URI:
/rest/timelines/{timeline id}/image
Method:
POST
Content-Type:
multipart/form-data

Parameters

image
A JPEG, PNG, or GIF file.

Response

201 Created
The image was successfully uploaded to the timeline.
404 Not Found
The timeline resource specified does not exist or is not accessible to the principal making the request.
500 Server Error
Unable to upload the image.

Create Event

Creates an event.

Request

URI:
/rest/events
Method:
POST
Content-Type:
multipart/form-data

Parameters

title
The title of the event. Required.
description
A description of the event. Optional.
timestamp
When the event occurred, formatted as per RFC 3339. Required.
link_url
A URL for more information related to the event. Optional.
image_url
A URL of an image for the event. Optional.
video_url
A URL of a video for the event. Optional.
location
The location of the event. The canonical form is "degree decimal" format, where the latitude and longitude are expressed as -90–90,-180–180 real numbers, separated by a comma, respectively. If a value is provided that doesn't follow the degree decimal format, the resource will attempt to geocode the value. If successful, the geocoded result will be stored as the canonical form. Optional.

Response

201 Created
The timeline was successfully created.
403 Forbidden
Unable to create the event.

Retrieve Event

Retrieves the event's properties.

Request

URI:
/rest/events/{event id}
Method:
GET
Content-Type:
application/x-www-url-encoded

Parameters

No resource-specific parameters.

Response

200 OK
The event data is returned in the response entity.
404 Not Found
The event resource specified does not exist or is not accessible to the principal making the request.

Entity

title
The title of the event.
description
A description of the event.
timestamp
When the event occurred, formatted as per RFC 3339.
link_url
A URL for more information related to the event.
image_url
A URL of an image for the event.
video_url
A URL of a video for the event.
location
The location of the event. The canonical form is "degree decimal" format, where the latitude and longitude are expressed as -90–90,-180–180 real numbers, separated by a comma, respectively. If a value is provided that doesn't follow the degree decimal format, the resource will attempt to geocode the value. If successful, the geocoded result will be stored as the canonical form. Optional.

Update Event

Updates the event's properties.

Request

URI:
/rest/events/{event id}
Method:
PUT
Content-Type:
multipart/form-data

Parameters

title
The title of the event. Required.
description
A description of the event. Optional.
timestamp
When the event occurred, formatted as per RFC-3339. Required.
link_url
A URL for more information related to the event. Optional.
image_url
A URL of an image for the event. Optional.
video_url
A URL of a video for the event. Optional.
location
The location of the event. The canonical form is "degree decimal" format, where the latitude and longitude are expressed as -90–90,-180–180 real numbers, separated by a comma, respectively. If a value is provided that doesn't follow the degree decimal format, the resource will attempt to geocode the value. If successful, the geocoded result will be stored in the canonical form. Optional.

Response

204 No Content
The event was successfully updated.
404 Not Found
The event resource specified does not exist or is not accessible to the principal making the request.

Delete Event

Deletes the event.

Request

URI:
/rest/events/{event id}
Method:
DELETE
Content-Type:
application/x-www-url-encoded

Parameters

No resource-specific parameters.

Response

204 No Content
The event resource was successfully deleted.
404 Not Found
The event resource specified does not exist or is not accessible to the principal making the request.

Upload Event Image

Adds or updates an image file to a event. After the image is successfully uploaded, the resource's image_url property is updated with a URL to the uploaded image.

Request

URI:
/rest/events/{timeline id}/image
Method:
POST
Content-Type:
multipart/form-data

Parameters

image
A JPEG, PNG, or GIF file.

Response

201 Created
The image was successfully uploaded to the event.
404 Not Found
The event resource specified does not exist or is not accessible to the principal making the request.
500 Server Error
Unable to upload the image.

Add Event To Timeline

Adds an event to the timeline.

Request

URI:
/rest/timelines/{timeline id}/events
Method:
POST
Content-Type:
multipart/form-data

Parameters

event_id
Event identifier of the event to add to the timeline.

Response

204 No Content
The event was successfully added to the timeline.
404 Not Found
The timeline or event resource specified does not exist or is not accessible to the principal making the request.

Remove Event From Timeline

Removes the event from the timeline.

Request

URI:
/rest/timelines/{timeline id}/events/{event id}
Method:
DELETE
Content-Type:
application/x-www-url-encoded

Parameters

No resource-specific parameters.

Response

204 No Content
The event resource was successfully removed from the timeline.
404 Not Found
The timeline or event resource specified does not exist or is not accessible to the principal making the request.