In the API Manager 1.10 release, the API Manager team unveild a new REST API for store and publisher operations. This article will discuss the details of the REST API design, how it was developed, and how you can use the API to generate customized applications that can design, develop, manage, and consume APIs.
Table of Contents
- Introduction
- REST API Design and Implementation Details
- Security Mechanisms
- OAuth Application Registration
- API Invocation
- How to Write a Simple Java Client to Invoke Rest API and Get all APIs
- Conclusion
Introduction
WSO2 API Manager is a complete solution for publishing APIs, creating and managing a developer community, and for scalably routing API traffic. It leverages proven, production-ready, integration, security and governance components from
WSO2 Enterprise Service Bus,
WSO2 Identity Server, and
WSO2 Governance Registry. Moreover, it is powered by WSO2 Business Activity Monitor, thereby making WSO2 API Manager ready for any large-scale deployments right away.
As part of its latest release, the REST API was developed as a CXF REST web application running on WSO2 API Manager. This API comes with a pluggable security mechanism. API security is implemented as a CXF handler, hence if users need to plug custom security mechanism then they can write their own handler and add it to web service. This REST API is implemented based on REST best practices and specifications. The API development started with a swagger specification for store and publisher operations.
In today’s connected world, it’s important to have proper REST APIs for all available software products. Almost all organizations, platforms, and products are connected to each other via APIs to enable a better service. For instance, if you consider a solution like API Management, then a complete API is a must-have feature given that most times users will develop their own API store publisher using APIs that are available in the platform.
Prior to API manager 1.10, we had a Jaggery-based REST API for API Management related common operations; however, it was not fully compliant with REST specifications. Therefore, in the 1.10 version, we decided to implement a complete REST API that complies with all REST-related best practices. We also decided to follow the Richardson maturity model for REST API when we progressed with implementation.
In WSO2 API Manager, you can perform all operations available in the API store and publisher via REST API. From API Manager 1.10 onwards, the product will come with REST API store and publisher features. The API store and publisher Jaggery applications will still support the old REST API. However, if you’re using the WSO2 API Manager 1.10 version or above, it’s highly recommended to use the new REST API to all store and publisher operations.
The contract first approach is not a new design methodology to anyone in the software industry, and in this implementation too we’ve used this approach. We started with a swagger definition for REST APIs and then progressed to design a complete REST API using swagger API description language. When designing the API, we identified resources, resource URLs, and multiple parameters to be pass APIs. All input/output request format response codes, response body, etc. were designed using swagger. For the initial implementation, we’ve incorporated REST API for API store and publisher functionalities. In the future, we will introduce a new API for all management and other operations available in the product.
In the swagger definition, we defined data models for each and every resource object. Hence, each resource would be represented with JSON payload and we can then map them to a Java object. This article will discuss the basics in REST API design, development details, and how you can invoke it. To invoke this REST API, you can use any web service client available in the industry, such as Curl, REST Client, SoapUI, or any others.
With this API, you can make a developer’s’ life easy as it’s a well-defined API. Since we have a complete swagger definition, users can generate client applications using a swagger document or code generation clients based on WADL, e.g. a WADL to Java client.
REST API Design and Implementation Details
These two web applications are implemented as CXF web applications. For this, we used swagger to CXF client and generated a code for web application. As we are generating CXF server side skeleton code directly from the swagger definition, there is a minimal amount of gap between the swagger definition and the actual implementation. In addition, when we make a change to the specification, this can easily be brought into the implementation code. These are major advantages of using a code generator. Once the initial code was generated, we implemented a data access layer.
WSO2 API Manager store and publisher REST APIs are developed as 2 separate CXF web applications named as follows:
- Applications are named as
- api#am#store#v1.war and
- api#am#publisher#v1.war.
- Applications will be deployed in contexts
- api/am/store/v1 and
- api/am/publisher/v1.
These 2 APIs are developed based on swagger definitions for WSO2 API Manager store and publisher. This app development first started with the swagger API definition after identifying all required operations for the API management story. Then the swagger to CXF code generator was used to generate code for web applications. The underlying data access layer will directly call the API manager consumer and provider implementations.
For more details about all supporting methods in this rest API you can use the
swagger console and add WSO2 API Manager store and publisher REST API definitions. Then it will list all operations available in store and publisher (you can find store and publisher swagger definitions for API Magere 1.10 in
this git location.
Security Mechanisms
WSO2 API Manager REST API has complex resource paths for different operations. These resources should be accessible based on user permissions. In real production systems, you would need to be able to manage these permissions as extensively as possible as requirements can change based on user scenarios. Moreover, you should be able to easily add/update permissions per resource/operations and associated users/roles, etc.
For example, let’s consider the following requirement:
API update/edit can be performed only by a special user with API create/update permission; API lifecycle state changes should be carried out by a user who has API publish permission; and tier edit/update should be performed by users with administrative privileges.
Here, you can see that different resources are defined with different permissions and, depending on deployment, these permissions can be changed. As a solution for that requirement, API manager REST APIs will comprise extendable security mechanisms.
According to the current implementation, API manager REST API web applications contain CXF interceptors to handle security. By default, it will have 3 security related interceptors and users can change configuration and select the required mechanism. In summary, we will support the following security mechanisms for REST API:
- Basic authentication
- XACML for fine-grained permission validation
- OAuth with scopes support
If users are willing to have another security mechanism they need to write CXF handler and plug it to web applications. It’s always recommended to use one or more security mechanisms with this API as users can do almost all critical operations using these APIs.
You can change the CXF interceptor by editing WEB-INF/beans.xml files. You can see the following entry for the security interceptor.
As you can see above, by default, REST APIs come with OAuth authentication; if you need to change it to basic authentication you may change the auth handler as follows:
Then you need to pass basic authentication headers along with API calls.
If you are planning to use XACML as fine-grained permission validator, you may add XACML handler in the same way we discussed earlier.
When you hit the XACML flow you will get server URL, username, and password defined in Java code of EntitlementClientUtils class and create a XACML client. If users are willing to use XACML in production, it is recommended to use some kind of configuration file and read these properties from it when you create the XACML client. Thereafter, we will do a web service call to the XACML service that’s running on server using the already created client. To create the XACML policy, you may need to install XACML features into the API manager or use WSO2 Identity Server as the key validator.
For the initial release we will use hard-coded parameters to connect the XACML server and later we will provide additional configuration to be used by this interceptor. To understand XACML usage in API manager you can refer to this article - (http://wso2.com/library/articles/2014/02/use-of-wso2-api-manager-to-validate-fine-grained-policy-decisions-using-xacml/).
By default, OAuth has been enabled as a security mechanism for REST APIs. Refer to the following diagram to understand OAuth flow to obtain token and access APIs.
Figure 1
OAuth Application Registration
Dynamic client registration is a very common and widely used software security implementation. In this case, we have provided web application register Oauth applications using dynamic client registration protocol. However, it’s important to note that this is not a complete implementation of the dynamic client registration specification. In API manager, you will see that the web application has been named client-registration. It’s the CXF web application that’s directly calling the API manager key manager. From WSO2 API Manager 1.9.0 onward, you can plug your own key manager implementation to the API manager product. We have extracted the key manager interface and anyone can write their own implementation for it. We will reuse the same capability here as well. We do not rely on the underlying key manager implementation. We will simply request the key manager object and call its method based on a pre-defined interface for the key manager.
First we have to obtain consumer key/secret key pair by calling the dynamic client registration endpoint. Then you can request an access token with proffered grant type. When doing so, you have to provide scope according to your requirements. The above-mentioned steps are almost the same for the identity server use case as well. Resource registration was not required because we will be using the swagger document as the resource for API. The scope to role mapping will be stored as configuration defined in the /_system/config/apimgt/applicationdata/tenant-conf.json configuration file available in tenants configuration registry.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | "RESTAPIScopes": {
"Scope": [
{
"Name": "API_PUBLISHER_SCOPE",
"Roles": "admin"
},
{
"Name": "API_CREATOR_SCOPE",
"Roles": "admin"
},
{
"Name": "API_CREATOR_PUBLISHER_SCOPE",
"Roles": "admin"
},
{
"Name": "API_SUBSCRIBER_SCOPE",
"Roles": "Internal/subscriber"
},
{
"Name": "API_ADMINISTRATIVE_SCOPE",
"Roles": "admin"
}
]
}
|
Now DCR is available as an installable feature, therefore anyone can install it and use it as per requirement. If you need to use it with the identity server, you can simply install this feature in the product.
Sample request to registration API
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | {
"callbackUrl": "www.google.lk",
"clientName": "rest_api_store",
"tokenScope": "Production",
"owner": "admin",
"grantType": "password refresh_token",
"saasApp": true
}
Sample response
{
"callBackURL": "www.google.lk",
"jsonString": "{\"username\":\"admin\",\"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_credentials implicit\"}",
"clientName": null,
"clientId": "HfEl1jJPdg5tbtrxhAwybN05QGoa",
"clientSecret": "l6c0aoLcWR3fwezHhc7XoGOht5Aa"
}
|
API Invocation
During the API invocation process request, first come to the CXF handler and then it will call an introspection API to validate the token. Post token validation, we will carry out scope validation with the given resource. To validate resources with scope, we will use the API object created by parsing the swagger document of API. Therefore, you don't need to store scopes/API details in databases. It will dynamically generate with swagger content (swagger inbuilt scope association for resources).
If you need to change the permission model, you just have to update swagger/configuration and redeploy application. To maintain scope to role mapping, we will use configuration defined in the WSO2 API Manager configuration file.
As of now we have identified 4 scopes to cover normal use cases:
API_PUBLISHER_SCOPE, publisherAPI_SUBSCRIBER_SCOPE, subscriberAPI_CREATOR_SCOPE, creatorAPI_ADMINISTRATIVE_SCOPE, admin
Token generate request
curl -k -d "grant_type=password&username=sanjeewa&password=sanjeewa&scope=API_SUBSCRIBER_SCOPE" -H "Authorization: Basic SGZFbDFqSlBkZzV0YnRyeGhBd3liTjA1UUdvYTpsNmMwYW9MY1dSM2Z3ZXpIaGM3WG9HT2h0NUFh" https://127.0.0.1:8243/token Token response
1 2 3 | {"scope":"API_SUBSCRIBER_SCOPE","token_type":"Bearer",
"expires_in":3600,"refresh_token":"33c3be152ebf0030b3fb76f2c1f80bf8",
"access_token":"292ff0fd256814536baca0926f483c8d"}
|
How to Write a Simple Java Client to Invoke REST API and Get all APIs
This section will focus on how you can implement Java client to invoke REST APIs. As discussed in previous section, API invocation is carried out in three steps. To register Oauth application, you would need to get an access token and invoke the API by using the following code sample:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 | //Following code block will call dynamic client registration endpoint and register OAuth application
String dcrEndpointURL =getKeyManagerURLHttp()+"client-registration/v1/register";
//This is the app request body. You can create JSON payload with your details for app.
String applicationRequestBody = " {\n" +
" \"callbackUrl\": \"www.google.lk\",\n" +
" \"clientName\": \"fffff\",\n" +
" \"tokenScope\": \"Production\",\n" +
" \"owner\": \"admin\",\n" +
" \"grantType\": \"password refresh_token\",\n" +
" \"saasApp\": true\n" +
" }";
Map<string, string=""> dcrRequestHeaders = new HashMap<string, string="">();
//This is base 64 encoded basic Auth value for user name admin and password admin.
String basicAuthHeader = "admin" + ":" + "admin";
byte[] encodedBytes = Base64.encodeBase64(basicAuthHeader.getBytes("UTF-8"));
dcrRequestHeaders.put("Authorization", "Basic " + new String(encodedBytes, "UTF-8"));
//Set content type as its mandatory for API
dcrRequestHeaders.put("Content-Type", "application/json");
JSONObject clientRegistrationResponse =new JSONObject(HttpRequestUtil.doPost(new URL(dcrEndpointURL), applicationRequestBody,dcrRequestHeaders));
//Now you have consumer key and secret key obtained from client registration call.
//Let's extract these parameters from response message as follows:
String consumerKey =new JSONObject(clientRegistrationResponse.getString("data")).get("clientId").toString();
String consumerSecret =new JSONObject(clientRegistrationResponse.getString("data")).get("clientSecret").toString();
Thread.sleep(2000);
//Now we need to call token API and request access token.
//For this example we will use password grant type. You need to pass correct scope based on the resource you are trying to access.
String requestBody = "grant_type=password&username=admin&password=admin&scope=API_CREATOR_SCOPE";
URL tokenEndpointURL = new URL(getGatewayURLNhttp() + "token");
JSONObject accessTokenGenerationResponse = new JSONObject(
apiStore.generateUserAccessKey(consumerKey, consumerSecret, requestBody,
tokenEndpointURL).getData()
);
//Add consumer key and secret as basic auth header
Map<string, string=""> authenticationRequestHeaders = new HashMap<string, string="">();
String basicAuthHeader = consumerKey + ":" + consumerSecret;
byte[] encodedBytes = Base64.encodeBase64(basicAuthHeader.getBytes("UTF-8"));
authenticationRequestHeaders.put("Authorization", "Basic " + new String(encodedBytes, "UTF-8"));
JSONObject accessTokenGenerationResponse= new JSONObject(HttpRequestUtil.doPost(tokenEndpointURL, requestBody, authenticationRequestHeaders));
//Get access token and refresh token from token API call.
//Now we have access token and refresh token that we can use to invoke API.
String userAccessToken = accessTokenGenerationResponse.getString("access_token");
String refreshToken = accessTokenGenerationResponse.getString("refresh_token");
Map<string, string=""> requestHeaders = new HashMap<string, string="">();
//Check User Access Token
requestHeaders.put("Authorization", "Bearer " + userAccessToken);
requestHeaders.put("accept", "text/xml");
//Call API publisher REST API and get all registered APIs in system. This will return you API array in json format.
HttpRequestUtil.doGet(getKeyManagerURLHttp()+"/api/am/publisher/v1/apis?query=admin&type=provide",requestHeaders);
</string,></string,></string,></string,></string,></string,>
|
Conclusion
In this article, we’ve taken you through a quick introduction into the concepts, implementation details, and how to use API manager REST API. Being aware of REST API is beneficial in terms of either building applications that consume WSO2 API Manager APIs or just a WSO2 API Manager user. Exposing API manager resources via a RESTful API is a flexible way to expose services to the outside world. It helps to meet integration requirements of an API management platform as well as external applications/systems. The details discussed in this article cover just the basics, but is aimed at inspiring you to develop your own application using API manager REST API.
