1. Getting Started
  2. Requests & Responses

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.

total_count integer
The total number of items matching the query filters in the database.

        /**
 * @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
 * @prop {Number} total_count - The total count of objects matching the search params in the database
 */

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

Previous <- Authentication
Next Sandbox ->