Generating SDKs in WSO2 API Manager 3.0.0
Note: WSO2 API Manager 3.0.0 is still a work in progress and as of the time of writing this article, the latest release is WSO2 API Manager 3.0.0-M10.
API Management has become a crucial requirement in the contemporary technological arena due to the fact that most services by various service providers are exposed to users through APIs. With this improvement, APIs have become a major revenue generating model for these service providers and they tend to improve these services so that their customers can have access to a better service experience.
In order to cater to the overwhelming usage of services through APIs, the service providers need a method for proper management of their APIs. WSO2 API Manager and the API Cloud is a fully functional API management solution that has the capability of managing all the stages of an API life-cycle in a massively scalable production environment. WSO2 API Manager is a completely free and opensource tool that can be downloaded and easily setup by referring to the official documentations.
WSO2 API Manager provides a sleek and a user friendly experience to both the API publishers and also the API consumers, so that they can achieve their requirements without facing an inconvenience. System Development Kit (SDK) support is one such feature that is implemented in the WSO2 APIM 3.0.0 with the intention of providing a much better user experience to the API consumers. Working with the SDKs support, API consumers can now have access to APIs, from applications that they have developed. The users can select from a wide variety of programming languages or frameworks to generate SDKs that suit their own requirements and preferences.
Providing an SDK to the consumers is one of the most effective mechanisms to expose a certain service across a multitude of platforms that can cater to various user requirements. SDKs make the life of a developers much simpler because, instead of writing code from scratch, to access the services provided by the service providers, the developer can easily use the SDKs that are generated for a particular service endpoint in the application he/she is developing and simply use call the methods with the required parameters and the SDK will handle the rest by itself. Support for the variety of platforms also takes the mind off of the API developer from worrying about support for various consumers that require various software environments.
APIs are mainly exposed to the consumers through the API Store. With SDK support, consumers can also use software applications to consume the APIs based on the provided SDK that suits the consumers software environment. After subscribing to a particular API and obtaining the required application keys, the consumers can easily write software applications to access the APIs and get the services. They are given the opportunity to select a programming language or framework of their choice from a wide variety of programming languages and frameworks. API consumers do not need to worry about creating complex solutions and mechanisms in order to use the APIs. The SDK provides all the required functions to invoke the subscribed APIs. Therefore, consumers can develop a simple software application by importing the SDK module to the project and use the functions or methods provided, to call the required services and get a response from the API. With this mechanism, a wide range of consumers can use APIs with ease. It will be advantageous to API providers to spread their services across multiple software applications and platforms as well.
SDK generation feature in WSO2 APIM 3.0.0 is powered by Swagger Codegen. It is an open source project which is a template driven engine to generate documentation, API clients and server stubs in a wide range of programming languages and frameworks by simply parsing the OpenAPI specification or the swagger definition of the API.
Design of the SDK generation feature
1.REST API to retrieve list of supported languages
A REST API has been implemented to retrieve a list of supported languages for the SDK generation.
This allows the front end UI to depict the list of languages that are currently configured for SDK generation. By defaultonly 3 (Java, Python, Android) are configured but other languages can be added by changing a configuration file.
Sample request:
GET https://localhost:9292/api/am/store/v1.0/sdk-gen/languages
HEADERS Authorization : Bearer ae4eae22–3f65–387b-a171-d37eaa366fa8
Sample response:
[ “java”,“python”,“android”]
2.REST API to generate SDKs
The second REST API is to generate an SDK for a specific API from a particular language. This allows the user to request an SDK for an API for a language of his/her choice and in return will get to download a zip file containing the SDK. This feature is supported by the swagger-codegen and it supports 41 languages for client stub generation. Swagger-codegen uses the OpenAPI specification (swagger definition) of the API to generate the SDK.
Sample request:
GET https://localhost:9292/api/am/store/v1.0/apis/{apiId}/sdks/{language}
HEADERS Authorization : Bearer ae4eae22–3f65–387b-a171-d37eaa366fa8
Eg: https://localhost:9292/api/am/store/v1.0/apis/890a4f4d-09eb-4877-a323-57f6ce2ed79b/sdks/java
HEADERS Authorization : Bearer ae4eae22–3f65–387b-a171-d37eaa366fa8
There are two parameters in concern.
i) apiId : The unique identifier of the API
ii) language : The programming language for which the SDK should be generated.
Sample response:
<API_NAME>_<LANGUAGE>_<API_VERSION>.zip
Eg: Petstore_java_1.0.0.zip
3.Supported language configurations
By default API Manager Store only supports 3 languages (Java, Python, Android) to generate SDKs. The default configurations are loaded by a bean unless over-ridden by a user specified configuration in the “deployment.yaml”. More languages can be added based on the user requirements by a simple edit to the “deployment.yaml”. The front-end and back-end both utilize the same configuration to show the user, the list of languages, and to generate the SDK respectively. This allowsthe user to add custom language templates, which are not shipped with swagger codegen.
Generating client SDKs in the API Store
Tip: A valid API subscription must exist in order to use the SDK. SDK generation is allowed per API.
By default, SDK generation is enabled for Android, Java and Python. If those languages are sufficient, then move to Step 03.
You also can enable other languages from a list of supported languages, to suit your requirements.
To enable SDK generation for other languages,
Step 01: Deployment.yaml
Open <APIM_Home>/conf/deployment.yaml and edit the file as follows.
Add the language configurations to the file as shown below. In this example Android, Java, Python, C#, and Ruby languages are enabled for SDK generation.
The list of supported languages can be found at the end of the article.
Note: SDK generation is enabled for Android, Java and Python by default even without these configurations residing in the deployment.yaml. Adding these custom configurations will override the default setup. Also mind the letter cases and indentations.
Step 02 : Restart server
Once the file is saved, restart the server.
Step 03 : SDK Tab
In the API Store, open the API and click the SDKs tab and you will find download options for all the languages that you have specified in the configuration.
You can use the search to filter out the specific SDK if there is a long list. The search filter will only appear if there are more than 6 languages in the list.
Step 04 : Download the SDK
Download the SDK by clicking the download button for the preferred language and use it to write software applications to consume the API.
Tip: As mentioned above, a valid subscription should exist for the API. The SDK cannot be used without a valid access token for the subscription.
List of supported platforms
This is the list of supported language for generating client SDKs.
References
