RESTful Hypermedia APIs (Representational State Transfer)

Recap of Kevin O’Neill’s talk at YOW night,a review of Meetup API, and

a look into HAL+JSON

@matt_connolly

Wednesday, 3 April 13

REST API for Mobile Apps

Kevin O’Neill, CTO of Playup. REST API for native mobile apps and browsers.REST wins for:

Caching,Performance / scalability.Use custom media types for backward and forward compatibility

Wednesday, 3 April 13

REST vs SOAP, XML-RPC, etc

SOAP:Big web.Strongly typed, complex object types.XML wrapping of remote procedure calls.Commonly found in Enterprise Java applications. Client consumes a WSDL interface and makes HTTP POSTs to a service endpoint.

Wednesday, 3 April 13

XML-RPC:Lighter weight than SOAP, simpler data types.XML wrapping of remote procedure calls.Client makes HTTP POSTs to a service endpoint. Client know the calls available or discovery if server supports “system.listMethods()” and“system.methodSignature(string methodName)”

REST vs SOAP, XML-RPC, etc

Wednesday, 3 April 13

REST vs SOAP, XML-RPC, etc

REST:much more free.Free use of media types (representations):

JSON, XML, etc.Actions follow HTTP verbs: GET, POST, PUT, DELETE, etc.GET requests are cacheable (performance)Resource identified by a URI.Requests can be routed by URI.

Wednesday, 3 April 13

Pros and Cons of REST

Pros:Cacheable,Distributable / Routable,Compatibility,Less bandwidth,Simpler for clients,Freedom of media types.

Cons:HTTP overhead,Methods need to map to resources,More requests,Harder to implement well,Freedom of media types.

Wednesday, 3 April 13

Hypermedia: What’s in a web page

Hypermedia includes text, styles, links, images, etc.

Supports all sorts of different browser capabilities.

Wednesday, 3 April 13

Hypermedia: The HTML of APIs

SOAP & XML-RPC wrap content in documented XML structure.

Data should be discoverable.

Resources map to URLs

URLs shouldn’t change -> broken links.

Wednesday, 3 April 13

Example 1: Blog post

A simple rails Blog app, with a “Post” model.

Example JSON response:

Demo...

Wednesday, 3 April 13

Example 2: Meetup API

GET https://api.meetup.com/2/event/106662252.json

How do we access the group?

Wednesday, 3 April 13

Example 2: Meetup API Docs

Bookmark this: http://www.meetup.com/meetup_api/docs/

App needs to know how to build URLs -> hard coded.

GET https://api.meetup.com/2/groups?group_id={id}

Data is not very descriptive of the API.

Wednesday, 3 April 13

HAL: Hypertext Application Language

http://stateless.co/hal_specification.htmlImplementations for Objective-C, Ruby, PHP, C#, Java, etcRicher JSON (or XML) structure, eg:{ "_links": { "self": { "href": "http://example.com/" } }}

Wednesday, 3 April 13

References

http://www.slideshare.net/KevinONeill1/yow-night-march-2013

http://stateless.co/hal_specification.html

http://37signals.com/svn/posts/3373-getting-hyper-about-hypermedia-apis

Wednesday, 3 April 13