Mon 20 Oct 2008
REST APIs must be hypertext-driven
Posted by Roy T. Fielding under software architecture, web architecture
[51] Comments
I am getting frustrated by the number of people calling any HTTP-based interface a REST API. Today’s example is the SocialSite REST API. That is RPC. It screams RPC. There is so much coupling on display that it should be given an X rating.
What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint? In other words, if the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period. Is there some broken manual somewhere that needs to be fixed?
API designers, please note the following rules before calling your creation a REST API:
- A REST API should not be dependent on any single communication protocol, though its successful mapping to a given protocol may be dependent on the availability of metadata, choice of methods, etc. In general, any protocol element that uses a URI for identification must allow any URI scheme to be used for the sake of that identification. [Failure here implies that identification is not separated from interaction.]
- A REST API should not contain any changes to the communication protocols aside from filling-out or fixing the details of underspecified bits of standard protocols, such as HTTP’s PATCH method or Link header field. Workarounds for broken implementations (such as those browsers stupid enough to believe that HTML defines HTTP’s method set) should be defined separately, or at least in appendices, with an expectation that the workaround will eventually be obsolete. [Failure here implies that the resource interfaces are object-specific, not generic.]
- A REST API should spend almost all of its descriptive effort in defining the media type(s) used for representing resources and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing standard media types. Any effort spent describing what methods to use on what URIs of interest should be entirely defined within the scope of the processing rules for a media type (and, in most cases, already defined by existing media types). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]
- A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct appropriate URIs, such as is done in HTML forms and URI templates, by defining those instructions within media types and link relations. [Failure here implies that clients are assuming a resource structure due to out-of band information, such as a domain-specific standard, which is the data-oriented equivalent to RPC’s functional coupling].
- A REST API should never have “typed” resources that are significant to the client. Specification authors may use resource types for describing server implementation behind the interface, but those types must be irrelevant and invisible to the client. The only types that are significant to a client are the current representation’s media type and standardized relation names. [ditto]
- A REST API should be entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media types that are appropriate for the intended audience (i.e., expected to be understood by any client that might use the API). From that point on, all application state transitions must be driven by client selection of server-provided choices that are present in the received representations or implied by the user’s manipulation of those representations. The transitions may be determined (or limited by) the client’s knowledge of media types and resource communication mechanisms, both of which may be improved on-the-fly (e.g., code-on-demand). [Failure here implies that out-of-band information is driving interaction instead of hypertext.]
There are probably other rules that I am forgetting, but the above are the rules related to the hypertext constraint that are most often violated within so-called REST APIs. Please try to adhere to them or choose some other buzzword for your API.
In what sense do you use “hypertext” here? Should I read your thesis to get the meaning you talk about, or is there somewhere online with the sense in which you mean the word?
Clarification concerning Hypertext vs. Hypermedia: when you state that the API must be hypertext-drive, you’re not implying restrictions on the representation, but properties it must exhibit, namely the ability for connecting a representation to other resources and operations thereon, correct? Then, why no say hypermedia-driven to avoid any confusion with implying that REST would be restricted to HTML?
I have a slide in my REST talk that explains what hypertext (and hypermedia) means.
Hypertext has many definitions:
Ted Nelson’s original definition was focused on non-linear documents.
Later, hypertext became associated with a particular user interface mechanism.
When I say hypertext, I mean the simultaneous presentation of information and controls such that the information becomes the affordance through which the user (or automaton) obtains choices and selects actions. Hypermedia is just an expansion on what text means to include temporal anchors within a media stream; most researchers have dropped the distinction.
Hypertext does not need to be HTML on a browser. Machines can follow links when they understand the data format and relationship types.
I think my poorly written proposal has caused some confusion. I never meant to claim that the OpenSocial or SocialSite RPC APIs were RESTful. There’s more on my blog.
The OpenSocial RESTful protocol is not RESTful. It could be made so with some relatively small changes, but right now it is just wrapping RPC results in common Web media types.
A truly RESTful API looks like hypertext. Every addressable unit of information carries an address, either explicitly (e.g., link and id attributes) or implicitly (e.g., derived from the media type definition and representation structure). Query results are represented by a list of links with summary information, not by arrays of object representations (query is not a substitute for identification of resources). Resource representations are self-descriptive: the client does not need to know if a resource is OpenSocialist because it is just acting on the representations received.
Think of it in terms of the Web. How many Web browsers are aware of the distinction between an online-banking resource and a Wiki resource? None of them. They don’t need to be aware of the resource types. What they need to be aware of is the potential state transitions — the links and forms — and what semantics/actions are implied by traversing those links. A browser represents them as distinct UI controls so that a user can see potential transitions and anticipate the effect of chosen actions. A spider can follow them to the extent that the relationships are known to be safe. Typed relations, specific media types, and action-specific elements provide the guidance needed for automated agents.
Roy, what do you think is the reason that so many people who think they are doing REST get it wrong?
So two questions I’ve always had about this constraint (if you’d be so kind to answer). I apologize if they are dumb, but they are questions I have.
1) What if the set of resources you want to expose is “flat”? Can you not have a RESTful service if there aren’t hyperlinks because the resources don’t naturally have them?
2) When you do have resources that are “like the web” – except for Atom/AtomPub – most resources aren’t as standard as HTML. So when you talk about automated agents aren’t those agents coupled to the particular service they know how to use and traverse?
Hi BillHiggins:
To some extent, people get REST wrong because I failed to include enough detail on media type design within my dissertation. That’s because I ran out of time, not because I thought it was any less important than the other aspects of REST. Likewise, I suspect a lot of people get it wrong because they read only the Wikipedia entry on the subject, which is not based on authoritative sources.
However, I think most people just make the mistake that it should be simple to design simple things. In reality, the effort required to design something is inversely proportional to the simplicity of the result. As architectural styles go, REST is very simple.
REST is software design on the scale of decades: every detail is intended to promote software longevity and independent evolution. Many of the constraints are directly opposed to short-term efficiency. Unfortunately, people are fairly good at short-term design, and usually awful at long-term design. Most don’t think they need to design past the current release. There are more than a few software methodologies that portray any long-term thinking as wrong-headed, ivory tower design (which it can be if it isn’t motivated by real requirements).
And, of course, lately there has been a lot of “me too” activity around REST, as is the nature of any software buzzword.
I had a hard time with the writing in this article; I don’t normally perform exegesis on blog posts. Am I interpreting this correctly?
1. Behavior should be determined by media types. For example, the operations you can perform on an image are predetermined by the fact that it’s an image. I *assume* this bears some relation to GET/POST/PUT/DELETE and how these should be interpreted for various media types… The definition of GET/POST/PUT/DELETE is formal (e.g. “safe”, “idempotent”) as opposed to semantic (they don’t mean CRUD). So, presumably GET/POST/PUT/DELETE are given meaning by the media type.
2. The interface to operations should be discovered. The example of html forms suggests that by e.g. GETting an image we know what parameters can be passed back (e.g., ?width=x&height=y to perform a resize, etc.). This reminds me of the service discovery in XMPP.
3. The location (URI) of objects in the system should have indirection in that by getting a root resource it has links to child resources. We shouldn’t know the location of child resources in advance (e.g., as it might be specified in an API doc).
So let me ask about the motivation for these design suggestions. Suppose I were designing a social networking site, where I have a person with many photos, favorite books, etc. You would advise to not explicitly layout a URL scheme beforehand (e.g., /people/1, /people/1/photos, /people/1/books), but to discover this with hyperlinks by traversing starting at / (slash). If I were looking at /person/1 I would know what the various hyperlinks point to given that I know in advance the media type representing a person (some xml format, say).
So with this example, I don’t really see what I’ve accomplished. I still have the out-of-band specification / coupling in that the media type needs to be specified in advance. The hyperlinks don’t seem to profit much by the price of indirection since I need to know what kind of media type I would get at each URL and I only know this if I know the media type of the parent resource in advance. The price of this indirection is, of course, an unnecessarily chatty protocol. The interface discovery of form elements doesn’t offer much, because although you’ve decoupled the query string format from the out-of-band protocol, in order to interpret the form (e.g., to know what “width” means), I need to know the media type in advance. The only advantage of this approach, it seems to me, is that by the interface and uri decoupling you’ve made the api resilient to protocol changes (e.g., you can move away from HTTP)–but this, to me, seems of little value.
Dr. Fielding, can you please clarify. And be gentle with jargon please.
Hi jonflanders:
1) Any important resource in a RESTful system must have an identifier, so I don’t see how you could have a set of resources (greater than one) which is “flat”. There are a lot of systems that have flat storage, like database records, but that’s exactly the kind of back-end implementation decision that REST is trying to hide. Sometimes an interface has to do work in order to avoid client coupling to the implementation.
2) Automated agents are dependent on their understanding of the media types, link types, or microformat extensions provided in representations. It is the same basic issue as with human communication: we will always need a common vocabulary to make sense of it. Exposing that vocabulary in the representations makes it easy to learn and be adopted by others. Some of it will be standardized, some of it will be domain-specific, but ultimately the agents will have to be adaptable to new vocabulary.
Hi nkallen:
I’m not sure that I can clarify much in a blog comment, but I will try to answer the main points of confusion.
1) Every media type defines a default processing model. For example, HTML defines a rendering process for hypertext and the browser behavior around each element. It has no relation to the resource methods GET/PUT/POST/DELETE/… other than the fact that some media type elements will define a process model that goes like “anchor elements with an href attribute create a hypertext link that, when selected, invokes a retrieval request (GET) on the URI corresponding to the CDATA-encoded href attribute.” Identifiers, methods, and media types are orthogonal concerns — methods are not given meaning by the media type. Instead, the media type tells the client either what method to use (e.g., anchor implies GET) or how to determine the method to use (e.g., form element says to look in method attribute). The client should already know what the methods mean (they are universal) and how to dereference a URI.
2) The interface doesn’t need to be discovered. It is defined right there in the hypertext. The representation tells the client how to compose all transitions to the next application state. This could be as simple as an anchor or as complex as a java applet. For example, Day’s CQ5 content management system allows the user to perform direct image masking and manipulation on the client side and save the filtered image view as a new resource, all within the environment of a standard Web browser window.
3) The purpose of resource modeling is to figure out what resources you have that are worth identifying, representing, and manipulating. You should not be building clients that are dependent on the resource naming structure. There is simply no need to do so — the hypertext sends the client directly to the desired application state.
“Servers must have the freedom to control their own namespace.”
Why is this important?
Can you give an example of a popular hypertext media type that can identify resources, their type and valid operations on them?
HTML lacks type specifications. I have to GET to find out the type, and in the case of POST, I must do the operation to find out which media type will be returned. POST and GET are also the only HTTP methods HTML supports, as far as I know.
If I decide that POSTing to the URI /item will create one new item, how would this be expressed using a suitable media type?
TheOtherMarcus: Because implementations change, but cool URIs don’t.
HTTP operations are generic: they are allowed or not, per resource, but they are always valid. Hypertext doesn’t usually tell you all the operations allowed on any given resource; it tells you which operation to use for each potential transition. The client (user or agent) has to decide what transition to take, not what interface to use.
HTML doesn’t need type specifications. No RESTful architecture needs type specifications. Don’t expect REST to act like some other architectural style. You don’t get to decide what POST means — that is decided by the resource. Its purpose is supposed to be described in the same context in which you found the URI that you are posting to. Presumably, that context (a hypertext representation in some media type understood by your client) tells you or your agent what to expect from the POST using some combination of standard elements/relations and human-readable text. The HTTP response will tell you what happened as a result. In HTTP, a single resource-creating POST action will result in a 201 response with another hypertext representation (telling you what happened and what can be done next) or 204 response with the Location header field indicating the URI of the new resource.
Roy:
When you say “Hypertext doesn’t usually tell you all the operations allowed on any given resource; it tells you which operation to use for each potential transition. The client (user or agent) has to decide what transition to take, not what interface to use.”, could you please explain how an agent without prior knowledge of the possible transitions could decide on the fly what to do? Don’t you think that an agent’s implementation (unlike a human) has to have an understanding of the expected transitions as part of a resource lifecycle?
Now assuming the agent has an a priori knowledge of these transitions (semantically or via the definition of what would appear to be a list of actions, i.e. an interface) how could the agent “adapt” on fly to any changes in the possible transitions when the “resource implementation” changes.
If your answer is yes, i.e, there is an a priori knowledge of these transitions, then, what is the point of hypertext in agent-to-agent communication? I can appreciate that it provides a de facto limitation on the possible actions that can be invoked, but it also introduces some constraints when you consider that an agent has to store the hypertext or fetch it just prior to invoking the action (as this hypertext could possibly change between the time the resource representation is received and the time the action is invoked).
In other words I see absolutely no gains when compared to a traditional interface based interaction. Both mechanisms are pretty much equivalent (again, in an agent-to-agent scenario, not human to agent). In both cases you need a priori knowledge of both the actions and the order in which these actions can be invoked (choreography of the interaction).
Ironically, REST exposes transitions but does not make the “states” of the resources explicit. As you get a resource state, you actually have no idea what is the precise lifecyle of this resource. I can easily understand how a human can deal with this situation, but as a developer I can only see how hard it is to write code without a precise knowledge of the interaction, not to mention, how does the code I just wrote survives when the resource lifecycle (states and transitions) changes.
JJ-
Hi Roy –
You say this:
One negative reaction I’ve come across often with this architectural style is how to implement it efficiently. E.G. often folks will want to implement PROPFIND-y variants to get a bunch of resources in one roundtrip. Is it safe to assume that you might advocate using caching services as one way of efficiently implementing this architectural style?
I’m intuiting that PROPFIND is outside your architectural principles, but I can’t articulate it based on your principles as described here. If true, can you shed light on this?
Something else occurs to me as well – as an architectural style, I wonder if giving examples of systems where the style is not appropriate is a way of raising consciousness.
I will describe my current mental model of REST and ask about the contradictions it still contains.
A client takes the application to the next state by selecting one of the possible actions presented in the hypertext representing the current application state. It can look something like this:
CreateItem POST /random/uri
The client must know what CreateItem means, because this is part of the media type. When posting to /random/uri, a new application state will be returned (201).
CreateItem POST /random/uri
Item GET|PUT|DELETE /item/17
Wouldn’t a 204 response mean that the application has terminated? There are no more state transitions to make? Or can any valid operation on the created resource be expected to initiate a transition to the next application state?
Am I overspecifying by saying that GET, PUT and DELETE are allowed on /item/17? Can this instead be an implicit property of the media type for Item?
I would expect the URI /item/17 to be valid until the item is deleted. How is it otherwise possible to bookmark and go back to interesting resources? But what about URI:s representing application state? Is it up to the server to decide how long they are valid? A simple server implementation may choose to invalidate old application state immediately after transition to a new state, but this would make the back button useless. Advanced server implementations would allow the user to go back to an old state and from there select a different transition, possibly splitting the application in two.
Now I return to the case with the 204 response, assuming the application has not terminated. The resource can be used, for example by putting a new representation of the resource. But now the advanced server becomes nondeterministic, because it can choose to proceed with any of the application states that has existed after the resource was created, not only the last one, as none of the application states are represented in the resource URI. Which of my assumptions is wrong here?
* The application has not terminated.
* The resource URI is constant and not dependent on application state.
* The advanced server should be deterministic.
When the number of state transitions grows, perhaps becomes infinite, the media type used to represent the application state must evolve to be able to present an infinite number of transitions in a finite space. This can be accomplished with URI generation rules. A million items can be hidden behind a query URI.
Progressive Disclosure…
Roy Fielding: I am amused by the people who are valiantly trying to decipher Roy. While I don’t really have much to add, here is what I have… Without intending to take anything away from Roy’s (valid) criticism on labeling, REST…
Thanks for clarifying my confusion. More or less, I think you’ve confirmed the essence of my interpretation. I want to ask again: what are the merits of an architectural style like this?
The argument you use is that out-of-band specification overly couples the client to the server. Hypertext mitigates this. But since the media type specifies, a priori, the kind of state transitions that can be performed, the coupling and out-of-band communication have happened in a RESTful world too. (Note that I’m thinking of an agent as opposed to a person). Given that this is the case, I don’t see the value in providing a hypertext document locating the various transition URIs, since it provides indirection to no end.
The only value the hypertext indirection provies where there are collections of resources of a certain kind and you want to discover what they are (e.g., you want to know the current list of favorite books so you go to /favorites/books and that points you to /favorites/books/the-pleasure-of-hating.html). Still, you must know the kinds of resources (the media types in advance). I would guess, though, that this is such a trivial use of hypertext that you can find few APIs that–falsely, in your view–claim to be RESTful but don’t have this feature.
Can you point us toward some systems that you consider properly RESTful? I think some examples would clarify this discussion.
After a nights sleep, I think I can answer my own questions.
Local resources are assigned URI:s that are unique to a specific application state. Whenever a transition is made, all local resources must be assigned a new URI. This makes it possible for the server to track the application state.
Global resources, like /item/17, are common to all clients. When they are updated, the local application state must not be affected. The most recent local applications state (or any local application state for that matter) is still valid after the global resource is updated.
The union of local and global resources are the total application state.
I am not yet prepared to completely give up global resources, even though they complicate the application design.
Hi jdubray,
Of course the client has prior knowledge. Every protocol, every media type definition, every URI scheme, and every link relationship type constitutes prior knowledge that the client must know (or learn) in order to make use of that knowledge. REST doesn’t eliminate the need for a clue. What REST does is concentrate that need for prior knowledge into readily standardizable forms. That is the essential distinction between data-oriented and control-oriented integration.
It has value because it is far easier to standardize representation and relation types than it is to standardize objects and object-specific interfaces. In other words, there are fewer things to learn and they can be recombined in unanticipated ways while remaining understandable to the client.
That doesn’t mean that I think everyone should design their own systems according to the REST architectural style. REST is intended for long-lived network-based applications that span multiple organizations. If you don’t see a need for the constraints, then don’t use them. That’s fine with me as long as you don’t call the result a REST API. I have no problem with systems that are true to their own architectural style.
Hi tlainhart,
Caching is important (and desirable), but that isn’t generally the answer to your question about batch operations. People perceive a need for batch operations because they don’t understand the scope of resources.
Resources are not storage items (or, at least, they aren’t always equivalent to some storage item on the back-end). The same resource state can be overlayed by multiple resources, just as an XML document can be represented as a sequence of bytes or a tree of individually addressable nodes. Likewise, a single resource can be the equivalent of a database stored procedure, with the power to abstract state changes over any number of storage items.
If you find yourself in need of a batch operation, then most likely you just haven’t defined enough resources.
Hi TheOtherMarcus,
Don’t confuse application state (the state of the user’s application of computing to a given task) with resource state (the state of the world as exposed by a given service). They are not the same thing.
Aside from that, I don’t think that I can give you further guidance on design within blog commentary. My guess is that you are thinking of OOD or ER modeling and trying to project that onto a resource space, but I really can’t say what would be an appropriate design without extensive knowledge of the application requirements and context.
Hi nkallen,
I don’t see how disagreeing with everything you wrote could be interpreted as “confirmed the essence of my interpretation.” Perhaps my comment 20 (above) will help clarify the role of standards in RESTful systems.
I’ve reviewed lots of “REST APIs”, many of them privately for clients, and a common theme I’ve noticed is that most folks coming from a CORBA/DCE/DCOM/WS-* background, despite all the REST knowledge I’ve implanted into their heads, still cannot get away from the need to “specify the interface”. Sometimes this manifests itself through predefined relationships between resources, specifying URI structure, or listing the possible response codes received from different resources in response to the standard 4 methods (usually a combination of all those). I expect it’s just habit. But a second round of harping on the uniform interface – that every service has the same interface and so any service-specific interface specification only serves to increase coupling – sets them straight.
[…] good to see Roy take on the pseudo/not-at-all “REST APIs” out […]
I agree that we won’t get any further with this discussion. I just want to know if there are any known media types besides HTML that is suitable for REST interfaces. As I see it, HTML is not ideal for an API intended to be used by a machine. I would have to use an AI if I want it to be able to figure out that a submit button that yesterday was called “Send order” is the same as the button now called “Submit order”. More formalization is needed.
It seems a link to a good example “out there” would be helpful.
Even after reading the post and comments and the OpenSocial “REST” API, AND your paper, and doing several different implementations on my own, I’m still not entirely clear what a good REST implementation would look like.
Hi Roy,
I am very thankful that you throw out some more prose, so one can decide whether a given API is RESTful or not. After all i still have a bad feeling of making such a claim myself. You, as a knowledgeable human being, are obviously able to decide on RESTfulness by inspecting an abstract description of the interface. Since i doubt that you are looking into a crystal ball, the following question crosses my mind: Is it possible for a machine to make such a decision? Would it be enough to pass it a sample transcript of a client server dialog? If that does not suffice, which other information would be necessary to decide on RESTfulness? Additionally, to the simple fact, whether or not an API is RESTful based on a sample, this would create the benefit that an API creator could read and understand the program and learn how to create an API that deserves this predicate. After all programmers prefer to read code over prose. If you think it is not possible or very difficult, i would be interested why.
Roy, maybe I’m misinterpreting your corrections then. You said
1. “the media type tells the client either what method to use”; I interpret this to mean that the media type defines the state transitions and the media type specifies which methods map on to which state transitions. This is essentially are more precise statement of my original interpretation, is it not?
2. “The interface doesn’t need to be discovered. It is defined right there in the hypertext.” This is, again, a matter of semantic precision. The state transitions are known a priori; the resouces on which you can perform the transitions are linked to.
3. Again, you’re restating my interpretation: the resource naming (uris) should not be specified in advance, but linked to.
I still feel your answers to jdubray in #20 are unsatisfactory. The out of band communication is happening when defining the media type. The only argument you marshall for media types in stead of fixed resources is that the media types can be shared across sites. That has value, but it’s a pretty weak value.
Hi Robert,
The short answer: “follow your nose”. That is the phrase we usually use to distinguish the process of following information-provided transitions/semantics versus following a set procedure or interface declaration outside of that flow of information. Basically, how far ahead is the client looking?
The difficulty in providing any trace criterion for REST is that what matters is how the client decides to take transitions. A client that has been pre-programmed to make a sequence of requests (regardless of the response) is going to produce the same network trace as one that examines each response and makes deliberate decisions based on the content.
In terms of testing a specification, the hardest part is identifying when a RESTful protocol is actually dependent on out-of-band information or if the authors are just overspecifying things for the purpose of documentation. What I look for are requirements on processing behavior that are defined outside of the media type specification. One of the easiest ways to see that is when a protocol calls for the use of a generic media type (like application/xml or application/json) and then requires that it be processed in a way that is special to the protocol/API. If they are keying off of something unique within the content (like an XML namespace declaration that extends the semantics of a generic type), then it’s okay. Usually, however, what they do is assume that the response has a specific structure beyond that defined by the media type. When the structure changes, the client will break.
nkallen,
The media type identifies a specification that defines how a representation is to be processed. That is out-of-band information (all communication is dependent on some prior knowledge). What you are missing is that each representation contains the specific instructions for interfacing with a given service, provided in-band. The media type is a generic processing model that every agent can learn if there aren’t too many of them (hence the need for standards). The representation is specific to the application being performed by the agent. Each representation therefore provides the transitions that are available at that point in the application.
When representations are provided in hypertext form with typed relations (using microformats of HTML, RDF in N3 or XML, or even SVG), then automated agents can traverse these applications almost as well as any human. There are plenty of examples in the linked data communities. More important to me is that the same design reflects good human-Web design, and thus we can design the protocols to support both machine and human-driven applications by following the same architectural style.
The way I think people look at REST is this: if it is not your everyday xml-based web services (SOAP and WS-*), then it must be REST. This distinction is taken regardless of whether the API in question is RESTfull (as defined by Dr. Fielding) or not.
So there is no need to be frustrated, people have taken the coined term and ran with it. This is how marketing will use it and so will everybody else.
Explaing REST and Hypertext: Spam-E the Spam Cleaning Robot…
I’m going to add to Sam Ruby’s amusement and throw in my attempt to explicate some of Roy Fielding’s recent discussion of what makes an API RESTful. If you’ve not read the post and all the comments then I encourage you to do so: there’s some great…
Roy, you are saying:
When representations are provided in hypertext form with typed relations (using microformats of HTML, RDF in N3 or XML, or even SVG), then automated agents can traverse these applications almost as well as any human.
I wonder how the agent knows what the relationship types mean or whether this just applies if client and server have shared knowledge on the vocabulary, actually more the respective programmers. In other words, if the server introduces a new relationship type, the agent probably needs adaption, depending on its task. Do you agree?
REST API Design: Invent Media Types, Not Protocols and Understand the Importance…
…
[…] with most applications of computing somewhere in between. However, when I send out a message to API designers, I expect the audience to be reasonably competent in the field. I have to talk to them as a […]
[…] from a client-centric point of view. I have to admit that after reading this post, and the Roy Fielding post that inspired it, my interpretation of REST has totally been turned on its head. Both are […]
[…] words come from the man who put REST on the map, one Roy Fielding in a bit of a rant against what people call REST today. The post is worth reading for anyone who is into the REST architecture (or […]
[…] giorni fa l’ennesimo caso di API dichiaratasi RESTful, ma che invece, a detta di Roy Fielding RESTful non è. La cosa che mi spiazza è la carenza cronica di esempi significativi e […]
[…] State Transfer was, as everyone knows, defined by Roy T. Fielding who recently gave SocialSite’s REST API a bit of a panning and then go on to give it to the OpenSocial specification. Now this must be quite hard to take and […]
[…] imaginez ma hâte lorsque j’ai découvert un post de Roy Fielding qui commence par la phrase suivante : “I am getting frustrated by the number […]
Roy,
do you think any of the public API’s out there are truly RESTful?
One problem I have is how to do security and keep it pure RESTFul
In order to have secure call I have to do something like:
GET /resource/11231231/token=KJGHY7687JKGH
Unless I do POST – is there a better way you see for this?
Dima.
Dima,
I am not sure why you think that having an obscure URI format will somehow give you a secure call (whatever that means). Identifiers are public information.
RESTful systems perform secure operations in the same way as any messaging protocol: either by encapsulating the message stream (SSL, TLS, SSH, IPsec, …) or by encrypting the messages (PGP, S/MIME, etc.). There are numerous examples of that in practice, and more in the future once browsers learn how to implement other authentication mechanisms.
REST != HTTP…
…
Roy,
What about the usecase of a distributed queue? The queue should not care about the media types it is exchanging between senders and receivers, yet it can quite easily satisfy the addressability, uniform interface, and statelessness constraints of a RESTful architecture. Can’t a service that is media-type agnostic be a RESTful API? Such a service would require assigning semantic meaning to a specific HTTP method and URI pattern and would not receive state transition information from its exchanged media types (as the service doesn’t care or need to know about the media types). I hope I am explaining myself well.
For example:
POST /{queue-name} sends a message to the queue
GET /{queue-name}/top is the current message waiting to be processed. It returns
Location: /messages/111
DELETE /messages/111 tells server you are done processing that message.
There are specific state transitions for the receiver, but why does the media type have to contain information on how to process a received message?
Assigning a little bit of semantics to the URI and HTTP methods adds a lot of simplicity to the overall architecture without requiring an “envelope” format to exchange data. I also think it is far easier to maintain and re-use over the long term.
Bill,
A distributed queue is an implementation choice. You can certainly implement some applications by having them interact with a queue-like resource in a RESTful manner. However, if your client relies on the resource being a queue, then it certainly isn’t a RESTful API. Do you see the difference? Encoding knowledge within clients and servers of the other side’s implementation mechanism is what we are trying to avoid.
If a client is receiving instructions on how to interact with a resource just before acting only on those instructions, then the client doesn’t care if the resource is a distributed queue. It simply doesn’t need to know how the resource is implemented. All it needs to know is the meaning of those instructions and some idea of what it wants to do next, whether that purpose be user-driven, configuration-driven, or some sort of AI-driven.
[…] Fielding recently wrote : REST APIs must be hypertext-driven. It is an excellent writeup which actually focuses on What REST is NOT and is written in the […]
Hi Roy,
The first bullet says “REST API should not be dependent on any single communication protocol.” and “In general, any protocol element that uses a URI for identification must allow any URI scheme to be used for the sake of that identification.”
If I understand it correctly, when I design a media type, I should not restrict URIs to a limited set of URI schemes. However, HTML doesn’t define how user agents can handle a form tag which uses a URI other than an HTTP URI as the value of its action attribute. Then who can decide which method needs to be used with an FTP URI? It seems HTML restricts the possible values of form’s action attribute to only HTTP URIs. How could I explain this?
The HTML specification doesn’t say that user agent developers need to use HTTP’s GET method for an anchor. Then how could they know how to handle the element with HTTP?
I know my English is really bad, but I just want to know how I can define in the media type that an anchor needs to be handled with HTTP’s GET.
Hi Roy,
Earlier on you speculated about why people find the HATEOS idea so difficult to follow. My view is it’s caused by the lack of good examples and/or a good book.
It might be worth contrasting it with DDD, in my view similiarly complex and also looking at designing simple software with a long term viewpoint.
As with anything DDD suffers from misunderstandings and people sometimes focus too much on the unimportant aspects.However overall things are in a much better state than they are with REST and I think that’s largely because Evans’ book really focusses the mind and describes real world examples that illustrate why his ideas are important. Similiarly the published code/design examples give people something to focus on.
However when it comes to REST a lot of content available on the Web, even from true REST experts, is quite unhelpful to newcomers. In fact *good* REST examples and discussions were thin on the ground until recently, probably fuelling the incessant squabbling and more recently the hijacking of REST (including WOA).
As I say recently we’ve had some realistic examples (I’m thinking in particular of http://www.infoq.com/articles/webber-rest-workflow, even though you might not consider it RESTful) but I certainly think that a lot more could be done and that perhaps a good book is in order? :)
Just my 2c as someone whose gradually coming to appreciate REST after many months of trying to get to grips with the great ideas behind it.
Thanks,
Colin
Roy,
How is HATEOAS possible if markup doesn’t adequately support protocol transactions?
Regards,
Mike