RESTful API Concepts

Overview

Representational state transfer (REST) is a standard architectural style used for web development. Systems and sites designed using this style aim for fast performance, reliability, and the ability to scale efficiently.

Resources

REST architectures are comprised of resources. Any information that can be named can be a resource - a document or image, a service, a collection of other resources, and so on. Resources comprise data and functionality and are accessed using Uniform Resource Identifiers (URIs). Resources use a set of standard, well-defined operations. Clients and servers exchange representations of resources by using a standardized interface and protocol – typically HTTP, similar to web-based URLs.

HTTP Resource Methods

Another characteristic of REST is the use of resource methods to perform the desired operation. Similar to other RESTful APIs, Shipwell API supports the following set of standard HTTP verbs as resource methods.

• POST
• PUT
• GET
• DELETE

To learn more about HTTP verbs as RESTful methods, see HTTP Methods for RESTful Services and the RFC9110 Specifications.

API Requests and Responses

By default, all API requests expect input in application/JSON format where each request is allowed to contain parameters and other discretionary data types. All JSON requests must specify the object types that the payload is carrying. The sample body request for each object contains the format type, query parameters, and any other required fields the sample body request for each object.

All API call responses return the requested information in JSON format. Responses in XML format are currently not supported. The following examples show the request and subsequent response from the request.

{
    "name": "Test Company,LLC",
    "dba_name": "Test Company",
    "primary_phone_number": "+15128675309",
    "primary_email": "boblabla@gmail.com",
    "mailing_address": "123 Main St. Austin, TX",
    "billing_address": "123 Main St. Austin, TX",
    "identifying_codes": [],
    "billing_email": "boblabla@gmail.com"
}

{
    "id": "00042c38-91cc-4e03-a328-653c02b6504f",
    "name": "Test Company,LLC",
    "dba_name": "Test Company",
    "primary_phone_number": "+15128675309",
    "primary_email": "boblabla@gmail.com",
    "mailing_address": "123 Main St. Austin, TX",
    "billing_address": "123 Main St. Austin, TX",
    "identifying_codes": [],
    "created_at": "2019-07-01T18:13:16.131103Z",
    "updated_at": "2019-07-01T18:13:18.159155Z",
    "billing_email": "boblabla@gmail.com"
}

{
    "error": "ValidationError",
    "error_description": "Invalid input.",
    "field_errors": {
        "company": {
            "non_field_errors": [
                "Invalid data. Expected a dictionary, but got str."
            ]
        },
    },
    "field_errors_condensed": [
        {
            "field_name": "company.non_field_errors",
            "field_errors": [
                "Invalid data. Expected a dictionary, but got str."
            ]
        }
    ]
}

Some endpoint responses default to ascending order and some descending order, based on the data column you wish to sort the response by. To change the default ordering of the response, use the ordering parameter in the GET request with the JSON column prepended by - for descending and + for ascending. For example, to change the order of GET shipments response to begin with the earliest created shipment, enter -created_at into the ordering parameter.

HTTP Status Code

Shipwell uses conventional HTTP response codes to indicate the success or failure of an API request. Every request includes an HTTP status code with the result. The code indicates the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx indicate an error with the provided information and codes in the 5xx range indicate a server-side error.

Successful status codes (2xx)

200 OK - The request was successful.

201 Created - The resource was successfully created. Confirms a success when creating a new employee, time off request, etc.

Client error status codes (4xx)

400 Bad Request - The request was invalid or could not be understood by the server. Resubmitting the request will likely result in the same error.

401 Unauthorized - Your API key is missing.

403 Forbidden - You do not have the correct privileges to perform this action. Verify your API key belongs to an enabled user with the required permissions.

404 Not Found - Can not find with the given identifier. Either the URL provided is not a valid API, or the ID of the object specified in the request is invalid.

406 Not Acceptable - The request contains references to non-existent fields.

409 Conflict - The request attempts to create a duplicate. For employees, duplicate emails are not allowed. For lists, duplicate values are not allowed.

422 Unprocessable Entity - The structure, syntax, etc of the API call was correct, but due to business logic, the server is unable to process the request.

429 Limit Exceeded - The account has reached its employee limit. No additional employees could be added.

Server error status codes (5xx)

500 Internal Server Error - The server encountered an error while processing your request and failed.

502 Gateway Error - The load balancer or web server had trouble connecting to the ACME app. Please try the request again.

503 Service Unavailable - The service is temporarily unavailable. Please try the request again.

Status Code ranges

200–299 as success

400–499 as client request errors

500–599 as server errors