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.
"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"
Why is this the biggest problem? For every protocol there are broken clients. For example, most XML parsers are broken. That is not a problem of XML, is it?
What's the alternative? For clients to refresh their copy of the "parent" resource [there may be a better term for this... I mean the resource used to access the resource that is to be gotten] often? For a commonly interactively accessed thing, it would introduce a lot of latency for clients to get it every time, so I suppose it must be cached... and then the cache of the parent resource be refreshed regularly and in case of failure? How far up the tree should that go?
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?
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.