Back to the Overview

Standards & Conventions

Al requests should include the key parameter, and should include an Authorization header containing the signed request with the secret_key given to the app.

Base URL

http://api.deliradio.com/v3/:path?key=:token&:params

Where :token is the consumer token. And :path is the path to the resources wanted to access. :params is the query string params when sending GET requests. When sending other verb than GET (e.g. POST, PUT) the parameters should be sent in the body not in the url.

Example

GET http://api.deliradio.com/v3/bands/1.json?key=098f6bcd4621

Or with a POST verb:

POST http://api.deliradio.com/v3/bands/2/subscribe.json?key=098f6bcd4621

Body:

email=foo@bar.com

POST bodies may be form encoded or JSON as long as the appriate Content-Type request header is set.

Version

The version of the API is specified in the URL /v1/. Be sure to use the right version. Current version is 3

Signing requests

Requests are required to be signed. For information on this, see Signing Requests

Responses

All the responses are in JSON. And it contains a root with the name of the resources that was asked for.

Example

    {
      "station" : {
        "id": 4,
        "title": "Rockish",
        "created_at": "2011-06-24T13:16:44-05:00"
      }
    }

When returning a collection of resources, the root is the type of the collection. Child elements will not have the root node.

Example

    { "stations": [
        {
          "id": 4,
          "title": "Rockish",
          "created_at": "2011-06-24T13:16:44-05:00"
        },
        {
          "id": 5,
          "title": "From L.A.",
          "created_at": "2011-05-04T23:12:20-09:00"
        }
      ]
    }

Status Codes

These are the codes that the API can respond with.

  • 200 OK: Success
  • 400 Bad Request: The request was invalid.
  • 401 Unauthorized: Authentication credentials.
  • 403 Forbidden: The request is understood, but it has been refused. Probably the path is not allowed for the given user.
  • 404 Not Found: The URI requested is invalid or the resource requested does not exist.
  • 406 Not Acceptable: Returned when an invalid format is specified in the request.
  • 500 Internal Server Error: Something is broken. Let us know so we can take a look.