Getting Started

Requests & Responses

# Verbs

To make our APIs as predicable and easy to use as possible, we only get GET , POST , and DELETE verbs. Generally in all cases a POST request to a plural endpoint will create a new resource, while a POST to a singular endpoint will update the object.

For example a POST to /v1/locations will create a new location while a POST to /v1/locations/:location will update that specific location.

# Responses

We'll always return the same response object to you whether you do a GET or POST request. All of our responses will have a data property, which is usually the object or array that you are looking for. When retrieving data with a GET request, you should expect that plural endpoints to have an array in the response with a pagination object, while a singular response will have just an object. For example a GET request to /v1/locations will respond with an array of locations, while a GET to /v1/locations/:location will respond with an object in the data property with the singular location that you requested.

# Responses Model

message string
The description of the response, this message can be shown to users.

data object|array
This is the context for the response. If you are creating or retrieving something on the platform, the data will be an object. If you are listing data (e.g: querying shipments instead of shipment), the result will be an array.

status integer
The html response code. 200 or 201 for success, and 4XX and 5XX for errors.

errors array
Errors in the request, normally the fields that failed validation.

code string
The developer-friendly error code to address what happened if there was as error.

pagination object|null
The pagination object if there is more data not included in this response.

endpoint string
The endpoint that was requested.

        /**
 * @typedef Response
 * @type {Object}
 * @prop {String} message - the human readable message for the response
 * @prop {(Object|Array<Object>)} data - the data for the response
 * @prop {Number} status - The status for the response
 * @prop {Array<String>} errors - The errors for the response. Normally inputs that caused the error
 * @prop {String} code - The error code for developers
 * @prop {?Pagination} pagination - The pagination object if the request had more data that was not returned
 * @prop {String} endpoint - The endpoint that was targeted
 */

      

# Pagination

When you query for a plural endpoint like in our /v1/locations example, you should expect a pagination property on the response that will tell if there are more items in the database that have not been returned yet.

# Pagination Model

limit integer
The maximum number of items that could have been returned in the request.

page integer
The current page that is being queried.

has_more boolean
True if there is more data that has not been queried yet.

        /**
 * @typedef Pagination
 * @type {Object}
 * @prop {Number} limit - The limit for the pagination
 * @prop {Number} [page=1] - The page being queried
 * @prop {Boolean} has_more  - If there is more data after this page
 */

      

# Query Parameters

To query for a different page or limit, simply update the query parameters on the request. For example, if trying to query for the next batch / page of locations, your request would look like this:

https://api.packagex.io/v1/locations?page=2&limit=50