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 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:

Type Description Example
String Text data, such as names and addresses "John Doe"
Number Positive, negative or decimal numbers 100   42.7   -5
Boolean Either true or false. true   false
Null No value. null
Object A 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
}
Array An 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://.

Note

Deprecated security protocols

ShipEngine does not support older security protocols such as TLS 1.0 or any version of SSL. These protocols have been deprecated by the IETF due to security vulnerabilities.

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 perfrming 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.

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: 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:

Method Description
GET Requests one or more resources from the server.
POST Creates one or more new resources.
PUT Updates a resource, or performs an action.
PATCH Adds data to an existing resource.
DELETE Deletes 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).

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 reqeust or response. There are many different types of headers, but these are the main ones that are relevant for ShipEngine:

Reqeust Headers

Header Name Description Example
API-Key Your ShipEngine API auth key API-Key: STlTyUyfFYmw2F2Qqhj8BhRQAfG72HP
Content-Type Tells the server what data format you're sending. ShipEngine only supports JSON format. Content-Type: application/json

Response Headers

Header Name Description Example
Content-Type Tells 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-Length The size of the response data, in bytes. Content-Length: 2537
Date The date/time that the response was sent Date: Fri, 18 Oct 2019 18:00:28 GMT
X-ShipEngine-RequestID A unique ID for every request/response. You can use this for logging, or when opening a support ticket X-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 Code Description Reason
200 Success The HTTP request was successful.
201 Created The requested resource was successfully created.
204 No Content The HTTP request was successful, and the response is empty.
400 Bad Request There's something wrong with your request. See the error code for more details about the problem.
401 Unauthorized Your API key is invalid, expired, or has been deactivated.
404 Not Found The 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
405 Not Allowed The HTTP method you used is not supported by ShipEngine.
409 Conflict The 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.
500 Internal Server Error The server cannot process the request. If this occurrs persistently, then please contact support for help.