Difference between revisions of "RESTful Service Theory"

From DataFlex Wiki
Jump to navigationJump to search
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: 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.
+
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.

Revision as of 14:23, 9 August 2019

REST is a term for a style of Web Service. It is in distinct contrast to the older style of SOAP Web Services.

The term "REST" was coined by Dr Roy Fielding in Chapter 5 of his PhD dissertation, in which he describes the underlying design philosophy of the World Wide Web, of which he was one of the principal architects (see, for instance, his contributions to the standards for HTTP and 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 "Representational State Transfer", 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 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 HTTP (or, more commonly for live services, HTTPS), where a representation of a resource, identified by its URL, is operated on through the use of HTTP Verbs.

When this design style is applied to a web service, that service, or 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 DataFlex, go to the See also section at the end of this article, or directly to the RESTful Services in DataFlex article.)

The Characteristics of REST

In his dissertation, Fielding identified six characteristics which typified REST:

  1. Client-Server - a client (such as, for instance, a web browser) makes requests of a server (such as a web server) and receives a response
  2. Statelessness - each request and response is independent of others and stands alone: no state is maintained on the server between requests
  3. Cacheable - for efficiency, the response to a request must be explicitly marked as cacheable or not
  4. Uniform Interface - essentially the use of URIs (in practice, URLs) to identify coarse-grained resources
  5. Layered System - the use of intermediate hardware components, such as proxies and gateways, to, in conjunction with the caching above, improve scalability and reduce latency
  6. Code-On-Demand - applets (i.e. Java) or scripts (i.e. JavaScript) which can be used to extend the functionality from the server to the client

In addition to these, RESTful web services also generally exhibit the use of:

The last of these is somewhat controversial. REST purists (sometimes referred to as "RESTafarians"), including Fielding himself, maintain that to be properly RESTful, an API must exhibit the property of HATEOAS ("Hypermedia As The Engine Of Application State"). 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 "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 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 Java applet, or a CSS file, or even an executable program. Anything, really.

Representations

The representation of a resource need not (and in web services, probably will not) be anything like the way it is stored at source (i.e. on the server). Typically that representation will be in some platform-neutral form such as HTML, XML, JSON, base64 or plain text (all of which are actually forms of plain text). In the case of RESTful web services, JSON is by far the commonest representation, although some services do support XML as an alternative.

URLs

Resources are identified by specific URLs. Examples might be:

https://www.example.org/api/v2/customers/1035

Which would refer to the instance resource: customer number 1035 within the Example.org API version 2, or:

https://www.mywebsite.com/rest/orders/3269/items

Which would refer to the collection resource: the line-items within order number 3269 in the RESTful API of MyWebsite.

Or you might dedicate an entire server (actual or virtual) to your APIs:

https://apis.mycompany.com/stock/v1/stockitems/ARF-41268-B

or:

https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol - Wikipedia is an example of a RESTful system (as is this Wiki).

Typically resources are organized into collections (i.e. orders) and within those, instances (i.e. the specific order number 3269), which in turn may have dependant collections (i.e. items) of further instances (i.e. item 14).

Naming

Since HTTP is providing the verbs, the URL segments identifying resources should, ideally, be nouns ("customers", "orders", "customers/1035", and so on).

Collection names should, in general, be plural (because they refer to a plurality of instances within them), while instances should be identified by a unique key within their containing collection.

In APIs representing a hierarchically organised systems, which most databases, to a greater or lesser extent, are, the pattern:

<protocol>://<host>/<api-path>/<version>/<collectionID>/<instanceID>/<collectionID>/<instanceID>/<collectionID>/... etc.

is a common one, although a depth of more that four or five collections would start to seem excessive!

Verbs

RESTful interfaces make use of HTTP verbs to determine what operation should be performed on a given resource. The standard set of verbs are: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS, CONNECT and TRACE. In practice, only the first five of these are in common use in RESTful services.

GET

GET is used to retrieve a resource, be that a collection or an instance. It should (must!) have no side effects: its use should change nothing on the server (for this purpose we can discount irrelevant "plumbing" side effects, such as incrementing page counters or updating server logs).

POST

POST is permitted to do anything, so there are no constraints on what this verb can be used for.

PUT

PUT is supposed to be "idempotent". Idempotent is a term, originally from mathematics (denoting an element of a set which is unchanged in value when multiplied or otherwise operated on by itself), but in the context of computing, it means that repeated applications of the same operation on the same resource should result in the same server state as resulted from the first application.

This makes PUT problematic for various operations. PUT can only be used to create or modify an entire resource. When creating a resource, everything about that resource must be known in advance: there must be no server-allocated key, or other associated aspect, involved in that creation, otherwise each new application would result in a different server state. Similarly, modifying a resource can only be done by replacing that resource entirely, which makes PUT unsuitable for partially updating a resource in a multi-user environment.

DELETE

DELETE, like PUT, is also supposed to be idempotent, however this is less of a problem. If a resource is deleted, subsequent attempts to delete that resource will fail (probably giving an HTTP response status of "404 Not Found") because the resource is no longer there to be acted upon, however the state of the server will not be changed by those subsequent attempts: the resource will still not be there.

PATCH

PATCH is a relatively recent (March 2010) addition to the list of common verbs, filling a requirement for "a feature to do partial resource modification", and that is exactly what it is good for: changing some parts of a resource without completely overwriting all of it.

See also