This document discusses RESTful microservices and best practices for designing REST APIs. It covers topics like why REST is important for API design, common REST principles, naming conventions, resource relationships, security, versioning, documentation, and management of REST APIs. It also provides examples of how various companies implement practices like filtering, searching, paging, and error handling in their REST APIs. Finally, it discusses how the WebSphere Liberty application server supports REST APIs through features like API discovery and collective APIs.

1. RESTful Microservices
Arthur De Magalhaes
WebSphere REST API Architect
arthurdm@ca.ibm.com

2. Agenda
• API Economy: Why REST?
• Best Practices
• WebSphere Liberty and REST
• Future Directions
• References
1

3. API Economy: Why REST?

4. Why do we need REST?
• So many languages, how do they expose data & functionality
consistently?
• How is communication between all the “Internet of Things”
components?
• REST abstracts languages (client and server), implementations
(libraries), and frameworks (VMs, HA, on-demand)
• But remember, not all REST apps are microservices!
3

5. REST API Principles
4

6. Monetarize existing assets!
5
Systems of Engagement
Systems of Record
Integration bus
Team
Stats
Ticketing
Systems of Insight
Audrey
Cloud App Dev
Ron
Enterprise
Developer
Catalog and
Publish APIs
Discover
APIs
FANAPP
App Server Cloud

7. Best Practices

8. HTTP verbs - use them! (…with caution)
7
• Idempotent - identical requests get the same result
• Safe - can be called without modification to data.

9. Resource Naming
• Use an appropriate resource name rather than the backend name:
• Good: http://api.ibm.com/offering/customers/{customer_name}
• Bad: http://api.ibm.com/offering/UserContextHandler
8

10. Resource Chaining
• Resources in RESTful URLs can be chained together to form a
hierarchy of relationships.
– resource1/{id}/resource2/{id}
• Always use a collection followed by a member
– …/customers/123/orders/456/items/789
– Items belong to orders, orders belong to customers.
9

11. Resource Chaining (2)
• URLs should be Hackable ‘up the tree’
– User should be able to remove the leaf path and get an expected response
back.
– …/customers/123/orders
– Removing the end of the URL up to orders should return back all of the
orders for that customer.
• Do not use members that belong to collections without having the
collection in the path first.
– Good: /customers/123/orders/456/items/789
– Bad: /customers/123/orders/456/789
10

12. Attributes
• A leaf resource will return attributes about itself
GET /employees/1a2b3c
{ “name” : “Bob”, “telephone” : “905-231-3410” }
• Allow attributes to be queried and updated directly (unless read-only or
virtual, like state), but not created from parent resource
Good: GET /employees/1a2b3c/telephone
Good: PUT /employees/1a2b3c/telephone { “416-974-2418” }
Bad: POST /employees/1a2b3c { “newAttribute” : “value” }
11

13. Algorithmic attributes
• Transforming operations into algorithmic attributes
• Example: APIs to start and stop a server
– Bad: POST /servers { “server” : “myhost.com/sv1”, “operation” : “start”}
– Bad: POST /servers { “server” : “myhost.com/sv1”, “operation” : “stop”}
– Good: POST /host/{host_id}/servers/{server_id}/start { ..optional..}
– Good: POST /host/{host_id}/servers/{server_id}/stop { ..optional..}
• Supports a read-only / virtual attribute GET /host/{host_id}/servers/{server_id}/state
– POST instead of PUT, because algorithmic attributes are not idempotent
12

14. Query parameters vs header
• Use query parameters for characteristics that have an affinity to the
resource
– Ex: paging, filtering, sorting
• Use header for characteristics that have an affinity to the whole request
– Ex: security credentials, caching attribute
13

15. Filtering in Industry
• Filtering which fields are returned from the resource
• LinkedIn
– /people:(id,first-name,last-name,industry)
• Facebook
– /joe.smith/friends?fields=id,name,picture
• Google
– ?fields=title,media:group(media:thumbnail)
14

16. Searching / Querying
• Searching for specific resources
• Always apply to a collection
• Best practice is to use “name=value” pairs, matching fields
– Ex: /employees?name=Bob&city=Mooresville
• Non-RESTful examples:
15

