Managing APIs

You manage APIs using the following UI in the API Manager. To get to this UI, follow the instructions in implementing APIs.

The tables below explain the fields of the above UI.

Field	Description
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: http://host:port/youtube/1.0 http://host:port/youtube/2.0 http://host:port/youtube/3.0 If you mark the third API as the default API, requests made to http://host:port/youtube/ get automatically routed to http://host:port/youtube/3.0. 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.
Tier Availability	See API-level throttling.
Transports	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.
Response Caching	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. To configure response caching, edit `<APIM_HOME>/repository/resources/api_templates/velocity_template.xml` file. The cache mediator properties in the XML file are as follows: collector true: Specifies that the mediator instance is a response collection instance false: Specifies that it's a cache serving instance. max MessageSize: Specifies the maximum size of a message to be cached in bytes. An optional attribute, with the default value as `unlimited`. maxSize: Defines the maximum number of elements to be cached.
Subscriptions	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: Available to current Tenant Only: Only users who are in the current tenant domain, i.e., the tenant domain of the API creator, can subscribe to this API. Available to All the Tenants: Users of all tenant domains in the API Manager deployment can subscribe to this API. Available to Specific Tenants: Users of specified tenant domains as well as the current tenant domain (i.e., the tenant domain of the API creator) can subscribe to this API.
Resource settings	Scope: See OAuth scopes Auth type: You can give the following levels of authentication to each HTTP method of the resource: None: The API Gateway skips the authentication process Application: Authentication is done by the application Application User: Authentication is done by the application user Application and Application User: both application and application user level authentication is applied. Note that if you select this option in the UI, it appears as Any in the API Manager's internal data storage and data representation and Any will appear in the response messages as well. 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

OAuth scopes

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.
Roles	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:

"scope":"news_read","token_type":"bearer","expires_in":3299,
"refresh_token":"8579facb65d1d3eba74a395a2e78dd6",
"access_token":"eb51eff0b4d85cda1eb1d312c5b6a3b8"

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:

"scope":"news_read news_write", "token_type":"bearer", "expires_in":3299, "refresh_token":"4ca244fb321bd555bd3d555df39315",
"access_token":"42a377a0101877d1d9e29c5f30857e"

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:

<ams:fault xmlns:ams="http://wso2.org/apimanager/security">
   <ams:code>900910</ams:code>
      <ams:message>The access token does not allow you to access the requested resource</ams:message>
      <ams:description>Access failure for API: /orgnews, version: 1.0.0 with key: eb51eff0b4d85cda1eb1d312c5b6a3b8
   </ams:description>
</ams:fault>

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.