API Introduction

The Rotabull API can be used to fetch RFQs, and generate customer Quotes. Building an application with Rotabull requires getting to know the various concepts and models used in Rotabull.

The API is a REST API. It consists of several resources which support standard HTTP operations (GET, POST) for accomplishing tasks. Each supported resource-operation pair is documented in detail.

Resource Representations

For all methods which accept or return structured data, JSON must be used.

Sandbox

We provide a sandbox environment where you can test out your client code (https://staging.rotabull.com). All quotes sent in the sandbox are automatically reset (i.e., deleted) at the end of each day. Emails will be sent, so please take care to set the recipient email accordingly.

📘

Access and Login

The same account and password used on Rotabull's production site can be used to login to the sandbox site.

❗️

Credentials and Environments

Currently, API credentials are shared between the sandbox and production environments. Please be careful when testing that you are pointed at the correct url.

Response Codes

We use standard HTTP codes to denote successful execution or indicate when errors occur. For some errors, the response will include additional information about the error, including an application error code and human-readable error description.

Successful execution

Operations that execute successfully will return 2xx codes. Where appropriate, they will return the information requested directly in the response body. The table below shows the typical response codes, entities, and headers used for the various HTTP verbs supported by the API:

VerbHTTP Response codeNotesResponse body
GET200The requested data as JSON
POST201Used when the POST will result in a new entity, e.g., placing a QuoteInformation about the inserted item as JSON

Error Handling

Operations that result in an error due to a problem on the client's part (e.g., invalid input) will return standard 4xx codes. Operations that result in an error due to a problem in the Rotabull server will return 5xx codes.

Where a standard HTTP error is sufficiently descriptive, e.g., 401 (Not Authorized) or 404 (Not Found), the response body will be empty. For other cases, we will use the generic response code for client error (400), and the response will include an error entity that gives further details about the error,including an application error code and a human readable error description. The format of this error entity is below, with an example:

{
  "title": "Error",
  "type": "object",
  "properties": {
    "code": {
      "type": "integer"
    },
    "message": {
      "type": "string",
      "description": "User readable description."
    }
  }
}
{
  "code": 3,
  "message": "Invalid Id received."
}

The table below shows the HTTP response codes and entities used for some common error conditions:

Error ConditionHTTP Response codeResponse body
The submitted data was invalid in some way400Error entity, in JSON, with appropriate specific application error code and message, and possibly detail. Each API operation will document the possible application error codes
The user/client API keys were not specified, or were not valid401Empty
Requested operation is not valid (e.g., due to workflow rules or restrictions on the current User's role)403Empty
Requested item (e.g,. Deal, Attachment) does not exist404Empty
There was an unexpected error in the Rotabull application500Empty
API is down for maintenance503HTML that can be ignored