Understand API Terminology

REST APIs

A REST (Representational State Transfer) API allows developers to execute operations on that system by exchanging copies of data (transferring the state) so that the server does not store any client session information (the server is stateless).

APIs and Webhooks

APIs (application programming interfaces) are messages between one system and another. The Delivery Hub API is mostly used to send information from an Order Management System (OMS) to Delivery Hub. For example, the most commonly used API calls include order and customer information. You can also send APIs to request information that is not included in webhooks, such as the type of packaging used for an order.

A REST (Representational State Transfer) API allows developers to create, read, update, and delete (CRUD) resources such as products, orders, and customer information. REST APIs are stateless, meaning that each call includes all the data needed to complete that request, so the comunication between apps does not rely on information saved on a server. This makes

Webhooks are like subscriptions to events. For example, after you send an order to Delivery Hub using an API call, you can then automatically subscribe to the order's status updates via webhook.

Verbs

Post: send this to create an entity

get: request information from Delivery Hub

put: update an entity that already exists in Delivery Hub

delete: delete an entity that exists in Delivery Hub

Patch: change specific fields or attributes of a resource without resending the entire resource.

API Structure and Hierarchies

Array: A list of objects (records or items) and the data pertaining to each object. For example, in Delivery Hub, an array of products is a list of products included in an order.

Object: A single record, such as a product, customer, or fulfillment.

Attribute: A detail of an object in an array. For example, an attribute of a product might be its weight, and the attribute of a customer could be a street address.

Access Management

Scopes are permissions or access controls that limit a client's access to specific endpoints and their respective actions and resources within an API. For example, you can limit your OMS to endpoints related to orders and your HR system to endpoints related to employees.

TTL, or Time to Live, is the amount of time that data remains valid. This term is often used to refer to the amount of time that an access token is valid. Learn more.

Transport Layer Security (TLS) is a protocol for securing communication between systems using encryption and authentication mechanisms. This prevents any system that intercepts the data from reading it. While OAuth prevents Delivery Hub from accepting and sending data without a token, TLS ensures that approved data exchanges are secure.

A TLS cipher suite is a set of algorithms that are used to secure communication over a network. For Delivery Hub's APIs, TLS and cipher suites are used to encrypt and decrypt API calls. Each system with a TLS certificate will support several cipher suites. During the TLS handshake process, the two communicating systems negotiate and agree on a mutual cipher suite to use.