Designing a Beautiful REST+JSON API

In this presentation, Les Hazlewood - Stormpath CTO and Apache Shiro PMC Chair - will share all of the golden nuggets learned while designing, implementing and supporting JSON-based REST APIs, using examples from a clean real-world REST+JSON API built with Java technologies. He will cover:

- JSON-based data formats in a RESTful API
- References to other JSON-based resources (aka 'linking')
- Resource collections and pagination
- How to map (and how not to map) HTTP methods to Resource CRUD
- Resource partial updates
- Supporting HTTP Method Overloading for clients that don't support HTTP PUT and DELETE
- API versioning strategies
- Meaningful Error responses
- Many-to-many resource relationships
- HTTP Caching and Optimistic concurrency control
- Authentication and Security

[Mali]

The best session for learning Rest API. I enjoyed learning.

[yvrelna]

One of the primary advantage of putting version numbers in the Content Type/MIME is that clients wouldn't be all forced to upgrade whole sale if a new API comes in. Clients can use API v2 to access application resource while still using v1 to access accounts resource. And since the HATEOAS URL between these resources are unadulterated URL without format or version specifier, it will all just be part of content negotiation to request different version of the format. The draw back is that supporting multiple version of an API concurrently requires lots of planning and designing and setting Accept Headers isn't as easy as appending to the URL when using regular web browser.

OTOH, if you put version numbering in the URL, you'll have to add special handling to be able to add the version parameter to the URL returned by HATEOAS to requests different versions of the API. The advantage is that it's easier for human to switch between formats/version when navigating the API using regular web browser.

[onetamer]

Excellent presentation! Wes is awesome and very knowledgeable. Heard other presentations by him (on Apache Shiro).

[Rubafix]

Really interesting talk, however the sound quality is horrible.

[RobotalkerSupport]

VERY GOOD! thanks you for sharing your vase knowledge.

[ruixue]

1:03:28 example of a collection resource

[anjin]

can have nested URL paths like you stated - that's not a problem, but you don't want the client interpolating values in those URLs - you want those values pre-populated in the response document before the client reads it.  

This is because UriTemplates are not RESTful (unless you have a special media type that codifies how UriTemplates should work, but that's a whole 'nuther topic outside the scope of what most people expect as 'normal' links).

Think about it - when a web browser access a web page, does it interpolate URLs with variables to get to other pages?  Absolutely not - it simply access whatever URLs are in the current document.

Ideal RESTful APIs embrace HATEOAS: when designing your REST API, think of a REST client like a browser: it should receive an initial 'index' response, and *everything* accessible to the client should be accessible from that initial response or anything that that can be traversed by links.

[unknowmOOsewasfound]

16:45, "head, is what you would kinda expect... "

[robertdewilde]

You should not mix up REST semantics with specific implementation semantics, like the 'HREF' in JSON. You would need to define seperate semantics for each distinct content/media-type.

Better stick to HTTP specifications as much as possible. It already covers this problem through "Web linking" in the HTTP Response in RFC 5988. You can discover using 'cheap' HEAD-requests. (Note: your main HREF seems to be just the Location header?)


Also, exploding/expanding resources does not feel like being very clean. Better use multipart for that purpose, so entities itself don't have to be changed in their representation (and so could be cached); it'll that way still be contained in a single request/response.


Also, you seem to bypass Accept-Ranges by introducing 'limit' and 'offset' query params.


Anyway, I really appriciate the video, great work!

[gabriel_export]

Great information, the speaker knew his stuff and was very concise. The audience kept aggravating me with their incessant interruptions though.

[sb]

i think the OAuth protocol is pretty standardized now

[batbawls]

Having access to these slides would be very helpful. slideshare net / stormpath / rest-jsonapis (there they are)

[nishanth]

love the starting music .. can anyone tell me where I can download this :p

[amidaobscura]

this video is really good about the design of API :) after that I was left with a big interrogation: the authorization part. Could somebody redirect me to some place where we can learn methods about how to define access and authorization rules for a client to interact with our API?

[balls]

you should fix the audio. the echo is VERY distracting

[fatchat]

shazam says it's maXXXimum's "destroy the dancefloor" - the flatline remix (much better than the original)