designing an api
DESCRIPTION
History, design choices, service aggregation, levels of REST,TRANSCRIPT
API Design Choices: Audience,
Aggregation & beyond
By Jacob Ideskog, Solution Architect
@jacobideskog, @2botech
Copyright © 2013 Twobo Technologies AB. All rights reserved.
Agenda
History
Trends
REST
Aggregation vs Mashups
Copyright © 2013 Twobo Technologies AB. All rights reserved.
Disruptive trends
Cloud
Computing
Social
Networks
Mobile
Big
Data
Copyright © 2013 Twobo Technologies AB. All rights reserved.
Back in the days
Copyright © 2013 Twobo Technologies AB. All
rights reserved
Web apps have evolved
from CGI to
the cloud
HTTP, HTML, CGI
COM & CORBA
SOAP & SOA
Web 2.0 & REST
The Cloud
Cloud APIs
How to start?
Design-by-buzzword
Copyright © 2013 Twobo Technologies AB. All
rights reserved
Hypermedia
Node.js
JSON REST
Target Audience
Who is it for?
Apps?
Mobile Apps?
Internal Apps
Other Services?
All of the above?
Copyright © 2013 Twobo Technologies AB. All
rights reserved
Target Architecture
What are you serving
Processing services
Data services
Communication services
?
Copyright © 2013 Twobo Technologies AB. All
rights reserved
The glorious REST
Representional State Transfer
Highly Scalable
Uses URI identifiers
No state on server side
Hyperlinked
No uniform standard
NOT A PROTOCOL
Copyright © 2013 Twobo Technologies AB. All
rights reserved
Resource or service
Copyright © 2013 Twobo Technologies AB. All
rights reserved http://martinfowler.com/articles/richardsonMaturityModel.html
Level 0: The Swamp of POX
Level 1: Resource
Level 2: HTTP Verbs
Level 3: Hypermedia Controls
Glory of Rest
Level 0 Swamp of POX
Copyright © 2013 Twobo Technologies AB. All
rights reserved
Copyright © 2013 Twobo Technologies AB. All
rights reserved
POST <getBook>
POST <deleteUser>
<book ...
<ok ...
/api
XML RPC all over again
Level 1 Resources
Uses URIs
But still XML messages as operations
Copyright © 2013 Twobo Technologies AB. All
rights reserved
POST <getBook>
POST <deleteUser>
<book ...
<ok ...
/books/2
/users/24
Level 2 HTTP Verbs
Utilizes the semantics of HTTP
Copyright © 2013 Twobo Technologies AB. All
rights reserved
GET - Read a resource HEAD – Read metadata about resource OPTIONS – Read what operations are available POST – Add a new resource, or run operation PUT – Replace existing resource completely DELETE – Remove resource (PATCH – Update existing resource in place)
GET ?pagesize=A4
DELETE
200 OK <book ...
201 No Content
/books/2
/users/32
Level 3 The Glory of REST
HATEOAS
Hypermedia As The Engine Of Application State
Or simply: Hypermedia
Let the Media Type tell you what to do
Hyperlink, hyperlink hyperlink
Copyright © 2013 Twobo Technologies AB. All
rights reserved
Example
Copyright © 2013 Twobo Technologies AB. All
rights reserved
curl –v http://localhost/stuff <stuff xmlns:tt=http://example.com/rest tt:rel=”/stuff"> <more-stuff tt:rel="/stuff/more-stuff"/> <other-stuff tt:=”/stuff/other-stuff"/> <data> <entry>Interesting 1</entry> <entry>Interesting 2</entry> </stuff>
curl –v http://localhost/stuff/more-stuff <more-stuff xmlns:tt=http://example.com/rest tt:rel=”/stuff/more-stuff"> <things tt:rel="/stuff/more-stuff/things"/> </more-stuff>
Ring a bell?
Copyright © 2013 Twobo Technologies AB. All
rights reserved
curl –v http://localhost/v2/stuff <html> <div id=“stuff”> <a href=“/stuff/more-stuff”/> <a href=“/stuff/other-stuff/> <ol id=“data”> <li id=“entry1”>Interesting 1</li> <li id=“entry2”>Interesting 2</li> </ol> <form action=“/stuff” > <input type=“text” name=“value” /> </form> </div> </html>
The Real World
But? My API uses other APIs
Copyright © 2013 Twobo Technologies AB. All
rights reserved
The power of Mashups
Web mashup is easy
API mashup is harder
But the payoff is greater
API aggregation is really hard
And believe me, you’ll need to do it anyway…
Copyright © 2013 Twobo Technologies AB. All
rights reserved
Mashups vs. Aggregations
Copyright © 2013 Twobo Technologies AB. All
rights reserved
Mashup Aggregation
Why is it hard
Different backend states and protocols
Different authentication methods
Different lookup schemes
Backend versioning
Copyright © 2013 Twobo Technologies AB. All
rights reserved
1st Original API New
‘Aggregated’ API
2ndOriginal API
Operationally
interesting
Aggregators
Don’t invent the wheel
Once your API is advanced enough, you’ll have to
mash-up
But do you need aggregation?
If so: Identify the “operationally interesting” area
Focus on that
Mashup the rest
Copyright © 2013 Twobo Technologies AB. All rights reserved
The Real World
Ah, the power of API Gateways!
Copyright © 2013 Twobo Technologies AB. All
rights reserved
Summary
Who is it for?
What are you selling?
Hypermedia in REST
Mash-ups vs. Aggregations
Copyright © 2013 Twobo Technologies AB. All
rights reserved
Questions & thanks
@2botech
www.2botech.com
@jacobideskog Copyright © 2013 Twobo Technologies AB. All rights reserved
