A REST API should not be dependent on any single communication protocol...
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.
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.