17. Paging in Industry
• Paging the results of a resource
https://api.mycompany.com/v1/users?offset=50&limit=50
• Facebook
– offset, before, after, limit, next, previous
• Twitter
– cursor, count, next_cursor, total_count
• LinkedIn
– start, count
16

18. Versioning
• Best practice is to put the version as "vX" after context root, ie:
/myApp/v2, /myApp/v3
• Top level GET should yield what versions are available.
– ie:GET /myApp should return something like {v1 : /myApp/v1, v2:
/myApp/v2}
• No version implies v1, so specifying v1 is optional, but if expecting new
versions to come along, adding v1 from the start is considered best
practice.
17

19. Versioning in the industry
• Twilio
– /2010-04-01/Accounts/
• Salesforce.com
– /services/data/v20.0/objects/Account
• •Facebook
– ?v=1.0
18

20. Versioning should be simple
• Guidelines is to keep major (v1) or major.minor (v1.1) versioning
• Beyond that brings confusion to clients, and hinders server-side
flexibility
• Ex: Docker APIs.
– Which clusters do I have running v1.18 which need to be upgraded?
– Someone requested a v1.21 API, but I routed them to a v1.19 server…
– Client:
if (server.version = v1.23)
….
else if (server.version = v1.22)
…. 19

21. Security of REST APIs
• No security
– Only for trials or prototypes, never for production-level
– Need enforcement of overall transaction rate
• Basic authorization
– Simplest and oldest form of authorization
– User/Password, or Certificates
– Ex: header(“Authorization”, “Basic kjz022zxlksa”)
20

22. Security of REST APIs
• API keys
– Can be simply a key that identifies an user:
• GET /employees/1a2b3c?apiKey=d2lk10xl2
– Can be stronger, and also include a signature of the data which matches a
private key:
• DELETE /employees/1a2b3c?apiKey=d2lk10xl2&sig=3s00xkll213kxxl
• OAuth (OpenID Connect)
– Most modern systems support this authorization method
– Significantly increases the flexibility of your APIs (ie: log into with Google or
Facebook account)
– Can also increase security by utilizing Scopes 21

23. Error handling
• Industry error handling:
22

24. Error handling
• Best practice:
23

25. CORS
• Cross-origin resource sharing
• Web browsers add extra constraints for Javascript code calling to
remote servers, to avoid phishing scams and other attacks
• CORS headers:
– Origin
– Access-Control-Request-Method
– Access-Control-Request-Headers
– Access-Control-Allow-Origin
– Access-Control-Allow-Credentials
– Access-Control-Expose-Headers
– Access-Control-Max-Age
– Access-Control-Allow-Methods
– Access-Control-Allow-Headers
24

