Using the REST API

The Marketplace Company API is organized around REST. Our API has predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication

Access Tokens are required to authenticate and use the The Marketplace Company API.

Creating an Access Token

Access Tokens can be created and managed from inside your account settings at Settings > Security.

Request

Our API is exposed as an HTTP/1 and HTTP/2 service over SSL. In general, 5 types of request methods are available in most resources, those some might have few or more. We support HTTP versions 1, 1.1, and 2, although HTTP/2 is preferred.

• POST - For creating new object for a resource
• PUT - For full update of a resource. Requires all attributes to be provided, and if any value is not present in the request, the attribute will be considered as empty value.
• PATCH - Recommended approach for partial updates
• GET - Get requests comes into two forms, one for querying a list of attributes and the other for fetching details of a specific item. Each support different kind of query parameters. You see more details in Query Parameters Section
• DELETE - Deletes an item using the id. (Please note that we do only soft-delete, but still this action is irreversible)

Content Type

All requests must be encoded as JSON with the Content-Type: application/json header. If not otherwise specified, responses from the our API, including errors, are encoded exclusively as JSON as well.

Response

Responses are returned with relevent HTTP statusCodes in the response header (see the list of status codes), and a body which is always in the json format. Response body may contain a success reponse or error response. In case of error response, it contains an Error object as mentioned in the document.

Successful response contains a json object which has two attributes in case of GET requests- data[ ] which is always an array of records of the request resource, and metadata which contains the information required for pagination. For requests like POST, PUT, PATCH and DELETE (content modification requests), the response object contains the id of the resource which was actioned.

Below is an example response structure of the GET request for list of records:

{
  "metadata": {
    "total": 200,
    "hasMore": false
  },
  "data": [
    {
      //....attributes
    }
  ]
}

Errors

All API endpoints contain a code and message within the error responses, though some API endpoints extend the error object to contain other information. Each endpoint that does this will be documented in their appropriate section.

Whenever a request is unsuccessful, the API will return an error response with an error type and message. You can use this information to understand better what has gone wrong and how to fix it. Most of the error messages are pretty helpful and actionable.

We follow a standard REST API Error format. An Error Object is defined below, with all properties. Response from an errored API request, will be having a valid error HTTP Response code, and an error object. Here is a list of the error types supported by the API.

"error": {
  "status": 401,
  "code": 01002,
  "type": "authenticationFailure",
  "userMessage": "Please login to continue",
  "message": "request is not authenticated with a valid auth token",
},
"metadata": {
  "hasData": false,
  "total": 0,,
  "hasMore": false,
},
"statusCode": 401,
"data": {},

Status Codes

Here is a list of the different categories of status codes returned by the API. Use these to understand if a request was successful.

Query Parameters

All the GET requests support certain query parameters. There are two kinds of GET requets:

1. LIST - GET for retrieving a list of Recrods. Eg: GET api//?
2. SHOW - GET request for retrieving details of a specific record, by ID Eg: GET api///?

Common Query Parameters

Below is a table of common query parameters, which are supported across entities, with the operations they are supported in, and the common use-cases.

All Query Parameter Operators

Rate Limits

Rate Limits We limit the number of calls you can make over a certain period of time. Rate limits are tracked by IP for public endpoints, and by API key for authenticated endpoints. If you exceed the rate limits, you'll get a 429 Too Many Requests response for subsequent requests. Check the Retry-After header to see how many seconds to wait before retrying the request.

Rate limits vary and are specified by the following header in all responses:

Rate limits are hard limits that apply to the platform when performing actions that require a response from our API.

Versioning

All endpoints and examples are designated with a specific version. Versions vary per endpoint and are not global.

The response shape of a certain endpoint is not guaranteed to be fixed over time. In particular, we might add new keys to responses without bumping a version endpoint, which will be noted in the changelog.

To ensure the security and correctness of your application, make sure to only read the keys from the response that your application needs. Don't proxy entire responses to third-parties without validation.

Old versions of each endpoint are supported for as long as possible. When we intend to deprecate, we will notify users in the changelog section.

Endpoint versions follow the base URL and come before the endpoint. For example:

https:///api/v3/listings