https://spring.io/guides/tutorials/bookmarks/
Http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
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's RPC. It screams RPC. There is so much coupling on display the It should be given an X rating.
What needs-be-done-to-make the REST architectural style clear on the notion this hypertext is a constraint? In other words, if the engine of application state (and hence the API) was not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period. Is there some broken manual somewhere so needs to be fixed?
API designers, please note the following rules before calling your creation a REST API:
- A REST API should not being dependent on any single communication protocol, though it successful mapping to a given protocol May is dependent on the availability of metadata, choice of methods, etc. In general, any protocol element is uses a URI for identification must allow any URI scheme to being used for the sake of T Hat identification. [Failure Here implies this 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 se T) should be defined separately, or at least in appendices, with a expectation that the workaround would eventually be obs olete. [Failure here implies, the resource interfaces is object-specific, not generic.]
- A REST API should spend almost all of it descriptive effort in defining the media type (s) used for representing Resou RCEs and driving application state, or in defining extended relation names and/or hypertext-enabled mark-up for existing S Tandard media types. Any effort spent describing "what methods" on "what URIs" interest should be entirely defined within the scope of th E processing rules for a media type (and, with 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 the fixed resource names or hierarchies (an obvious coupling of client and server). Servers must has the freedom to control their own namespace. Instead, allow servers to instruct clients on what to construct appropriate URIs, such as was done in HTML forms and URI tem Plates, by defining those instructions within media types and link relations. [Failure here implies that clients Was assuming a resource structure due to out-of band information, such as a domain-specific standard, which was the data-or iented equivalent to RPC ' s functional coupling].
- A REST API should never has "typed" resources that is significant to the client. Specification authors may use resource types for describing servers implementation behind the interface, but those types mu St is irrelevant and invisible to the client. The only types that is significant to a client is the current representation ' s media type and standardized relation name s. [ditto]
- A REST API should is entered with no prior knowledge beyond the initial URI (bookmark) and set of standardized media t Ypes that is appropriate for the intended audience (i.e., expected to being understood by any client that might use the API) . From (that), application state transitions must is driven by client selection of server-provided choices a Re present in the received representations or implied by the user ' s manipulation of those representations. The transitions May is determined (or limited by) the client ' s knowledge of media types and resource communication Mechani SMS, both of which May is improved on-the-fly (e.g., code-on-demand). [Failure here implies that Out-of-band info Rmation is driving interaction instead of hypertext.]
There is probably other rules that I am forgetting, but the above is the rules related to the hypertext constraint that is most often violated within so-called REST APIs. Please try the adhere to them or choose some the other buzzword for your API.
A REST API