26. Documentation: Swagger Introduction
• Industry leading specification for defining REST APIs.
• Supports both JSON and YAML formats.
• Large open source community with various projects on GitHub:
• Client code generation (26 languages).
• Server code generation (9 languages).
• Online editor and GUI.
• Over 2000 related open-source repository, with 15000 daily downloads.
• Base specification for Open API Initiative (https://openapis.org/), under
Linux foundation.
25

27. Documentation: Swagger YAML Sample
26
paths:
/pet:
post:
tags:
- pet
summary: Add a new pet to the store
description: ''
operationId: addPet
consumes:
- application/json
- application/xml
produces:
- application/xml
- application/json
parameters:
- in: body
name: body
description: Pet object that needs to be added to the store
required: true
schema:
$ref: '#/definitions/Pet'
responses:
'405':
description: Invalid input
security:
- petstore_auth:
- 'write:pets'
- 'read:pets'

28. Documentation: Swagger Annotations
• Documents the RESTful endpoint.
• Always in-sync, since it’s together with the code.
27

29. Management
• Rate limiting
– Subscription to APIs; Plans
• API lifecycle
– Deprecation; N – 2 approach
• High availability
• Load balancing (API split)
– Splitting becomes more critical when using hybrid cloud environments
• Logging and auditing
28

30. Languages
29
• A lot of languages to choose from!
• Which is the best one??

31. Languages
30
• Which languages are you familiar with?
• What are your requirements today? (routing, db access)
• What are your requirements tomorrow? (on-prem vs cloud)
• Look at all the entire lifecycle of your REST APIs
• Development, Maintenance, Fire-drills, Upgrades, Access
control, etc.
• Don’t just focus on how quickly they can be made available

32. WebSphere Liberty and REST

33. API Discovery
• All applications are discoverable in a single RESTful endpoint,
/ibm/api/docs
• Query parameter allows filtering based on context root.
• Support both JSON and YAML.
• Application participation can be configured in server.xml (location, on/off).
• Available through apiDiscovery-1.0 feature.
32
Admin UI
Applications
Liberty
REST
APIProviders
API Manager

34. API Discovery User Interface
• Based on the Open Source Swagger UI
• Available at /ibm/api/explorer
33

35. API Discovery Collective Support
• Enabling apiDiscovery-1.0 on a collective member will expose their
aggregated Swagger documentation available.
• Endpoints:
– /ibm/api/collective/docs
– /ibm/api/collective/explorer
34
Admin UI
RepositoryREST
Controller
API Manager
M M
M
REST APIs from Members
M

36. API Discovery Cloud Scenario
• Can push Liberty package into Cloud Foundry
• Creates an auto-discoverable container in the cloud.
• cf push <yourappname> -p wlp/usr/servers/defaultServer
35
app
app
app
WLP
Developer
ibm.biz/wlp-api (dev / dev)

37. 36
1. Git commit java code
2. Travis build is triggered and successful
3. swagger.yaml is extracted from app, using
IBM’s open source offline swagger processor
4. apic’s module is invoked, passing in a committed product.yaml
from Git and generated swagger.yaml
ex: apic publish product.yaml –catalog sb
5. APIs are now available in APIC’s developer portal
CI flow #1: auto-processing APIs during build time

38. CI flow #2: auto-processing APIs after deployment
37
1. Git commit java or node code or dockerfile
6. APIs are now available in APIC’s developer portal
Deploy Invoke
2. Jenkins builds and packages apps & containers, and invokes UCD
3. UCD deploys artifacts onto collective
(on-prem, cloud, etc)
4. UCD invokes “curl POST /ibm/api/collective/docs/apiconnect,”
sending a committed product.yaml as input
M M
MM

39. Future directions

40. Public and Branded UIs | Collective UI redesign
39
• Branded and public Swagger UI
• Inlined collective APIs
[
{
"title" : "ACME Air",
"description" : “Flight booking service",
"version" : "1.0.0",
"hosts" : [ "myHost1:9080",
"myHost2:9085"]
}
]
• Query APIs as services

41. API integration with data
40
1. Many new apps use loopback to quickly expose APIs over a DB
2. Expose these system APIs via a single aggregated Swagger catalog
3. Use the app accelerator (Swagger -> jaxrs client/server) to build interaction APIs that call
various system APIs, and deploy them in Docker containers.
Data Data
system APIs collective
Data
Data
on-premises
interaction APIs
private cloud
app developers
public cloud

42. API integration with other cloud platforms
41
Amazon API gateway Azure API management Google Cloud Endpoint + Apigee
Liberty Collective Docker w/ Liberty

43. Using subset of Swagger to register services
42
• Taking advantage of our discovery framework ‘s dynamic behavior to register and
heartbeat APIs as services
• title, description, version, URL, hosts, plus others
Bluemix Service Registry
Liberty Collective Docker w/ Liberty

44. References

45. Additional Info / Resources
• IBM Middleware User Community (WAS Forum)
https://www.imwuc.org/p/fo/si/topic=1007
• Create and vote for enhancements
https://www.ibm.com/developerworks/rfe
• dwAnswers
https://developer.ibm.com/answers/
• StackOverflow
Tags: swagger, websphere-liberty
44

46. Demonstration
• The following blog introduces 3 videos for API Discovery
http://ibm.co/1Ytyyaa
45