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.
A REST API should work over any protocol (HTTP, FTP, SSH, whatever) with enough basic functionality to support it. It shouldn't mandate any particular protocol.
------------
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
A REST API shouldn't require a customized version of the underlying protocol.
------------
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
Here's big idea #1. Documentation for a correctly designed REST API will describe mostly what is being returned, not how to get it. Each resource is accessed via a different resource, except for the standalone root.
For example, you might start at the root resource http://foo.com/api/ . It returns, as content, a set of subresources that can be requested. The API documentation should describe what data the server sends for /api/ -- what format it's in (HTML, XML, JSON, etc), how to find its subresources (<a>, <form>, id'ed elements), and any relationship metadata it contains. The user agent (web browser) uses the MIME-type returned by the server to parse whatever it returns.
------------
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.
Big idea #2: the API documentation shouldn't just be a list of URLs; if it is, the server's URLs can't be modified without breaking clients. Clients should use hypertext to parse URLs retrieved from the server.
For example, the front page doesn't just give you a list of story IDs and require you to build the URL manually. It provides each URL in an anchor, as an opaque identifier, and your web browser simply passed it back to the server to get whatever it points to.
------------
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.
The client shouldn't have to contain a list of what URLs return what data. If http://foo.com/students/ returns a student list, either use the MIME-type (application/x-foo.com-students) or a standardized relation name (<foo.com><list rel="students">...).
For XML-based APIs, I would encourage the use of XML namespaces, although Fielding doesn't mention them. Sometimes you've got a few dozen different document types, and it just isn't worth figuring out MIME-types for them all; in that case, return (application/xml) and let the client use the namespace'd root element as an identifier.
------------
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
This is mostly an elaboration of previous bullet points; clients shouldn't have to hardcode a list of resource locations. If your client has something like "students = Resource("/students/"), it's going to break when the server changes that URL.
Good luck doing that for "FTP, SSH, whatever"
In other words, if I want to get the Twitter feed for Joe's "ABC" group and I don't want to hardcode the URL for that resource, how often should I download (and cache), parse, and traverse the resources for Twitter's users then Joe's feed then Joe's ABC group, etc.? Or am I misunderstanding this?
I agree, somewhat, but I would formulate it a bit differently: REST is defined from a user's (or client's) standpoint. It is ill-defined on the other side, even to the point that it is hard to say whether any ruleset can be derived for implementers to use in building their applications. Essentially all of the popular conventions like Resource objects are somewhat misguided, as they are not in any way implied.
I have tried to hammer it in to my acquaintances and colleagues that if you pick one thing about REST to base everything on, it is links, not URLs.
I have pondered on writing a "everything you know about REST is wrong"-article, but have thus far been counterweighed by the consideration that perhaps this perversion that passes for REST is actually better than the real thing.
URIs don't have to start with http, and they don't have to be locators. The rest of his bullet basically says that if you use a non-locator identifier like urn:..., then some other metadata or method will be needed to allow the client to locate the named resource. For example, you might have a resource that can map isbn numbers to online reviews of a book. You can pass in a urn:isbn:### identifier as part of the request url and you'll get back a resource with one or more URLs that point to reviews.
A REST API should not contain any changes to the communication protocols...
Here he's saying that you shouldn't make up new methods. A RESTful API doesn't just use uniform resource identifiers, it uses uniform methods as well. The exceptions are to fill in gaps in the standard methods (which presumably would be fixed in future versions of the protocol standard) and to fill in gaps in implementations (like browsers not supporting DELETE.) The former should be part of the core definition of your API, but the latter should be in an appendix that describes a temporary workaround. A common approach is to allow POST with a parameter named _method to workaround methods that browsers don't support.
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....
Again, the methods are uniform and don't need to be described by the API. The media types and representations are resource-specific, so that's what the API documentation needs to focus on.
A REST API must not define fixed resource names or hierarchies...
Clients should never need to construct a url. Instead, every resource that the API can return should be reachable through a url that is embedded in another resource. All the client should need is the API's entry point. A classic example is a website: every page should be reachable through the home page by following links and submitting forms. You never need to go and edit the url directly to reach a given page.
Browsers and protocol standards are lacking in this respect, because they don't yet support templatized URLs. The workaround here is to provide a url template and some metadata that tells the client how to fill in the template, and if your client is a browser perhaps some javascript that fill in the template appropriately.
A REST API should never have “typed” resources that are significant to the client....
Unlike SOAP, which has typed data similar to a programming language (int, byte, string, boolean, etc) the only types in RESTful APIs are media types. The client is expected to know how to handle a media type in a useful and standardized way. This is related to the earlier point about the API documentation spending time defining the media types used by the API and how to interpret and use them (for non-standard media types.)
For those who want data types, text/json is a good media type choice because it uses the typical programming data types. But if you use JSON you're going to strongly couple clients to your service because you can't modify the json response without modifying the clients that parse the response. If you control both sides that's not a problem, but if you don't or you need to update both sides independently a less-coupled and more metadata-driven representation would be better.
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)...
This bullet repeats what I mentioned above about clients not constructing URIs.
? says "hi, I'm a question mark, and I'm feeling a bit lonely over here..."
> some metadata that tells the client how to fill in the template
Like a <form> </form> maybe?
If you have an API which talks about URI patterns, for example, then it's not REST in this sense, because these URI patterns aren't found inside the documents as hyperlinks. Instead, they're found outside the document.
Similarly, if state is not encoded and transformed by following links in the web of documents, and instead is implicitly understood to be occurring whenever you do e.g. a PUT of some URI pattern, then hypermedia isn't the engine of application state.
A purist approach to REST, though, is IMO impractical for systems that aren't very like the web itself.
So, can you translate his bullet points for me? Or can I safely assume that, yes, Roy Fielding doesn't believe these interfaces are "REST", but that I can safely ignore that fact and use the term "REST" the way the rest of the world does (RPC that uses URL patterns instead of WSDL).