Thursday, October 9, 2014

Design,Implement and Manage a RESTful API with WSO2 API Manager

A proper API has to be intuitive,well documented,consistent  and wrap with security and analytics support.This is where the importance of WSO2 API Manager product comes. WSO2 API Manager is a complete solution to design,implement and manage APIs.It comes with an out of the box  API Publisher  which allows to design the API  properly and convert it to a managed API.API Publisher is the main entry point,which is a web application in which an API developer will starts developing his API and expose it to public.

Basically API Publisher provide capabilities to cover the three API phases of design,implement and manage.

  • Design phase-

The phase in which API creator is planning and designing the API with defining the set of API resources exposed from the API.

  • Implement phase-
The phase in which API creator try to deploy the API and test it as a Prototyped API to check the designed API is working as expected.Additionally API creator can connect with back-end implementation and test it as a sandbox endpoint. Then try to connect with real production endpoint.

  • API manage phase- 
The phase in which ,API creator will engage the value added features as security,throttling to the API.This way the RESTful API will become a managed API as the API creator has engaged policies into it ,in-order to convert it to a more controllable API.

Design APIs with WSO2 API Manager


This is the starting phase of creating a good RESTful API.An API design is a proper definition for the actual back-end implementation,its supporting resources and methods.In other words,it’s the contact for end users who are willing to consume the API.Thus designing the API properly matters.Thus we have introduced API designing capability with API Publisher application in WSO2 API Manager from the released 1.7.0 on-wards.

API designing involves making the API intutitive,well documented and consistent.To achieve these,it has to properly define the API resources and well document them for consuming each.Thus in WSO2 API Manager,we have integrate swagger framework with the API resource defining function.Swagger is a declarative resource specification,which consumers could understand and consume services without knowledge of server  implementation.It' is an open source framework which will describe,visualize and consume a RESTful API.The swagger documentation of methods,parameters and models are tightly integrated to back-end implementation and it allows APIs to always in sync with implementation.

From API Publisher ,design API UI,an API developer can declare API resources with swagger in style.Swagger integration to API Publisher provide support for API developers to define API resources inline with swagger or import pre-defined API resources directly.


Implement APIs with WSO2 API Manager

Next phase is how the API developer can continue testing the designed API.Before exposing the API to public for consuming it,API developers has to properly test the API with its defined API resources set. For this, an API developer can try sampling the responses for each API definition as prototyped APIs and test or either directly connecting to the backend through WSO2 API Manager. With the prototyped APIs concept an API developer could initially test whether he has properly designed API resource definitions without costing additional network delay on connecting to actual backend implementation.The advantage of having a prototyped API is it provides early promotion for the created API.API developer could get early feedbacks from API Consumers as API consumers can consume the prototyped APIs without subscribing to them. A prototyped API can sample its implementation inline with javascript.


Once the API creator deploy and test the API as a prototype,now it has confirmed the API resource definitions are properly defined.Now the missing part is test with actual back-end implementation.For that,API developer can switch the implementation method in ‘Implement’ phase UI of API Publisher to back-end endpoint as shown below.Since this is for testing purposes,better to give the testing environment back-end endpoint as the sandbox url. Then as an APIConsumer a user can subscribe to this API ,generate a sandbox token and continue testing on this.


Manage APIs with WSO2 API Manager

Above has covered how to design a RESTful API,test the implementation and now remaining is expose it as a managed API to the public.In this phase ,with WSO2 API Manager,an API developer can engage policies to an API as throttling ,security and expose it to public for subscriptions.There are more value added features in API manage phase like restrict the API exposing transport either to be http or https,engage additional mediation logics via sequences to fire during API invocations,control API subscriptions.Additionally API Publisher provides capability of managing the API life-cycle.