RESTful Service Theory: Difference between revisions
m
Adding
m (Adding link) |
m (Adding) |
||
| Line 3: | Line 3: | ||
The term "REST" was coined by [https://roy.gbiv.com/ Dr Roy Fielding] in [https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm Chapter 5] of his [https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm PhD dissertation], in which he describes the underlying design philosophy of the [https://en.wikipedia.org/wiki/World_Wide_Web World Wide Web], of which he was one of the principal architects (see, for instance, his contributions to the standards for [https://tools.ietf.org/html/rfc2616 HTTP] and [https://tools.ietf.org/html/rfc3986 URIs/URLs], among others). In effect, to describe something as "RESTful" (having the characteristics of REST) is to say that it is architected in the same style as the Web. | The term "REST" was coined by [https://roy.gbiv.com/ Dr Roy Fielding] in [https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm Chapter 5] of his [https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm PhD dissertation], in which he describes the underlying design philosophy of the [https://en.wikipedia.org/wiki/World_Wide_Web World Wide Web], of which he was one of the principal architects (see, for instance, his contributions to the standards for [https://tools.ietf.org/html/rfc2616 HTTP] and [https://tools.ietf.org/html/rfc3986 URIs/URLs], among others). In effect, to describe something as "RESTful" (having the characteristics of REST) is to say that it is architected in the same style as the Web. | ||
REST is an acronym for "'''Re'''presentational '''S'''tate '''T'''ransfer", which refers to the '''transfer''' of a '''representation''' of some aspect of the '''state''' of one machine to another. That ''aspect of state'' is referred to as a [[#Resources|''resource'']]. In the case of a simple web site, a resource might be, for instance, a page of HTML: a web page (however don't forget that more complex web pages themselves often - usually! - contain many other kinds of embedded resources). | REST is an acronym for "'''Re'''presentational '''S'''tate '''T'''ransfer", which refers to the '''transfer''' of a '''representation''' of some aspect of the '''state''' of one machine to another. That ''aspect of state'' is referred to as a [[#Resources|''resource'']]. In the case of a simple web site, a resource might be, for instance, a page of HTML: a web page (however don't forget that more complex web pages themselves often - ''usually!'' - contain many other kinds of embedded resources). | ||
In practice (if not in theory) that transfer is almost always conducted over [https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol HTTP] (or, more commonly for live services, [https://en.wikipedia.org/wiki/HTTPS HTTPS]), where a [[#Representations|''representation'']] of a [[#Resources|''resource'']], identified by its [[#URLs|''URL'']], is operated on through the use of HTTP [[#Verbs|''Verbs'']]. | In practice (if not in theory) that '''transfer''' is almost always conducted over [https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol HTTP] (or, more commonly for live services, [https://en.wikipedia.org/wiki/HTTPS HTTPS]), where a [[#Representations|''representation'']] of a [[#Resources|''resource'']], identified by its [[#URLs|''URL'']], is operated on through the use of HTTP [[#Verbs|''Verbs'']]. | ||
When this design ''style'' is applied to a web service, that service, or [https://en.wikipedia.org/wiki/Application_programming_interface API], is often referred to as being "'''RESTful'''", so a "REST API" or a "RESTful API" or a "RESTful service" are all simply different ways of describing essentially the same thing. | When this design ''style'' is applied to a web service, that service, or [https://en.wikipedia.org/wiki/Application_programming_interface API], is often referred to as being "'''RESTful'''", so a "REST API" or a "RESTful API" or a "RESTful service" are all simply different ways of describing essentially the same thing. | ||
(To skip further discussion of the theory and go directly to the practicalities of dealing with consuming or creating RESTful services in | (To skip further discussion of the theory and go directly to the practicalities of dealing with consuming or creating RESTful services in | ||
DataFlex, go to the [[#See also|See also]] section at the end of this article or directly to [[RESTful Services in DataFlex]].) | DataFlex, go to the [[#See also|See also]] section at the end of this article, or directly to the [[RESTful Services in DataFlex]] article.) | ||
=The Characteristics of REST= | =The Characteristics of REST= | ||
| Line 32: | Line 32: | ||
*[https://www.w3schools.com/tags/att_a_href.asp hypertext references] (HREFs) to provide navigable links between different resources | *[https://www.w3schools.com/tags/att_a_href.asp hypertext references] (HREFs) to provide navigable links between different resources | ||
The last of these is somewhat controversial | The last of these is somewhat controversial. REST purists (sometimes referred to as [http://www.ben-morris.com/the-restafarian-flame-wars-common-points-of-disagreement-over-rest-api-design/ "RESTafarians"]), including [https://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven Fielding himself], maintain that to be properly RESTful, an API must exhibit the property of [https://en.wikipedia.org/wiki/HATEOAS HATEOAS] ("'''H'''ypermedia '''A'''s '''T'''he '''E'''ngine '''O'''f '''A'''pplication '''S'''tate"). By this they mean that an API should be "entered" by a client via a single known URL, with all other resources, and the operations which can be performed on them, being "discoverable" through HREF links and other information returned by the server. In his dissertation Fielding says: "''REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; self-descriptive messages; and, '''hypermedia as the engine of application state'''''"; the last of these has become something an article of faith among some in the community, with interfaces (APIs) which do not conform to such a constraint being dismissed as "[https://www.jsonrpc.org/specification JSON-RPC]". In practice, you are free to make your own design choices: there is nothing wrong with JSON-RPC if that fits your requirements. | ||
=Resources= | =Resources= | ||
Resources can be pretty much anything which can be stored, in any form, on a computer. A resource might be text or HTML, or media such as a PDF document, a picture, video or music file. It might be a [[JavaScript]] file, or a [https://en.wikipedia.org/wiki/Java_applet Java applet], or a [[CSS]] file, or even an executable program. Anything, really. | Resources can be pretty much anything which can be stored, in any form, on a computer. A resource might be [https://en.wikipedia.org/wiki/Text_file text] or [https://en.wikipedia.org/wiki/HTML HTML], or media such as a [https://en.wikipedia.org/wiki/PDF PDF] document, a picture, video or music file. It might be a [[JavaScript]] file, or a [https://en.wikipedia.org/wiki/Java_applet Java applet], or a [[CSS]] file, or even an executable program. Anything, really. | ||
=Representations= | =Representations= | ||
| Line 66: | Line 66: | ||
==Naming== | ==Naming== | ||
Since HTTP is providing the [[#Verbs|''verbs'']], the URL segments identifying [[#Resources|''resources'']] should, ideally, be '''nouns''' ("customers", "orders", "customers/1035", and so on). | Since HTTP is providing the [[#Verbs|'''verbs''']], the URL segments identifying [[#Resources|''resources'']] should, ideally, be '''nouns''' ("customers", "orders", "customers/1035", and so on). | ||
Collection names should, in general, be <u>plural</u> (because they refer to a plurality of instances within them), while instances should be identified by a unique key within their containing collection. | Collection names should, in general, be <u>plural</u> (because they refer to a plurality of instances within them), while instances should be identified by a unique key within their containing collection. | ||