API Documentation

Last updated on April 01, 2015 17:55

Our API is still under going construction but this page will outlines each of the API methods which are available to you.

The Viaduct API is created using the Moonrope specification. What follows explains how to make requests and how responses are formed.

  • All requests are made using HTTP.
  • All responses will be returned in JSON.
  • The HTTP verb doesn't matter but POST is recommended.
  • Authentication information is provided in HTTP headers.
  • HTTP status codes can be ignored as the status is provided in the standard JSON response. Most requests will return a 200 OK with the exception of a 500 Internal Server Error.

The API implements a number of actions which are split into controllers. The documentation is split into the same hierarchy and each controller has it's own section and each action has its own page.

URL

API requests should be made to the following URL and replacing controller & action with the appropriate values for your request.

https://api.viaduct.io/api/v1/controller/action

User Agent

A User-Agent header is recommended but not required. Including such a header will help us help you when debugging any issues you might have when making API requests.

API Limits

API access is currently unrestricted however limits will be imposed in the future.

Parameters

To send parameters to an API action, you must encode them in a JSON hash and send them in the params HTTP parameter. For example, your HTTP body might look like this:

params={"username":"adam"}

Authentication

To authenticate a request to the Viaduct API, you need to send a couple of authentication headers as shown below.

  • X-Auth-Token - the API token
  • X-Auth-Secret - the secret which goes with the API token

If your application needs to authenticate as Viaduct users other than yourself, you need to register your application with Viaduct. Once registered, you will be provided with an application token which must be passed with all API requests in the X-Auth-App header. To obtain user tokens & secrets, you should use one of these login flows.

Alternatively, you can generate a personal access token which will provide you with a token & secret for your own user account. You should not provide any X-Auth-App headers when you authenticate using a personal access token.

Responses

Most responses from the API will be returned as JSON. You can determine the content type using the HTTP Content-Type header. For JSON responses, this will be application/json.

Every request will include a JSON payload similar to this one:

{
  "status":"success",
  "time":1.3,
  "flags":{},
  "data":"..."
}

The status attribute includes the status of the request and can be one of the following values:

  • success - the request was successfully performed
  • not-found - a resource which was requested could not be found
  • error - a generic error message related to your request. The body of these errors will always contain a code and message attribute with details of the error which has been encountered.
  • access-denied - access to the requested action was not permitted
  • parameter-error - the parameters provided were not suitable for this action
  • validation-error - a resource could not be created/updated/removed due to a validation error. This is usually accompanied by errors in the data attribute.
  • maintenance - the API is currently unavailable for maintenance work.
  • internal-server-error - an error outside of your control occurred. Please report these to the team if they persist.

The time attribute specifies how long the request took to perform on the server. This doesn't include any HTTP processing time.

The flags attribute includes extra information for your request. For example, if data is paginated you'll find a pagination flag which will include information about the number of pages and the records returned.

The data attribute contains the actual response. This can be a hash, array , string, integer or just a boolean (true/false) value.