API Reference

Whether you're a seasoned developer or just starting out, this reference can help you build applications that integrate with the marketplace.

The alias OpenAPI specification is designed to adhere to the RESTful principles of predictable resource oriented URLs. It also uses standard HTTP response codes and verbs while encoding all responses in JSON. For each endpoint, you'll find:

• Detailed descriptions that explain how each API works
• Code samples that show how to use the APIs in different programming languages
• Troubleshooting tips that can help you resolve common problems

Authentication

Every request to this API must be authenticated using bearer authentication and authorized using personal access tokens. This means that you must include a valid bearer token in the Authorization header of your request and the token must be one that you have been granted access to through the token manager.

Bearer Authentication

Bearer authentication is a method of granting access to an API using a token called a bearer token. The bearer token is a short string that is issued to a user or application after they have successfully authenticated. The bearer token is then used to make requests to the API, and the server will complete the request if the bearer token is valid. To use bearer authentication, you will need to create a bearer token and then send it to the API in the Authorization header of your request as shown below.

const BEARER_TOKEN = 'mytoken_84cf6c5c734d4c88';

fetch('https://api.alias.org/api/v1/test', {
  headers: {Authorization: `Bearer ${BEARER_TOKEN}`}
})
  .then(resp => resp.json())
  .then(json => console.log(JSON.stringify(json)));

Personal Access Tokens

Personal access tokens (PATs) are a type of bearer token that can be used to grant access to an API to an application. PATs are issued to a specific user and application, and they do not need to be refreshed. This makes them ideal for applications that need to access our API frequently. To create a PAT, you will need to go to the token manager page. You will be asked to provide a name for the PAT and select the scopes that the PAT will have access to. Once you have created the PAT, you will be able to view it in the dashboard. To use a PAT, you will need to include it in the Authorization header of your request. The format of the Authorization header is shown above.

Versioning

The API follows Semantic Versioning. This means that each release will have a version number in the form MAJOR.MINOR.PATCH. We can expect breaking changes during the beta stage of the API.

Major Version

The major version number is incremented when there is a major change to the API. This could be a change in the underlying data model, a change in the way the API works, or a change in the way the API is accessed.

Minor Version

The minor version number is incremented when there is a backwards-compatible change to the API. This could be a new feature, a bug fix, or a minor change to the way the API works.

Patch Version

The patch version number is incremented when there is a backwards-compatible bug fix.

Changelog

• Added commission_cents, commission_percentage, seller_fee_cents into GetOrder endpoint

Pagination

Many top-level API resources contain "list" and "search" versions to be used for reading large data sets. Often times, these list versions of the resource cannot be queried in a single request, and need to be paged over to obtain the entire set. For instance, you can search catalog items in an effort to create listings or analyze pricing insights. These list API methods share a common structure, taking at least two pagination control parameters: limit and paginationToken.

The response of a paged API method represents a single page in an order determined by the specific resource and can be determined by consulting that APIs reference. If you do not specify a paginationToken, you will receive the first page of the dataset. You can specify paginationToken equal to the returned paginationToken of the first page of the queried dataset. This implies that you cannot "skip ahead" of pages or send concurrent requests to receive the entire dataset at once, so please use the appropriate query control parameters (such as filters and facets) of your specified resource to concentrate your queried dataset to only relevant information.

If a given page is not the last page in the dataset, the response will contain a hasMore boolean field value of True, and a paginationToken to be used in a subsequent paged request. Please note that most "list" and "search" requests enforce rate limits, so it is advised to record persistent IDs for re-use in other API operations.

const PATH = 'search';
const LIMIT = 50;
const PAGINATION_TOKEN = '857f6e1f-f01e-4c88-b00d-84cf6c5c734d';
const BEARER_TOKEN = 'mytoken_84cf6c5c734d4c88';

fetch(`https://api.alias.org/api/v1/${PATH}?query=${QUERY}&limit=${LIMIT}&paginationToken=${PAGINATION_TOKEN}`, {
  headers: {Authorization: `Bearer ${BEARER_TOKEN}`}
})
  .then(resp => resp.json())
  .then(json => console.log(JSON.stringify(json)));

Response:

{
  "items": [],
  "nextPaginationToken": "string",
  "hasMore": true
}

Errors

alias OpenAPI uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a resource cannot be found, another process is modifying the resource, etc.). Codes in the 5xx range indicate an error with our servers.

4xx errors that can be handled programmatically include an error code that briefly explains the error reported, as well as a generally helpful error message. It is recommended to handle these errors based off of the error code returned, and not the error message. Error messages can change between versions and may be translated based off of language preferences, but error codes will remain consistent between versions.

Request IDs

Request IDs are universally unique IDs that can be used to identify a request. We often use these IDs to help resolve any issues and to track the historical status and resolution of a request. Request IDs can be retrieved from the standard x-request-id response header returned after each request.

If you file a support ticket or reach out our support email, please include any relevant request IDs to help us facilitate a prompt and accurate response to your question or issue.

const PATH = 'search';
const BEARER_TOKEN = 'mytoken_84cf6c5c734d4c88';

fetch(`https://api.alias.org/api/v1/${PATH}?query=${QUERY}&limit=${LIMIT}&paginationToken=${PAGINATION_TOKEN}`, {
  headers: {Authorization: `Bearer ${BEARER_TOKEN}`}
})
  .then(resp => resp.headers.get('x-request-id'))
  .then(console.log);