For some reason I have this bizarre thought about people screaming RPC at WS-* when people were really doing document passing, it must be really terrible when people mislabel what you are doing...
Steve 2008/10/31 Gervas Douglas <[EMAIL PROTECTED]>: > <<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.>> > > You can read this blog at: > > http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven. > > Gervas > >
