Introduction to REST

ShipEngine is a REST (REpresentational State Transfer) API, which means that it follows certain HTTP conventions for things like URLs, methods, headers, and status codes. If you're not yet familiar with REST, then this page is for you. We'll explain the basics that you need to know to get started with ShipEngine.

Resources

REST APIs are centered around the concept of resources. Resources are data on which you can perform operations. For example, one of the resources in ShipEngine is a Label, and the operations that you can perform on a label include creating a label, querying labels, and voiding labels.

JSON

REST allows resources to be represented in any format, such as JSON, XML, CSV, binary, etc. Almost all resources in ShipEngine are in JSON format. One notable exception to this is label images, which can be downloaded in a variety of formats.

JSON is a convenient format to represent REST resources because it's human readable, compresses well, and is supported by all modern programming languages. In addition, JSON is fairly easy to understand because it only has a few data types:

TypeDescriptionExample
StringText data, such as names and addresses"John Doe"
NumberPositive, negative or decimal numbers100   42.7   -5
BooleanEither true or false.true   false
NullNo value.null
ObjectA set of key/value pairs inside curly braces. The keys are always strings, but the values can be any JSON data type.{
"name" : "John Doe",
"age": 37,
"is_married": true
}
ArrayAn ordered list of values inside square brackets. The values can be any JSON data type.["red", "green", "blue"]

HTTP

REST APIs communicate using HTTP (HyperText Transfer Protocol) or its more secure sibling, HTTPS (HTTP Secure), which uses TLS (Transport Layer Security) to encrypt request and response data.

ShipEngine requires HTTPS and TLS v1.1 or higher for all API calls. This means that all API calls must be made to https://api.shipengine.com, not http://.

See our Security & Authentication Guide for more information.

Requests & Responses

To call a REST API, you need to send an HTTP request to the server. The request contains all the information necessary to tell the server (e.g. ShipEngine) what you want it to do. When the server is finished performing the operation that you requested, it sends an HTTP response back to you, which contains all the information necessary to let you know whether the operation was successful or not, and includes any data that you requested.

All HTTP requests consist of four parts: method, endpoint, headers, and JSON data. You can learn more about the anatomy of an HTTP request on our blog.

HTTP responses consist of just three parts: a status code, headers, and JSON data.

Methods

The HTTP protocol includes many different "methods" (also called "verbs"), such as GET, POST, PUT, PATCH, OPTIONS, and more. Each of these methods instructs the server to perform a certain operation on a resource. To keep things simple, ShipEngine only uses the following methods:

MethodDescription
GETRequests one or more resources from the server.
POSTCreates one or more new resources.
PUTUpdates a resource, or performs an action.
PATCHAdds data to an existing resource.
DELETEDeletes or deactivates a resource.

Endpoints

To call a ShipEngine API, you have to know its endpoint, which is a combination of a URL (Uniform Resource Locator) and an HTTP method. For example, to create a shipping label, you need to call the POST https://api.shipengine.com/v1/labels endpoint. In this case, the POST method tells the server that you want to create a new resource, and the /v1/labels URL path tells the server what kind of resource you want to create (a label resource).

URL Query Parameters

Some HTTP requests may also include URL query parameters, which are used by the server to filter the data returned. A query parameter consists of a key-value pair, such as carrier_id=se-28529731.

Query parameters can be specified by including them directly in the URL using a ? to indicate that query parameters follow. For example, https://api.shipengine.com/v1/labels?carrier_id=se-28529731. This example tells ShipEngine to return all the labels with the specified carrier ID. If we did not include this portion in the URL, ShipEngine would have returned all the labels ever created, regardless of carrier ID.

If you wish to include multiple parameters in the URL, simply separate each set of parameters with an &. For example, https://api.shipengine.com/v1/labels?carrier_id=se-28529731&warehouse_id=se-1234. This example tells ShipEngine to return all labels with the specified Carrier ID and the specified warehouse ID.

Example Request

1
2
3
4
GET /v1/labels?created_at_start=2020-11-09T00:37:54.14212Z&created_at_end=2020-11-09T22:37:54.14212Z HTTP/1.1
Host: https://api-stage.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

Headers

HTTP requests and responses have a headers section and a data section. The data section contains a REST resource, such as a label in JSON format. The headers section contains metadata about the request or response. There are many different types of headers, but these are the main ones that are relevant for ShipEngine:

Request Headers

Header NameDescriptionExample
API-KeyYour ShipEngine API auth keyAPI-Key: STlTyUyfFYmw2F2Qqhj8BhRQAfG72HP
Content-TypeTells the server what data format you're sending. ShipEngine only supports JSON format.Content-Type: application/json

Response Headers

Header NameDescriptionExample
Content-TypeTells you what data format the server is sending. This will be JSON format, except for label downloads, which can be in a variety of formats.Content-Type: application/json
Content-LengthThe size of the response data, in bytes.Content-Length: 2537
DateThe date/time that the response was sentDate: Fri, 18 Oct 2019 18:00:28 GMT
X-ShipEngine-RequestIDA unique ID for every request/response. You can use this for logging, or when opening a support ticketX-ShipEngine-RequestID: c6c453ca-37e9-4326-9d32-e72da2ae4195

Status Codes

HTTP response status codes let you know whether your API request was processed successfully, or if an error occurred. ShipEngine uses the following status codes:

Status CodeDescriptionReason
200SuccessThe HTTP request was successful.
201CreatedThe requested resource was successfully created.
204No ContentThe HTTP request was successful, and the response is empty.
207Multi-StatusThe HTTP request was successful, but contains separate response codes that each need to be evaluated
400Bad RequestThere's something wrong with your request. See the error code for more details about the problem.
401UnauthorizedYour API key is invalid, expired, or has been deactivated.
404Not FoundThe resource you requested does not exist. For example, a request to v1/shipments/se-123456 would return a 404 status code if there is no shipment with an ID of se-123456
405Not AllowedThe HTTP method you used is not supported by ShipEngine.
409ConflictThe request conflicts with the current state of the server. For example, you may be attempting to create a resource that already exists, or ship a package that has already been shipped.
500Internal Server ErrorThe server cannot process the request. If this occurrs persistently, then please contact support for help.