REST – Beyond the hype

Who am I?

• Twitter: @darrel_miller

• http://www.bizcoder.com/

Solve API Problems Fast

Objectives

• Very brief history of REST

• Consider the alternatives

• The rise and fall of Pop REST

• The lies you have been told about REST

• Just the facts

• Open question period

You will get more from this if it is interactive, so ask questions, challenge my assertions.

RESTWhat is it and where did it come from?

REST describes the architectural style of the Web

http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm

“Most of REST’s constraints are focused on preserving independent evolvability over time, which is only measurable on the scale of years.”

• How many users do you have? 10, 100, 10000

• How many different client applications do you have?

• Can you force updates on your users?

• Do you even control the clients?

What are the alternatives?

• Distributed Objects

• Event Based Integration

• RPC

Why not SOAP?

• Tooling made SOAP based systems fragile

• XML got blamed for people’s poor use of it

• Tooling forced SOAP to be implemented as RPC

The birth of Pop REST

• The craving for prescriptive guidance

• Web API Frameworks

• API Management vendors

Programmable Web

http://apievangelist.com/2014/04/15/what-are-some-good-examples-of-hypermedia-apis/

FoxyCartA hypermedia example from the world of commerce, providing an example that fits nicely into the API economy.

FamilySearchAn interesting approach to using hypermedia APIs for discovering and managing your family history.

HuddleAn enteprise example of hypermdia APIs from the content collaboration platform huddle.

Amazon AppStream REST APIThe Amazon AppStream web service provides APIs you can call to manage applications hosted on Amazon AppStream and to manage client sessions connecting to those applications.

ClarifyClarify is a self-service API that allows you to make your audio and video files actionable via search and extracted keywords and topics.

Lync Web DeveloperMicrosoft’s Unified Communications Web API (UCWA) is the Next Generation Platform for Mobile and Web Development.

PayPal REST APIOne of the key features of the PayPal REST API is HATEOAS (Hypertext As The Engine Of Application State).

VerticalResponseVerticalResponse's API generally follows the REST model, based on the principles behind HTTP.

Lies you are being told about REST

“Your URLs should be RESTful”

• http://example.org/customer/10

• http://example.org/customer?id=10

• http://example.org/customer/10/edit

• http://example.org/customer/10/close

• http://example.org/9E9AD8EC-B4F5-4000-A74F-1F6CF99C5DDA

RFC 7320URI Design and Ownership

“Expose your entities as resources"• Name the resource

• http://example.org/order/23• http://example.org/order/24• http://example.org/users?name=bob• http://example.org/users?name=bill• http://example.org/location?lat=34&long=23

RFC 3986

RFC 2396

Entity free resources

• http://example.org/dashboard

• http://example.org/printer

• http://example.org/barcodeprocessor

• http://example.org/invoice/32/status

• http://example.org/searchform

• http://example.org/calculator

"instead of trying to figure out what a resource is, think of it in terms of what it does." Leonard Richardson

Processing Resources

https://tools.ietf.org/html/rfc7231#section-4.3.3

“GET/PUT/POST/DELETE == CRUD”

• POST is not necessarily create

• PUT might be create or update

• DELETE doesn’t have to physically delete

• What about PATCH, HEAD, OPTIONS, TRACE ?

CRUD is a uniform way of exposing data

REST is intended to expose an application workflow.

“A REST API is for exposing your data on the web”

Patterns of Enterprise ArchitectureMartin Fowler

“REST has no contracts just return application/json and/or application/xml”

{} </>

GET /some-mystery-resource=>200 OKContent-Type: application/xml

<ivik><spartun gecka="59" gasko="0"/><spartun gecka ="13" gasko ="1"/><spartun gecka ="17" gasko ="30"/><spartun gecka ="8" gasko ="365"/><spartun gecka ="3" gasko ="65535"/>

</ivik >

Let’s talk about contracts

GET /some-mystery-resource=>200 OKContent-Type: application/vnd.acme.cache-stats+xml

<ivik><spartun gecka="59" gasko="0"><spartun gecka="13" gasko="1"><spartun gecka="17" gasko="30"><spartun gecka="8" gasko="365"><spartun gecka="3" gasko="65535">

</ivik>

http://www.iana.org/assignments/media-types/media-types.xhtml

GET /some-mystery-resource=>200 OKContent-Type: application/vnd.acme.cache-stats+xml

<cacheStats><cacheMaxAge percent="59" daysUpperLimit="0"><cacheMaxAge percent="13" daysUpperLimit="1"><cacheMaxAge percent="17" daysUpperLimit="30"><cacheMaxAge percent="8" daysUpperLimit="365"><cacheMaxAge percent="3" daysUpperLimit="65535">

</cacheStats>

GET /some-mystery-resource200 OKContent-Type: application/data-series+xml

<series xAxisType="range" yAxisType="percent" title="% of requests with their max-age value in days">

<dataPoint yValue="59" xLowerValue="0" xUpperValue="0"><dataPoint yValue="13" xLowerValue="0" xUpperValue="1"><dataPoint yValue="17" xLowerValue="1" xUpperValue="30"><dataPoint yValue="8" xLowerValue="30" xUpperValue="365"><dataPoint yValue="3" xLowerValue="365" xUpperValue="65535">

</series>

Other media types that support hypermedia

application/xhtml+xml

application/hal+json

application/vnd.collection+json

application/vnd.siren+json

application/ld+json

application/rdf+xml

application/home+json

application/http-problem+json

application/atom+xml

application/activity+xml

text/uri-list

“Add metadata to be self-descriptive”

<ivik><metadata>

<Description>Max Age caching statistics</Description><Row Name =“spartun” Description=“data point”/><Property Name=“gecka” Type=“int” Descripton=“percentage”/><Property Name=“gasko” Type=“int” Descripton=“max age”/>

</metadata><spartun gecka="59" gasko="0"/><spartun gecka ="13" gasko ="1"/><spartun gecka ="17" gasko ="30"/><spartun gecka ="8" gasko ="365"/><spartun gecka ="3" gasko ="65535"/>

</ivik >

“Serializing DTOs is the best way to return data”

“A REST API should never have “typed” resources that are significant to the client.”

“The only types that are significant to a client are the current representation’s media type and standardized relation names.”

Get /Customer/10=>200 OKContent-Type: application/json

{“name” : “Acme Inc.”,“street” : “87 Fortune way”,“city” : “Winnipeg”,“postalCode” : “T4R 2Y5”

}

“Design your URIs first”

• Design by URI tends to force your resource design into a hierarchy

• Can be constrained by the routing capabilities of your framework

• Discourages the creation of resources that don’t map directly to other implementation concepts

• Focus more on structural relationships between resource rather than workflow relationships.

Home

Speakers

Days

Topics

Sessions Session

Topic

Speaker

AllSpeakers

AllTopics

AllDays

TopicById

SessionsByDay

SpeakerById

SessionsById

SpeakersByTopic

SessionsByTopic

SessionsBySpeaker

Reviews

ReviewsBySession

ReviewsBySpeaker

SessionsByKeyword

SpeakersByName

Conference Hypermedia API

“Adding hypermedia to your representations is inefficient”

• Caching is critical

• Allows correct granularity of resources

• The additional costs of providing hypermedia are far outweighed by its benefits

“You must document the URIs your API exposes”Absolutely need - Media types specifications, link relation specifications, HTTP specification and root URL.

Including URIs in documentation is dangerous for RESTful systems.

Same for return types, error codes.

“You need to build a client SDK for your API”

• http://trafficandweather.io/posts/2013/10/20/episode-18-this-will-be-way-easier

• SDKs can be a crutch for a poorly designed API

• SDKs are expensive to maintain

• SDKs can constrain deployment of new features

The problem with client libraries

PhotoSearchOptions options = new PhotoSearchOptions(); options.Tags = "blue,sky"; PhotoCollection photos = flickr.PhotosSearch(options);

So many lies, what is the truth

• Client/Server

• Stateless

• Caching

• Uniform Interface

• Layered

• Code on Demand

Questions