Managing APIs‎ > ‎

API Versions

A typical API evolves over time. You can add or remove resources and change them. Your API's clients typically expect a certain set of resources to be available. To prevent breaking the clients, create an API version. Each API can have more than one API version, each one containing its own set of resources.


Versions are part of the URL of a REST endpoint. The version name is a unique string value that you can use to create different namespaces for different custom resources. API versions are part of the URL so that you can define new resources yet preserve the existing API under an older version.

The last (darkest) portion of the URL reflects the request you are coding. The first part is the name of the API version you are targeting. The second part is the request, which includes your resource name, followed by parameters, such as the primary key, filters, and ordering. Your resource name is either a base table or a defined resource. You can specify resource names with dot notation to access contained resources (for example, OneCustomer.Orders).

Note: Your code might create a prefix for the service/project portion to be prepended to the request.

Best Practice: To facilitate controlled migration over revisions, avoid hard-coding the API version into the URL.

The following image shows an example of the Create, Versions page, including the URL details:

Switch Between API Versions

After you have created a new version, you can switch between versions on the Create, Resources, Resource tab.

Filter by API Version

You can filter by version names in the REST Lab.

For more information about the REST Lab, see Test Using the REST Lab.

Attributes

 Name Type Required Description
 ident integer Y The unique identifier for this object
 ts timestamp Y The date and time when this object was created or last modified
 name string(50) Y The name for this API version. This must be a short name, valid in a URL, so use only letters, numbers, dash, period and underscore.
 comments string(1000) N 
 project_ident integer Y The ident of the project/API that contains this API version