Let's take a look at some concepts and terminology that you need to know in order to follow the use cases.
...
When you add resources to an API, you define a URL pattern and HTTP methods. A resource can also have a list of OAuth scopes.
| URL Pattern | A URL pattern can be one of the following types:
The terms url-mapping and uri-template come from synapse configuration language. When an API is published in the API Publisher, a corresponding XML definition is created in the API Gateway. This XML file has a dedicated section for defining resources. See examples below:
url-mapping performs a one-to-one mapping with the request URL, whereas the uri-template performs a pattern matching. Parametrizing the URL allows the API Manager to map the incoming requests to the defined resource templates based on the message content and request URI. Once a uri-template is matched, the parameters in the template are populated appropriately. As per the above example, a request made to http://gatewa_host:gateway_port/api/v1/texas/houston sets the value of Also see http://tools.ietf.org/html/rfc6570 on URI templates. |
Once a request is accepted by a resource, it will be mediated through an in-sequence. Any response from the backend is handled through the out-sequence. Fault sequences are used to mediate errors that might occur in either sequence. The default in-sequence, out-sequence and fault sequences are generated when the API is published.
...
The main attributes of a method are described below:
| OAuth scopes | You can define a list of OAuth scopes to an API's resource and assign one of them to each HTTP method. |
| Authentication type | The authentication type can be one of the following:
Note that for the resources that have HTTP verbs (GET, POST etc.) requiring authentication (i.e., Auth Type is not NONE), set None as the Auth type of OPTIONS. This is to support CORS (Cross Origin Resource Sharing) between the API Store and Gateway. (The above screenshot shows this). 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. |
| Response content type | You can use this attribute to document in what type the backend sends the response back to the API Manager. Note that this attribute doesn't do any message type conversion, but used simply as a way of letting the user know what type the response will be. |
| Parameters | Parameters of an HTTP method are analogous to arguments of a function in an object-oriented programming language. A resource's parameters are cached in the resource cache at the API Gateway. |
...
Cross-origin resource sharing
Cross-origin resource sharing ( CORS ) is a mechanism that allows restricted resources (e.g., fonts, JavaScript) of a Web page to be requested from another domain outside the domain from which the resource originated.
The Swagger API Console that is integrated in the API Manager runs as a JavaScript client in the API Store and makes calls from the Store to the API Gateway. Therefore, if you have the API Store and Gateway running on different ports, enable CORS between them.
...
The elements are described below:
| XML Elements | Values | Description |
|---|---|---|
| <Enabled> | True/False | Used to enable/disable sending CORS headers from the Gateway. By default, CORS is enabled (True). This is needed for Swagger to function properly. |
| <Access-Control-Allow-Origin> | HTTP and HTTPS Store Address. Change the Host and Port for correct values of your store. For example, https://localhost:9443,http://localhost:9763 | The value of the <Access-Control-Allow-Origin header>. Default values are API Store addresses that are required for swagger to function properly. |
| <Access-Control-Allow-Headers> | Header values you need to pass when invoking the API. For example, | Default values are sufficient for Swagger to function. |
| <Access-Control-Allow-Credentials> | True/False | Specifying this header to true means that the server allows cookies (or other user credentials) to be included on cross-origin requests. The default value is false. If you set it to true, make sure that the Access-Control-Allow-Origin header does not contain the wildcard (*). |
Change your code according to the sample given here.
...
| Code Block | ||
|---|---|---|
| ||
<handlers> <handler class="org.wso2.carbon.apimgt.gateway.handlers.security.CORSRequestHandler"/> </handlers> |
...
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 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 under Resources.
On the screen that appears, enter a scope key, scope name and optionally, allowed roles and a description. Click Add Scope.
| 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 apply the scope, you add the scope to a resource, save and publish the API.
| Tip |
|---|
Tip: When you generate access tokens for applications with APIs protected by scope/s in the API Store, a Scopes drop down list is displayed in the Production Keys tab of the application, where you can select the scope/s after the token is generated.
|
...