The tables below explain the fields of the above UI.
Make this the default version
All API contexts are suffixed with an API version. The default version option allows you to mark one API, from a group of API versions, as the default one, so that it can be invoked without specifying the version number in the URL. For example, say that the following API versions exist:
You can make any of the API versions as the default version at any time. However, if you mark an unpublished API as the default while the previously default API was a published one, then the users who invoke the default API will still be routed to the previous default version rather than the new one. This is because the new default API version is not published yet.
|See API-level throttling. |
The transport protocol on which the API is exposed. Both HTTP and HTTPS transports are selected by default. If you want to limit API availability to only one transport (e.g., HTTPS), un-check the other transport.
|Sequences||Custom sequences that you want to invoke in the message flow. For details, see per-API sequences.|
Used to enable caching of response messages per each API. Caching protects the backend systems from being exhausted due to serving the same response (for same request) multiple times. If you select the enable option, specify the cache timeout value (in seconds) within which the system tries to retrieve responses from the cache without going to the backend.
Used to specify the tenants who can subscribe to an API, in a multi-tenanted API Manager deployment. The following types of subscription categories are available between tenants:
Scope: See OAuth scopes
Auth type: You can give the following levels of authentication to each HTTP method of the resource:
The auth type is cached in the API Manager for better performance. If you change the auth type through the UI, it takes about 15 minutes to refresh the cache. During that time, the server returns the old auth type from the cache. If you want the changes to be reflected immediately, please restart the server after changing the auth type.
Tier: See Resource-level throttling
Scopes enable fine-grained access control to API resources based on user roles. You define scopes to an API's resources. When a user invokes the API, his/her OAuth 2 bearer token cannot grant access to any API resource beyond its associated scopes.
You can apply scopes to an API resource at the time the API is created or modified. In the API Publisher, click the API -> Add menu (to add a new API) or the Edit link next to an existing API. Then, navigate to the Manage tab and scroll down to see the Add Scopes button. A screen such as the following appears:
|Scope Key||A unique key for identifying the scope. Typically, it is prefixed by part of the API's name for uniqueness, but is not necessarily reader-friendly.|
|Scope Name||A human-readable name for the scope. It typically says what the scope does.|
The user role(s) that are allowed to obtain a token against this scope. E.g., manager, employee.
To illustrate the functionality of scopes, assume you have the following scopes attached to resources of an API:
Assume that users named Tom and John are assigned the employee role and both the employee and manager roles respectively.
Tom requests a token through the Token API as
grant_type=password&username=nuwan&password=xxxx&scope=news_read news_write. However, as Tom is not in the manager role, he will only be granted a token bearing the news_read scope. The response from the Token API will be similar to the following:
Next, John requests a token as
grant_type=password&username=john&password=john123&scope=news_read news_write. As john has both roles assigned, the token will bear both the requested scopes and the response will be similar to the following:
This means that Tom can only access the GET operation of the API while John can access both as he is assigned to both the employee and manager roles. If Tom tries to access the POST operation, there will be an HTTP 403 Forbidden error as follows:
Tip: To invoke an API protected by scopes, you need to get an access token via the Token API. Tokens generated from the My Subscriptions page in the API Store will not work.
Click Save & Publish or click Save to publish the API later. For information on publishing APIs, see Publishing to API Stores.