Core API Concepts

An API is an application programming interface. It is a set of rules that allow applications to talk to each other. The developer creates the API on the HTTP server and allows the HTTP client to talk to it by making calls and sending messages to the API. Each call to the API is called an API request while the data sent back to the client is called an API response. API request and response message bodies are typically formatted as JSON or XML.

Every time you make a call to a server using an API, it counts as an API request. To make an API request, some APIs require authentication such as the VoyageOne API. When you sign up for an account, you are given API credentials. You authenticate to the VoyageOne API by providing your API credentials in each API request.

The VoyageOne API is a RESTful API. REST stands for "Representational State Transfer" which determines how the API is structured. It is a set of rules that developers follow when they create their API. One of these rules states that you should be able to get a piece of data (called an API resource) which is provided in the response when you call a specific URL (called an API endpoint).

Tip: Although the term endpoint is not officially part of the REST vocabulary as described by the framers of the REST architecture, to those who are versed in APIs, the term "endpoint" can provide for an easy way to talk about REST operations which are comprised of an HTTP method and URL.

Refer to the following sections to learn how to construct an API request to call an API endpoint and perform operations on an API resource:

API Authentication

API authentication is the mechanism of associating an incoming API request with a set of identifying API credentials used to authenticate and authorize access to protected resources. There are several techniques APIs use to authenticate a client. These are called API authentication schemes such as Basic authentication, API key-based authentication and token-based authentication.

The VoyageOne API currently uses a custom API authentication scheme that utilizes a unique Client ID and Token (your API credentials). In short, every API request requires additional headers carrying your API credentials to authenticate and authorize API requests to protected resources.

Note: VoyageOne will soon transition to the OAuth 2.0 framework (a token-based API authentication) for authenticating API requests to the VoyageOne API. Essentially, OAuth 2.0 specifies a process for resource owners to authorize third-party access to their server resources without sharing their credentials. Access tokens are issued to third-party clients by an authorization server with the approval of the resource owner then the third-party uses the access token to access the protected resources hosted by the resource server.

API URL and Endpoints

REST APIs have a base URL to which API endpoint paths are appended. By combining the API's base URL and endpoints, an API request can target a specific resource on which to perform an operation such as creating a product or getting an order.

Base URL

The base URL is defined in the following format:

  <scheme>://<host>/<basePath>

The base URL has the following elements:

All URLs referenced in this document have the following base URL where <basePath> is the version of the VoyageOne API:

  https://sandbox.voyageone.com/v1

API Endpoints

API endpoints are a set of logically related API resources. The URL path for the API endpoint, also known as the URI (for Uniform Resource Identifier), is structured to handle an incoming API request and pass specific information to the API endpoint necessary to prepare the API response.

All API endpoints are relative to the API's base URL. For example, assuming the base URL of https://sandbox.voyageone.com/v1, the /restapi/supplier/order/list API endpoint would be:

  https://sandbox.voyageone.com/v1/restapi/supplier/order/list

Please see Product API Endpoints and Order API Endpoints list of available API endpoints.

API Environments

VoyageOne supports two different API environments to which you can make API requests. The different environments allow you to test your calls to the VoyageOne API before you move your application to production. You address the specific environment you want to target using the API's base URL.

The following table shows the available sandbox and production base URLs.

Environment URL
Sandbox https://sandbox.voyageone.com/v1
Production https://api.voyageone.com/v1

Note: The maximum number of items that can be included regardless of the amount you specify is 100.

Methods

HTTP defines a set of request methods to indicate the desired action to be performed for a given resource. Although they can also be nouns, these request methods are sometimes referred as verbs that include GET, POST, PUT, DELETE, etc. The following example shows the POST method used for the API request:

  POST https://api.example.com/v1/restapi/supplier/order/list

Note: All VoyageOne API endpoints use the POST method.

Headers

Headers allow the client and server to pass additional information with the API request and response. They define the operating parameters of an HTTP transaction. The headers are key-value pairs separated by a colon and terminated by a new line.

You must include headers with each API request to interact with an API. Some headers are optional such as the Content-Type and Accept headers while others are required. The VoyageOne API requires a custom header, called Client-Id, to be included along with the standard Authorization header, both of which are used to supply API credentials for access to API resources.

Body

Both API requests and responses can contain a body or often called a "payload." The API request body is used to send either parameters or a data collection to an API while the API response body is used to return either a response status (including error messages) or data collection.

API request and response bodies are typically in a structured format such as JSON or XML. JSON is most widely used data format for data interchange on the web. JSON is a lightweight text based, data-interchange format and is completely language independent. It is based on a subset of the JavaScript programming language and it is easy to understand and generate. With the VoyageOne API, request and response bodies are always formatted in JSON.

You pass parameters to an API endpoint to influence the result. For example, when making an API request to retrieve a large result of products, the VoyageOne API allows you to specify pagination parameters to control how many products are returned in each response as shown below:

{
  "pageNo": 1,
  "pageSize": 100,
  "createdTime": [null, null]
}
You pass a data collection to an API endpoint when you are performing an operation on a resource such as when making an API request to update inventory for a product as shown below:

{
  "items":
  [
    {
      "sku": "example-product-sku",
      "qty": 100
    }
  ]
}

Finally, the API response body contains the result of theoperation initiated by the API request. With the VoyageOne API, API responses will always return a code and a data name/value pair.

Response Status Codes

The VoyageOne API only returns HTTP status codes for standard HTTP server success and error statuses such as 200, 400, 401, 403, 404 and 500. But it does not utilize HTTP status codes to communicate successful or unsuccessful operations on an API resource like typical REST APIs. Instead, status and error codes are returned in the body of each API response.

All responses to API requests are returned with the HTTP Status 200 (OK) while errors are communicated with an error code and a message as shown in the following example:

{
  "code": "E1010074",
  "data": null,
  "message": "The data[items[0].qty] cannot be less than 0."
}