API Design

The Castr is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.


Castr uses access tokens to authenticate the API requests. To make a successful request to access a resource in Castr, you must pass a Token ID and Secret key in the authorization header of each request.

The Authentication is performed via HTTP basic auth where you pass the Token ID in the username value and the Secret key in the password value.

API Protocol

Castr follows the REST standard taking advantage of HTTP methodologies defined by the RFC 2616 protocol. It uses GET/POST requests to communicate and HTTP response codes to indicate status and errors.

All responses come in the standard JSON and all requests must include Content-Type: application/json Header, and a valid JSON body when applicable.