2. Who am I?
• Twitter: @darrel_miller
• http://www.bizcoder.com/
Solve API Problems Fast
3.
4. 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.
5. REST
What 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
6. “Most of REST’s constraints are focused on
preserving independent evolvability over time,
which is only measurable on the scale of years.”
7. • 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?
8. What are the alternatives?
• 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 of Pop REST
• The craving for prescriptive guidance
• Web API Frameworks
• API Management vendors
12. http://apievangelist.com/2014/04/15/what-are-some-good-examples-of-hypermedia-apis/
FoxyCart
A hypermedia example from 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.
18. “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
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
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 API is for exposing your data on the web”
Patterns of Enterprise Architecture
Martin Fowler
23. “REST has no contracts just return
application/json and/or application/xml”
{} </>
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 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
30. “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.”
32. “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.
34. “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
35. “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.
36. “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
37. The problem with client 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
- Developer advocate for Runscope.
- Cloud based solutions for API performance monitoring
Microsoft MVP
Book
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 ….
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.
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.
Dist objs. – died with corba, web sphere EBI – Service Buses, big client requirements. RPC – SOAP/ XML-RPC
SOAP 1.0 (2000) mentioned using it for RPC. By Dec 2001 it was fixed.
REST was touted as easier than SOAP, testable from the browser, the next silver bullet. More lightweight. “no contracts”.
Now almost 13,000 APIs listed. To this date there are only a handful of public APIs that support hypermedia.
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.
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.
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.
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
Specific APIs can define conventions, but shouldn’t be standardized
Hurts re-use
Resources are more like object instances than classes.
Content-Type is supposed to provide the information I need to find out how to interpret the document
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.
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.
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.
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
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
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.
No URIs were harmed in the making of this design.
Link bloat --- compression / relative URIs / templates
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.