Download to read offline
More Related Content
Similar to Lies you have been told about REST
Lies you have been told about REST
- 1. REST – Beyondthe hype
- 2. Who am I? •Twitter: @darrel_miller • http://www.bizcoder.com/ Solve API Problems Fast
- 4. Objectives • Very briefhistory 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.
- 5. REST What is itand where did it come from? REST describes the architectural style of the Web http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
- 6. “Most of REST’sconstraints are focused on preserving independent evolvability over time, which is only measurable on the scale of years.”
- 7. • How manyusers 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?
- 8. What are thealternatives? • Distributed Objects • Event Based Integration • RPC
- 9. 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
- 10. The birth ofPop REST • The craving for prescriptive guidance • Web API Frameworks • API Management vendors
- 11.
- 12. http://apievangelist.com/2014/04/15/what-are-some-good-examples-of-hypermedia-apis/ FoxyCart A hypermedia examplefrom the world of commerce, providing an example that fits nicely into the API economy. FamilySearch An interesting approach to using hypermedia APIs for discovering and managing your family history. Huddle An enteprise example of hypermdia APIs from the content collaboration platform huddle. Amazon AppStream REST API The 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. Clarify Clarify 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 Developer Microsoft’s Unified Communications Web API (UCWA) is the Next Generation Platform for Mobile and Web Development. PayPal REST API One of the key features of the PayPal REST API is HATEOAS (Hypertext As The Engine Of Application State). VerticalResponse VerticalResponse's API generally follows the REST model, based on the principles behind HTTP.
- 13. Lies you arebeing told about REST
- 14. “Your URLs shouldbe 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
- 17. RFC 7320 URI Designand Ownership
- 18. “Expose your entitiesas 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
- 19. 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
- 20.
- 21. “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.
- 22. “A REST APIis for exposing your data on the web” Patterns of Enterprise Architecture Martin Fowler
- 23. “REST has nocontracts just return application/json and/or application/xml” {} </>
- 24. GET /some-mystery-resource => 200 OK Content-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
- 25. GET /some-mystery-resource => 200 OK Content-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
- 26. GET /some-mystery-resource => 200 OK Content-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>
- 27. GET /some-mystery-resource 200 OK Content-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>
- 28. Other media typesthat 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
- 29. “Add metadata tobe 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 >
- 30. “Serializing DTOs isthe 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.”
- 31. Get /Customer/10 => 200 OK Content-Type:application/json { “name” : “Acme Inc.”, “street” : “87 Fortune way”, “city” : “Winnipeg”, “postalCode” : “T4R 2Y5” }
- 32. “Design your URIsfirst” • 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.
- 33.
- 34. “Adding hypermedia toyour representations is inefficient” • Caching is critical • Allows correct granularity of resources • The additional costs of providing hypermedia are far outweighed by its benefits
- 35. “You must documentthe 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.
- 36. “You need tobuild 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
- 37. The problem withclient libraries PhotoSearchOptions options = new PhotoSearchOptions(); options.Tags = "blue,sky"; PhotoCollection photos = flickr.PhotosSearch(options);
- 38. So many lies,what is the truth • Client/Server • Stateless • Caching • Uniform Interface • Layered • Code on Demand
- 39.
Editor's Notes
- #3 - Developer advocate for Runscope. - Cloud based solutions for API performance monitoring Microsoft MVP Book
- #5 Considered doing the standard REST talk. This is how you can do it. But there are many places where they will tell you that. Many of them are wrong. I decided to take a more confrontational approach and tell you the lies you are being told about REST. Hopefully it will make the next few hours easier to stay awake and I’m hoping it will promote more interaction. We will have an open question period but ….
- #6 Why should I care about REST? REST is style that can be applied to building distributed systems. Web APIs, Microservices. Business to business interactions, Mobile applications.
- #8 Evolvability matters when there are many different participants in the distributed system under control by different release cycles. The REST constraints are all about reducing, focusing and controlling the coupling between clients and servers to make change easier to manage.
- #9 Dist objs. – died with corba, web sphere EBI – Service Buses, big client requirements. RPC – SOAP/ XML-RPC
- #10 SOAP 1.0 (2000) mentioned using it for RPC. By Dec 2001 it was fixed.
- #11 REST was touted as easier than SOAP, testable from the browser, the next silver bullet. More lightweight. “no contracts”.
- #12 Now almost 13,000 APIs listed. To this date there are only a handful of public APIs that support hypermedia.
- #14 I’m taking this more confrontational approach because I’m hoping to provoke conversation. This mis-information is everywhere. Even starting to appear in “best practices” articles. Credibility.
- #15 Which of these are RESTful? The question makes no sense. An identifier is just that. It can’t be restful or not restful. How you are able to interact with that resource determines whether the URI identifies a RESTful resource. Sadly, it’s an uphill battle. On SO alone there are 358 questions about RESTful urls.
- #16 Web Frameworks like rails invented this convention so that they could provide facilities to make it easy to implement REST based systems. But somewhere along the way, someone decided that this convention was definitively what REST was.
- #17 There is nothing wrong with a web framework defining conventions for exposing resources. However, claiming that this is the definition of REST is like Facebook declaring that Facebook is the Web. OData
- #18 Specific APIs can define conventions, but shouldn’t be standardized Hurts re-use
- #19 Resources are more like object instances than classes.
- #25 Content-Type is supposed to provide the information I need to find out how to interpret the document
- #26 With this content-type, as a client developer, I can go to IANA, find the spec, understand the mean and write code to process it.
- #27 Obviously human readable makes sense, but just because we understand it, that isn’t enough. REST has a notion of self-descriptive. We don’t want to depend on the client having to be able to understand/recognize/parse the URL to be able to interpret the meaning of the response. The problem with the media type as define here, is that it is extremely specific. Not very re-usable. Too much effort to write a spec and register it. Consider for a moment what a client might want to do with this data.
- #28 If all we want the client to do is be able to view a graph of the data, or do some simple statistical analysis, then maybe a more generic media type is suitable.
- #30 Self-descriptive means that the message declares everything that the client application needs to understand in order to process the message. Adding metadata to an application/xml response just moves the lack of understanding of the content, to the lack of understanding of the metadata. Application/xml and application/json have no semantics
- #31 DTO’s as introduced by Fowler we useful for RPC based distributed systems, however REST uses media types as the contracts for interacting with other systems over the wire. Media types are a more controlled environment that take a far more tolerant approach to versioning and are globally discoverable
- #32 DTO generally get returned in application/xml and application/json formats so are not self-descriptive. This means the client needs to know what content is coming from which URI. Creating a media type for every DTO is a crazy proposition. Windows Explorer example.
- #34 No URIs were harmed in the making of this design.
- #35 Link bloat --- compression / relative URIs / templates
- #38 Is this accessing the REST api, or the SOAP api? Which line of code makes a network request? What happens when PhotosSearch fail? Is it safe to retry? Was it an auth problem? Was it a versioning problem? What happens when Flickr add a new property to PhotoSearchOptions or PhotoCollection? New versions are all or nothing.