Introduction to REST
The Custom Store API that you will build for ShipStation to consume 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 building your ShipStation Custom Store API.
Resources
REST APIs are centered around resources. Resources are data on which you can perform operations.
For example, one of the resources in your Custom Store will be an order.
JSON
REST allows resources to be represented in any format, such as JSON, XML, CSV, binary, etc. All the resources that you will create for the Custom Store will be in JSON format.
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. | { |
| 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.
ShipStation requires HTTPS and TLS v1.1 or higher for all API calls. This means that all API calls must be made to https://api.my-store.com, not http://.
Note
Deprecated security protocols
ShipStation 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.
Requests & Responses
To call a REST API, ShipStation will send an HTTP request to your Custom Store server. The request contains all the information that ShipStation needs for integration. When the server is finished performing the operation that ShipStation requests, it sends an HTTP response back to ShipStation, which contains all the information necessary for ShipStation to know if the operation it requested was successful or not, and includes any data that ShipStation 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, your Custom Store only needs to use the following methods:
| Method | Description |
|---|---|
| GET | Requests one or more resources from the server. |
| POST | Creates one or more new resources. |
Endpoints
To call your Custom Store API, you will need to create and expose its endpoints, which are a combination of a URL (Uniform Resource Locator) and an HTTP method.
Headers
HTTP requests and responses have a headers section and a data section. The data section contains a REST resource, such as an order 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 your Custom Store:
Request Headers
| Header Name | Description | Example |
|---|---|---|
| Content-Type | Tells the server what data format you're sending. The Custom Store only needs to support JSON format. | Content-Type: application/json |
| Authorization | Used for Basic Authentication, you can use this to enhance the security of your Custom Store implementation | Authorization: Basic ZGVtbzpwQDU1dzByZA== |
| API Key | Used for API-Key based authentication, you can use this to enhance the security | API-Key: 1hGiItv/gzGsjcs8ikF |
Response Headers
| Header Name | Description | Example |
|---|---|---|
| Content-Type | Tells you what data format the server is sending. This will be JSON format. | |
| 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 |
Status Codes
HTTP response status codes let you know whether your API request was processed successfully. ShipStation expects 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. |
| 207 | Multi-Status | The HTTP request was successful and the response contains the status of multiple resources that were updated in this call. |
| 400 | Bad Request | There's something wrong with the ShipStation request to the Custom Store. |
| 401 | Unauthorized | The basic auth or api key that was used to call your Custom Store API is incorrect. |