Design an External API Store

WSO2 API Cloud allows you to perform all the operations which you do in the API Store, remotely done through an external application which you have written and hosted in your environment. This feature helps you if you are interested in having a highly customizable API Store where the total control of all aspects of the API Store will be in your hands. This section describes how you can design and build up your own API Store to run against WSO2 API Cloud using the WSO2 Store REST APIs. This includes the best practices and an understanding of a secure design and architecture and makes building up your own API Store a hassle free experience.

Guidelines for developing the middle tier

We suggest having a separate backend component written, to handle the authorization token generation, when developing the custom API Store application in the integration cloud.This backend component can be written in MSF4J or any other language of your choice.

The main responsibilities of the middle tier are listed below. All the calls which reach the front end goes to WSO2 through this intermediate middle tier.

• Calling the WSO2 OAuth2 endpoint(key generation service) to retrieve the access token.
• Requesting for refresh tokens once the current tokens expire.
• Handling the secure invocation to the WSO2 Cloud REST APis.

The diagram below illustrates the structure of this middle tier application and how to use an external store application to consume the WSO2 REST APIs. The middle tier also known as the backend application will be responsible for handling the operations shown inside the red box. 

The following are the three middle tier functionalities handled by the middle tier(backend application). Make sure that all these functions are implemented when you write your backend application.

1. Invoking Admin REST APIs
   
   
   (a) Password Grant
   (b) Refresh Token Grant 
2. Logging in and storing subscriber access tokens
   
3. Invoking Store REST APIs
   

REST API invocation guidelines

This section explains the main concepts behind invoking the WSO2 API Cloud Subscriber Authentication and Registration REST APIs. All the REST APIs which are exposed to be consumed are authenticated using the password grant type. The password grant type requires to pass credentials to the token endpoint in order to retrieve a valid OAuth2 token. A predefined set of admin user credentials is used if the username and password are not provided through the frontend store application. See REST APIs to be invoked with an Admin token for a list of  REST APIs that require the admin user’s credentials when making the calls to the token endpoint.

REST APIs to be invoked with an Admin token

• Subscriber Invitation API
• Subscriber Invitation Verification API
• Subscriber Registration API
• Reset Password Initiation API
• Reset Password Verification API
• Reset Password Confirmation API

REST API Endpoints to be invoked with subscriber access token.

This token is received and stored in the session when the subscriber logs in to the front end app.

• API Store REST APIs
• API Store Statistics APIs

Prerequisite - Storing the client id and client secret to make requests

This is also known as dynamic client registration. You need to have an OAuth2 token to invoke the REST APIs. You can obtain the OAuth2 token by passing the client id and client secret, which can be retrived by calling the dynami  client registration endpoint. The steps shown in the above diagram are described below.

1. The admin user needs to send a request to the WSO2 Dynamic Client Registration Endpoint manually. For more details on the request format, see the Store REST API documentation. You can use curl or a simple REST client to send this request.

   Make sure to use the email of the admin user in the payload. Invoke the dynamic client registration endpoint with the credentials of an admin user to obtain the client id and secret for the admin user, since you need a user with more privileges to perform these actions, due to security concerns.

2. The dynamic client registration endpoint will return the client id and client secret of the admin user in the response. A sample response is given below.

   {
       "callBackURL": "www.google.lk",
       "jsonString":
       "{
       \"username\":\"email_username@Org_key\",
       \"redirect_uris\":\"www.google.lk\",
       \"tokenScope\":[Ljava.lang.String;@3a73796a,
       \"client_name\":\"admin_rest_api_store\",
       \"grant_types\":\"authorization_code password refresh_token iwa:ntlm
       urn:ietf:params:oauth:grant-type:saml2-bearer client_credentialsimplicit\"
       }",
       "clientName": null,
       "clientId": "HfEl1jJPdg5tbtrxhAwybN05QGoa",
       "clientSecret": "l6c0aoLcWR3fwezHhc7XoGOht5Aa"
   }

3. Store the client id and client secret in your backend application as a configuration reference.

Making requests to the REST APIs through the external custom Store application.

Admin REST APIs and subscriber login functions

The diagram above explains the concept behind invoking the REST APIs listed above through the frontend app (Store app) and also covers the flow of the login call done to get the user’s access token. 

Store APIs invoked by subscribers

The diagram below explains the the concept behind invoking the REST APIs through the frontend app (Store app) provided that the user’s access token has been obtained using the logic call before this. 

Access token generation and regeneration

The diagram below explains the how the access tokens, used to invoke the REST APIs, are generated/regenerated.

(a) Obtain an access token using the password grant

(b) Obtain an access token using the refresh token grant

(c) The recommended path when you receive an unauthorized response. This would imply that the token has expired.

(d) This method can also be used when an unauthorized response is received while invoking the REST APIs. However (c) is recommended.