The document discusses API design and management using WSO2 API Manager. It provides information about the presenters, WSO2 company, key components of API Manager, and demonstrates designing, implementing, and managing APIs with API Manager. The document recommends API Manager as a complete solution for designing, implementing, and managing APIs through its API publisher and other features.

1. Last Updated: Jan. 2014
Roshan Wijesena & Lalaji Sureshika
API Designing with
WSO2 API Manager
WSO2 API Manager Team

2. **
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.

3. *
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

4. **
What WSO2 delivers

5. *
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

6. *
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.

7. *
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.

8. *
Key Elements of a REST API
๏ Verbs
๏ Endpoints
๏ Status code
๏ Filtering
๏ Versioning

9. *
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

10. *
Characteristics of good REST API
design
๏ Intuitive
๏ Documentation
๏ Analytics
๏ Stability and Consistency
๏ Security

11. *
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

12. *
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.

13. *
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.

14. *
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.

15. *
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.

16. *
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

17. *
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

18. *
Key Components

19. *
Designing APIs with WSO2 API Manager
https://ip:port/publisher/

20. *
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.

21. *
Designing APIs with WSO2 API Manager

22. *
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/

23. *
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}
}

24. *
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.

25. *
Implementing APIs with WSO2 API
Manager

26. *
Demo : Implementing APIs as Prototyped
APIs with WSO2 API Manager

27. *
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

28. *
Implementing APIs with WSO2 API
Manager

29. *
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.

30. *
Managing APIs with WSO2 API Manager

31. *
Demo : Managing APIs with WSO2 API
Manager

32. **
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/

33. **
Business Model

34. Contact us !