Versions Compared

Old Version 1

changes.mady.by.user Former user

Saved on

compared with

New Version Current

changes.mady.by.user Former user

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: https://github.com/wso2/docs-apim/issues/8

Let's take a look at some concepts and terminology that you need to know in order to follow the use cases.

...

API visiblity level specified in the UIAPI visiblity level specified in the REST API
Publicpublic i.e. visibility=public "visibility": "PUBLIC"
Visible to my domainprivate i.e. visibility=private "visibility": "PRIVATE"
Restricted by rolesrestricted i.e. visibility=restricted&roles=role1,role2,role3"visibility" :"RESTRICTED" , visibleRoles :["role1","role2", "role3"]

Subscription availability

...

URL Pattern

A URL pattern can be one of the following types:

  • As a url-mapping. E.g., /state/town/*
  • As a uri-template. E.g., /{state}/{town}

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:

Code Block
languagehtml/xml
<resource methods="POST GET" url-mapping="/state/town/*">
<resource methods="POST GET" uri-template="/{state}/{town}">

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 state to texas and the value of town to houston. You can use these parameters within the synapse configuration for various purposes and gain access to these property values through the uri.var.provincestate and uri.var.districttown properties. For more information on how to use these properties, see Introduction to REST API and the HTTP Endpoint of the WSO2 ESB documentation.

Also see http://tools.ietf.org/html/rfc6570 on URI templates.

...

The default in-sequence, out-sequence and fault sequences are generated when the API is published.

...

HTTP methods

HTTP methods specify the desired action to be performed on an API's resource. You can select multiple methods from GET, POST, PUT, DELETE, PATCH, HEAD and OPTIONS. A method has attributes such as an OAuth scope, authentication type, response content type, parameters etc. as the diagram below shows:

Image Removed Image Added 
The main attributes of a method are described below:

OAuth scopes define a list of OAuth scopes to an API's resource and assign one of them to each HTTP method.
Response content typeYou can Authentication type

The authentication type can be one of the following:

  • None: No authentication is applied and the API Gateway skips the authentication process.
  • Application: Authentication is done by the application. The resource accepts application access tokens.
    • Application User: Authentication is done by the application user. The resource accepts user access tokensuse the Produces attribute to document in what type the backend sends the response back to the API Manager. Note that this attribute does not do any message type conversion, it is only used as a way of letting the user know the type of response they will receive. You can define the response content type in the Design tab when creating an API.
    ParametersParameters 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. You can define the parameters in the Design tab when creating an API.

    Image Added

    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
    OAuth scopes

    You can define a list of OAuth scopes to an API's resource and assign one of them to each HTTP method. You can define the OAuth scopes in the Manage tab when creating an API as shown above.

    Authentication typeParameters

    You can set the response content type by navigating to the Manage tab, when creating an API, and select the corresponding authentication from the "Application & Application user" drop-down list, which corresponds to the respective resource.

    The authentication type can be one of the following:

    • None: You can select this option to create a non-authenticated API. This will remove the authentication requirements for regular managed APIs, so that the API Gateway skips the authentication process. This is useful in instances when you want to still have the API listed on the API Store home screen and/or when you want to disable authentication requirement for individual resources of an API.

    • Application: The authentication is done by the application and the resource accepts application access tokens. Therefore, if you select this option, the API will require OAuth tokens generated with a client grant type that produces tokens specific to the subscription, but not the end-users. Therefore, if there is a web or mobile application that has subscribed to this API and it has multiple end-users, then they will all share the same token and the API backend will not know which end-user invoked the API.


    • Application User: Authentication is done by the application user and the resource accepts user access tokens. Therefore, if you select this option, the API accepts the OAuth tokens that are generated with the password grant type. These tokens are specific to the end-user, because they not just require the application key, but also the end-user’s username and password. In this case, each end-user gets their own OAuth tokens even though they are using the same API subscription. The API Gateway then generates a JWT token and uses it to pass application and user information to the API backend.
    • Application and Application User: Both application and application
    user  level
    • user level authentication is applied. Thereby, both kinds of tokens are acceptable by the API.
      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.
    Note

    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 typeYou 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.

    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.

    ...

    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. 

    ...

    Code Block
    languagexml
    <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.

    Info

    OAuth provides a method for clients to access a protected resource on behalf of a resource owner. OAuth 2 bearer token is a security token that any party in possession of it can use the token for authentication. Refer OAuth 2.0 Specification of Bearer Token Usage for more information.

    How scopes work

    To illustrate the functionality of scopes, assume you have the following scopes attached to resources of an API: 

    ...