More Related Content
Similar to Designing an API (20)
Designing an API
- 1. API Design Choices: Audience,
Aggregation & beyond
By Jacob Ideskog, Solution Architect
@jacobideskog, @2botech
Copyright © 2013 Twobo Technologies AB. All rights reserved.
- 4. 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
- 5. How to start?
Design-by-buzzword
Copyright © 2013 Twobo Technologies AB. All
rights reserved
Hypermedia
Node.js
JSON REST
- 6. 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
- 7. Target Architecture
What are you serving
Processing services
Data services
Communication services
?
Copyright © 2013 Twobo Technologies AB. All
rights reserved
- 8. 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
- 9. 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
- 10. 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
- 11. 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
- 12. 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
- 13. 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
- 14. 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>
- 15. 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>
- 16. The Real World
But? My API uses other APIs
Copyright © 2013 Twobo Technologies AB. All
rights reserved
- 17. 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
- 19. 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
- 20. 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
- 21. The Real World
Ah, the power of API Gateways!
Copyright © 2013 Twobo Technologies AB. All
rights reserved
- 22. Summary
Who is it for?
What are you selling?
Hypermedia in REST
Mash-ups vs. Aggregations
Copyright © 2013 Twobo Technologies AB. All
rights reserved