Introduction

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:

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: