of 39 /39
REST – Beyond the hype

Lies you have been told about REST

Embed Size (px)

Citation preview

Page 1: Lies you have been told about REST

REST – Beyond the hype

Page 2: Lies you have been told about REST

Who am I?

• Twitter: @darrel_miller

• http://www.bizcoder.com/

Solve API Problems Fast

Page 3: Lies you have been told about REST
Page 4: Lies you have been told about REST

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.

Page 5: Lies you have been told about REST

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

Page 6: Lies you have been told about REST

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

Page 7: Lies you have been told about REST

• 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?

Page 8: Lies you have been told about REST

What are the alternatives?

• Distributed Objects

• Event Based Integration

• RPC

Page 9: Lies you have been told about REST

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

Page 10: Lies you have been told about REST

The birth of Pop REST

• The craving for prescriptive guidance

• Web API Frameworks

• API Management vendors

Page 11: Lies you have been told about REST

Programmable Web

Page 12: Lies you have been told about REST

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.

Page 13: Lies you have been told about REST

Lies you are being told about REST

Page 14: Lies you have been 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

Page 15: Lies you have been told about REST
Page 16: Lies you have been told about REST
Page 17: Lies you have been told about REST

RFC 7320URI Design and Ownership

Page 18: Lies you have been told about REST

“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

Page 19: Lies you have been told about REST

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

Page 20: Lies you have been told about REST

Processing Resources

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

Page 21: Lies you have been told about REST

“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.

Page 22: Lies you have been told about REST

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

Patterns of Enterprise ArchitectureMartin Fowler

Page 23: Lies you have been told about REST

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

{} </>

Page 24: Lies you have been told about REST

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

Page 25: Lies you have been told about REST

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

Page 26: Lies you have been told about REST

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>

Page 27: Lies you have been told about REST

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>

Page 28: Lies you have been told about REST

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

Page 29: Lies you have been told about REST

“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 >

Page 30: Lies you have been told about REST

“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.”

Page 31: Lies you have been told about REST

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

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

}

Page 32: Lies you have been told about REST

“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.

Page 33: Lies you have been told about REST

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

Page 34: Lies you have been told about REST

“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

Page 35: Lies you have been told about REST

“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.

Page 36: Lies you have been told about REST

“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

Page 37: Lies you have been told about REST

The problem with client libraries

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

Page 38: Lies you have been told about REST

So many lies, what is the truth

• Client/Server

• Stateless

• Caching

• Uniform Interface

• Layered

• Code on Demand

Page 39: Lies you have been told about REST

Questions