Becoming familiar with Synerise API Reference
Our API reference is an extensive source of knowledge that keeps growing and receiving regular updates.
Take a few minutes to become familiar with the format of the reference and how to navigate it.
For the purpose of this article, we make the following distinctions:
- A service is short for a microservice that exposes endpoints for your usage.
- An endpoint is a resource available at a URL, within a service.
- A method is the HTTP method used with the endpoint, for example GET or POST. An endpoint may expose more than one method under the same URL.
When reading the API reference itself, you may encounter the word endpoint used in the “HTTP method + URL” meaning.
Navigating the reference categories
When you access the main page of the API Reference, you will see tiles that represent logical categories.
Click a tile to see its subcategories as bars.
These bars correspond directly to the subcategories displayed in the left panel of each category's reference page. Once you access a reference page, you don't need to return to the bar view to see another subcategory - instead, click that category in the left panel.
Reading the reference page
- Clicking the Synerise logo takes you to the API Reference home page.
- The buttons on the right lead to other resources.
- The methods are grouped into logical subcategories.
- Each method has a title and an icon that shows the method type.
- The description offers some basic information about the method's usage.
To learn more about permissions, read this article.
- The Authorizations field informs about the type of authorization used by the method. Some methods do not require authorization.
- This is the path of the method. Click to see the full URL.
- The Parameters section includes the headers, path parameters, and query parameters that occur in this method.
- Required entities and fields are marked this way.
- This is the name of the entity.
- This is the type of the entity.
- This is a list of allowed values, if applicable.
- The description offers more detailed information about the entity.
Reading request and response body schemas
The Request body schema section outlines the JSON body of the request, if applicable.
- The arrow means that the entity is an object or an array. Click it to expand the details.
- Some entities have longer descriptions that are initially collapsed for easier browsing. Click to expand.
- The buttons toggle between different schemas of an entity. “One of” means that you can only pick one, “Any of” means that you can pick any combination. If restrictions exist, they are mentioned in the description.
To see the schema of a response, click the bar. The schema expands:
Request and response samples
The samples visualize the schema and offer help in a few programming languages.