API publishing
Endpoints are made accessible outside of Xapix in one of two ways. Enable API publishing and let users sign up for a basic authorization token (admin API-token). Disable API publishing which disables authentication.
For an overview of API Publishing, view this video.
To manage API access, you do the following:
Enable API publishing.
Select a Rate Limit Store from the list of available defined cache servers.
Set a global Rate Limit for each endpoint in the project. This sets the total number of requests that can be made to an endpoint per selected time period (for example, 100 calls per second).
Define Access Roles which are usage profiles for a given set of endpoints.
Provide the user with the Public URL to login and request an authentication token.
API Publishing allows for managing which users can get access to a project's APIs.
Rate Limit Stores are caches used to store data to improve API call performance. They must be defined in Cache Connections before they become available to API Publishing. Currently, caches can be either Redis or Memcached.
Rate limiting is the number of requests that can be made to an API per window. For example, an API can have 1000 request per hour (window) but this is the total number of requests. Rate limits can be set per user (via Access Roles in User Management) or per endpoint (Rate limit per endpoint in API Publishing). Rate limiting helps the performance of the API by not overloading the API with requests. It can also help to prevent DoS attacks by eliminating the possibility of unlimited API requests. Additionally, if requests to an API starts to become more active, the rate limit can be adjusted in steps to achieve optimum performance for users.
Access Roles are applied to specific users in the User Management page. It consists of settings for rate limit, a role type and a selection of endpoints. The role types can be either no endpoints, all endpoints or a selection of endpoints.
Public URL is the base URL for the endpoint. It is provided to users to request an authentication token and to gain access to projects to which they have been given access.
To allow users to sign up for a basic authentication to access endpoints of a project, API publishing needs to be enabled.
Within a project, select from the Home menu, select API Publishing.
In the Settings pane, set the Enable / Disable slider to On
You can now implement access roles and rate limits for the endpoints in a project.
Before you can enable rate limiting, a caching server needs to be connected to the project.
If no caching server has been selected, an error will appear, as shown below.
You define the cache servers, either Memcached or Redis, using the Cache Connections forms.
Ensure you have defined cache connections. If not, select Cache Connections from the Home menu and follow the procedure to add a new cache connection.
From the Home menu, select API Publishing.
In the Settings page, select a rate limit store from the dropdown menu.
Click Update rate limit store.
The error message will disappear. Rate limits are now be enabled on endpoints.
Access Roles are profiles that determine which resources a user will be able to access.
You can define the rate limit that is applied to any user accessing the API. A rate limit defines the number of unique calls to an endpoint that can be made per time period (per second, minute, and so on). This is in addition to a rate limit set per endpoint (see below).
You can also define the type of access role:
No access - access to any endpoint in the project disabled
All access - full access to all endpoints in the project using a defined rate limit.
Custom access - Selected endpoints using a defined rate limit
When you select Custom Access, you select which endpoints in a project a user can access. The following screenshot shows the currently defined access roles for a project. It contains access roles for each type of role.
Defining a new access role
From the Home menu, select API Publishing.
Click Manage Access Roles to add new API users and set rate limits.
Click New Access Role.
In Create new access role, define the following:
Provide a name for the access role.
Set the rate limit.
Select a role type. If you want a user to access all endpoints, select all_access; to prevent access to any endpoint, select no_access; to have access to only a selection of endpoints, select custom_access.
For custom_access, highlight the endpoints you want using shift-click. The selected endpoints will be highlighted in a grey background.
Click Create to save the new access role.
Each endpoint in a project can have a custom rate limit set. As with access roles, a rate limit defines the number of unique calls to an endpoint that can be made per time period (per second, minute, and so on).
When maximum number of total requests sent by whomever are reached, an error will be returned.
The following screenshot shows rate limits set for two endpoints. One has no rate limit set, the second has a limit of 100 requests per second.
Setting rate limits for an endpoint
From the Home menu, select API Publishing.
Select the menu for an endpoint (down arrow) to expand the endpoint form.
For no limit, leave the calls field blank and click Update.
For a custom limit, enter the number of calls and select a duration, then click Update.
