Designing an API

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

Disruptive trends
Cloud
Computing
Social
Networks
Mobile
Big
Data

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
rights reserved
Hypermedia
Node.js
JSON REST

Target Audience
 Who is it for?
 Apps?
 Mobile Apps?
 Internal Apps
 Other Services?
 All of the above?
rights reserved

Target Architecture
 What are you serving
 Processing services
 Data services
 Communication services
 ?
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
rights reserved

Resource or service
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
rights reserved
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
rights reserved
POST <getBook>
POST <deleteUser>
<book ...
<ok ...
/books/2
/users/24

Level 2 HTTP Verbs
 Utilizes the semantics of HTTP
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
rights reserved

Example
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?
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
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…
rights reserved

Mashups vs. Aggregations
rights reserved
Mashup Aggregation

Why is it hard
 Different backend states and protocols
 Different authentication methods
 Different lookup schemes
 Backend versioning
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!
rights reserved

Summary
 Who is it for?
 What are you selling?
 Hypermedia in REST
 Mash-ups vs. Aggregations
rights reserved

Designing an API

Recommended

Recommended

More Related Content

What's hot

What's hot (14)

Viewers also liked

Viewers also liked (9)

Similar to Designing an API

Similar to Designing an API (20)

Recently uploaded

Recently uploaded (20)

Designing an API