Embed Size (px)
DESCRIPTION
APIs provide broader opportunities for companies to connect with new partners with the use of APIs itself as an advertising media. A proper design of such RESTful APIs is key to achieving the above-mentioned goals and provides benefits of increasing API performance, reducing the API development effort, and minimizing the operational support burden. WSO2 API Manager helps companies venture into the API space with its own brand and control of an API management platform, providing a great deal of support for designing, implementing, and managing such APIs.
Citation preview
Last Updated: Jan. 2014
Roshan Wijesena & Lalaji Sureshika
API Designing with WSO2 API Manager
WSO2 API Manager Team
**
About the Presenters
๏ Roshan joined WSO2 in march 2014.He is a senior software engineer in the WSO2 API manager team.Prior to joining WSO2, Roshan worked at webgurus as a Senior PHP developer where he was responsible for designing, developing and maintaining complex human resource management applications.
๏ Lalaji joined WSO2 in September 2010. She is a senior software engineer in the WSO2 API Manager team where her main focus is on the development of the product. In addition to her product development efforts she has provided development support and technology consulting on customer engagements, including customer QuickStart programs.
*
About WSO2
*
๏ Global enterprise, founded in 2005 by acknowledged leaders in XML, web services technologies, standards and open source
๏ Provides only open source platform-as-a-service for private, public and hybrid cloud deployments
๏ All WSO2 products are 100% open source and released under the Apache License Version 2.0.
๏ Is an Active Member of OASIS, Cloud Security Alliance, OSGi Alliance, AMQP Working Group, OpenID Foundation and W3C.
๏ Driven by Innovation
๏ Launched first open source API Management solution in 2012
๏ Launched App Factory in 2Q 2013
๏ Launched Enterprise Store and first open source Mobile solution in 4Q 2013
**
What WSO2 delivers
*
What is an API๏ A = Application P = Programming I = Interface
๏ An interface used by software components to communicate with each other - Wikipedia
๏ Example.
My app
API calls
Facebook infrastructure
Interfaces
*
Why is a good API important?● API providers
○ Brand building as a marketing tool.○ Increase interest in the company products and
services.○ Increase website traffic.
● API consumers○ Integration with other great services/infrastructures○Customizable data.
*
REST API
๏ Representational State Transfer is an architectural style that abstracts the architectural elements within a distributed hypermedia system- wikipedia
๏ Is it easy to develop a great REST api? answer is NO.
๏ It should be extremely easy to use for the consumer.
*
Key Elements of a REST API
๏ Verbs๏ Endpoints๏ Status code๏ Filtering๏ Versioning
*
Good design
Resource Sample GET
POST PUT DELETE
api/v1/orders Get the list of
orders
Creates a new
order
Batch update of
orders
return error
Status code 200 OK 201 CREATED 201 CREATED 400 BAD-REQUEST
api/v1/orders/100 Gets a single
order
Return an
error
Update a single
order
Delete an order
Status code 200 OK 400 BAD-
REQUEST
201 CREATED 204 NO CONTENT
*
Characteristics of good REST API design
๏ Intuitive
๏ Documentation
๏ Analytics
๏ Stability and Consistency
๏ Security
*
Intuitive๏ Predictable meaningful URLs๏ Ex-/customers/100/orders/114
๏ Nouns not verbs๏ Base URL is important. ๏ Ex : http://api.pizza.com
๏ Bad practice old RPC style๏ /getOrders๏ /getUsers
๏ Best practice ๏ /Orders๏ /Orders/1
*
Documentation
๏ Should be easy to find and publicly accessible ๏ Show examples of complete request/responses/HTTP
status codes.๏ Give some cURL examples that can directly paste in to
terminal and allow to see results.๏ Clearly define depreciations/updates ๏ Documentation tools. ex Swagger.
*
Stability and Consistency
๏ Less volatile API.๏ support older version of apis quite longer time๏ maintain versioning properly.
๏ Internal consistency.๏ Should not change parameter names and methods๏ same naming conventions throughout entire API
๏ Record and publish changelog.๏ publish any updates globally that everybody can
access.
*
Analytics
๏ Keep track of the version/endpoints of your API being used by Consumers
๏ The most commonly used API calls should be made efficient.๏ You can contact third party developer and let them know
updates๏ Analytics tools.
*
Security
๏ Should be simple must not be difficult to get authenticated
๏ no need to reinvent the wheel. Use existing protocols.๏ Avoid sessions when possible๏ Authorized based on resource content not based on
URL.๏ Use api keys instead of username/password.๏ Basic Auth.๏ oAuth 2.0 + SSL.๏ Openid connect 1.0.
*
Sample of uncompleted JAX-RS REST API๏ GET
๏ /Customers๏ POST
๏ /Customers๏ {"Customer":{"name":"lalaji","address":"hello","age":2}}
๏ PUT๏ /Customers/{id}
๏ DELETE๏ /Customers/{id}
๏ No Baseurl๏ No versioning๏ No security ๏ No multiple response type
*
WSO2 API Manager
๏ WSO2 API Manager is a complete solution for designing, implementing and managing APIs.
๏ It comes with an out of the box API Publisher which allows you to design your API and convert it to a managed API.
๏ API Publisher provides a rich set of capabilities to
-- Design -> Plan and design a good RESTful API
-- Implement -> Deploy and test as a prototyped API
-- Manage -> Publish and expose as a managed RESTful API
*
Key Components
*
Designing APIs with WSO2 API Manager
https://ip:port/publisher/
*
Designing APIs with WSO2 API Manager
๏ Document API in Style -Swagger 2.0 A powerful representation of a RESTful API. An open source framework implementation to describe,visualize and consume a RESTful API.
It provides interactive documentation support.
It’s a declarative resource specification,which consumers could understand and consume services without knowledge of server implementation.
*
Designing APIs with WSO2 API Manager
*
Demo : Designing APIs with WSO2 API Manager
Demo AM 1.8.0 nightly build pack- https://svn.wso2.org/repos/wso2/scratch/chunk13-release/06-10-2014/
*
Demo : Designing APIs with WSO2 API Manager
API Context -customer-service
API Version -v1
API Resources -
HTTP Method URL- Pattern Payload
GET /customers/{id} -
POST /customers {"Customer":{"name":"user1","address":"cmb","age":6}}
DELETE /customers/{id} -
PUT /customers {"Customer":{"id":124,"name":"user1","address":"cmb","age":6}}
*
Implementing APIs with WSO2 API Manager
๏ Implement Inline as Prototyped APIs
-- Provide the ability to expose a developing API as a prototyped
API.
-- Prototyped APIs will provide early promotion for a RESTful API.
-- Can specify the sample implementation inline with Java-scripts.
-- Ability to get early feedbacks for APIs from API consumers
without subscribing.
*
Implementing APIs with WSO2 API Manager
*
Demo : Implementing APIs as Prototyped APIs with WSO2 API Manager
*
Implementing APIs with WSO2 API Manager
๏ Implement with backend endpoint
-- Provide the ability to connect with the real backend
implementation.
-- Supported Endpoint Types
HTTP Endpoint - A REST service endpoint based on a URI template
Address Endpoint - The direct URL of the service
WSDL Endpoint - A WSDL as an endpoint
Failover Group - A group of endpoints connect in a fail-over
manner
Load Balance - A group of load-balanced endpoints
*
Implementing APIs with WSO2 API Manager
*
Managing APIs with WSO2 API Manager
๏ Expose a well designed API as a managed RESTful API.
๏ Engage throttling,authorization and monitoring features to the
API.
๏ Managing through a life-cycle of API.
๏ Make it available for API consumers via subscriptions in APIStore.
*
Managing APIs with WSO2 API Manager
*
Demo : Managing APIs with WSO2 API Manager
**
More Information
● http://wso2.com/products/api-manager/
● https://docs.wso2.com/display/AM170/Designing+APIs
● https://docs.wso2.com/display/AM170/Implementing+APIs
● https://docs.wso2.com/display/AM170/Managing+APIs
● http://swagger.io/
**
Business Model
Contact us !
