APITalkMeetupSharable

Why Are APIs Important?
• Integrations
– External Customers
– Internal Customer
• Partner enablement
– Integration Partners
– Value Added Partners
• Build business logic once and use it everywhere
– Web
– Mobile
– Social
– Others.
• Customer Loyalty

ROA vs SOA
• Resource Oriented Architecture
– Better suited for interactive-human applications with rich user interfaces
– "top-down" usage paradigm.
• Service Oriented Architecture
– typically best for non-human-interactive applications
– "bottom-up" usage paradigm

REST vs. SOAP
 REST is better suited for the following
 Limited bandwidth
 Totally stateless operations
 Caching situations
 SOAP is better suited for the following
 Asynchronous processing and invocation
 Formal contracts
 Stateful operations

REST Adoption
Source: Programmable Web

Relative Adoption Across The
Board

Another Point of View

Introduction to REST Principles
•Give every “thing” an ID
•Link things together
•Use standard methods
•Resources with multiple representations
•Communicate “statelessly”
Source: InfoQ

Give Every “Thing” An ID
 Use URIs to identify everything that merits being identifiable
 Individual items
 Collections of items
 Physical objects
 Virtual objects
 Computation results
 Workflow
 Workflow steps

Link Things Together
 Hypermedia as the engine of application state - HATEOAS
 Follow the links to retrieve/discover more information
 Links allow the client to move from state to another
 Link can be changed thus making the application more robust

Use Standard Methods
• Make use of the standard method:
– GET
– POST
– PUT
– DELETE
• Implicit contract (Idempotent e.g.)
• Pattern driven design
– Lowers the number of APIs
– Lowers learning curve on all sides
• Take advantage of caching

Resources With Multiple
Representations
• Provide multiple representations of resources for different needs.
• Write business logic once
• Adapt the request/response to specific format
– JSON
– XML
– ATOM
– etc.

JSON Adoption

Communicate “Statelessly”
1. Client-server
2. Stateless server
3. Cache stateless
server
client
cache
client
cache
Each request
must contain
all information.
No stored
context on
the server.
Client has the
right to reuse
response data.
Taken from http://blog.apigee.com/detail/hateoas_101_introduction_to_a_rest_api_style_video_slides/

Quick Demo
•Self Discovery
•Support HATEOAS
•Meta Data: Standard vs. Custom
•GET & Partial GET
•Dealing with collection & Search
•Create (POST) & Update (PUT)
•Support for multiple formats

API Design
•Self discovery using the Description API
•Each API is stand alone, stateless transaction
•Each API supports token based authentication
•Stay away from distributed transactions
•RPC style / non-crud operation is done as follows:
– By introducing a virtual entity
– Using POST method

Data Model
-Domains would be normalized (Candidate, Requisition, Application etc.)
-Individual domain would consist of:
- Core attributes
- Composition entities (Candidate > Work History)
- Reference to other aggregate/lookup entities (Candidate > Referrer/Currency)
-Data retrieval would be optimized by doing the following:
- Relationships (Application e.g.) domains will be its own resource.
- Aggregates can be its own resource.
- Common domains (Location e.g.) can have controlled redundancy.

Search
 All standard APIs operate on one resource at a time except Search.
 Allow filters to go across resources
 Support pagination
 Allow for projection of fields
 Query Language
 Ql.io
 YQL
 Custom
 Conscious choice on response verbosity
 Support for HATEOAS using the “Relationship URLs”
 Chatty APIs vs. Coarse Grained

Authentication & ACL
•Build APIs with ACL (function and data) in mind
•Calls must take place over HTTPS with a certificate signed by a trusted CA
•All REST queries should be signed

Versioning
•Versioning may be required if …
– The data that the client app needs to submit has changed
– Distinguish two types of customers apart,
– The client app somehow "knows" the behavior of the old version and is dependent on it.
•Versioning based on URI?
– /customers/1234
– /customers/v2/1234
•How to avoid versioning altogether
– Auto upgrade behavior?
– URL redirect?
– Auto detect expected scenario from payload.
– Version notifications (old/new)
“Versioning is a mechanism that allows providers to
simultaneously maintain two or more sets of business
logic in a consumer-visible way.”
Source: InfoQ
- Service versions are not really an interface
detail. They're an implementation detail that
often leak into the interface.

Adopting for Diverse Clients
 Oracle Fusion TAP (mobile) framework is REST based.
 Introduced new end points that uses one or more REST
 The new end points add a layer on top of the core APIs
 This intermediate layer does three things:
 Adapts the response to conform to TAP format
 Decorates the response to add presentation information
 Aggregates response for multiple calls for TAP consumption

REST Maturity Model
Source: martinfowler.com

Anti Patterns
 Tunneling everything through GET
 Tunneling everything through POST
 Tunneling errors through 200
 Ignoring Caching / eTAGs
 Misusing Cookiesit’s fine if there is resource state, or client state. It’s
session state that is disallowed due to scalability,
reliability and coupling reasons.

Anti Patterns
•Forgetting hypermedia
•Returning HTML in response
•Ignoring mime types
•Not handling side effects of 500 error
•Using API for heavy lifting

Last Thoughts
 Have well thought through and consistent naming conventions
 Handle errors/exceptions graceful with meaningful error messages
 Consider fault tolerance in HA environment,
 Define performance SLA and test for it
 Build in diagnostics and monitoring
 If you need metering/throttling, be sophisticated about it.
 Consider WADL / JSON Schema to help with tooling.

Reference
 InfoQ
 Programmable Web
 Martin Fowler Blogs

APITalkMeetupSharable

More Related Content

What's hot (20)

Viewers also liked (15)

Similar to APITalkMeetupSharable (20)

APITalkMeetupSharable

Editor's Notes