.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Web::MREST::WebServicesIntro 3pm" .TH Web::MREST::WebServicesIntro 3pm "2022-09-21" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Web::MREST::WebServicesIntro \- General discussion of REST and Web Services .SH "GENERAL DISCUSSION OF REST AND WEB SERVICES" .IX Header "GENERAL DISCUSSION OF REST AND WEB SERVICES" Before you try to implement a \s-1REST\s0 server using Web::MREST, you might want to take a look at our \*(L"prerequisites\*(R". The heading of each subsection below describes the prerequisite. However, the text under each subsection heading should \fBnot\fR be taken as an authoritative discourse on the subject. .SS "Know what Web Services are" .IX Subsection "Know what Web Services are" A \*(L"Web Service\*(R" is a client-server application that uses the \s-1HTTP\s0 protocol for communications between client and server. More specifically, the client attempts to open a \s-1TCP\s0 connection to a pre-defined host and port where the server is listening. Once a connection is open, the client and server communicate in \s-1HTTP.\s0 .PP Web Services can run on any \s-1TCP/IP\s0 network \- the public Internet is one example, but many Web Services run on corporate intranets, for example. A developer will typically have an isolated testing network on his own machine, etc. .SS "Know what a RESTful Web Service is" .IX Subsection "Know what a RESTful Web Service is" Before you write a \s-1REST\s0 server, you should probably learn what a \s-1REST\s0 server is. Here is a crash course. .PP Even if you _think_ you know what a \s-1REST\s0 server is, it might be useful to either skim this crash course or, even better, just read Leonard Richardson's paper which this \&\*(L"crash course\*(R" attempts to paraphrase. .PP \fIIntroduction\fR .IX Subsection "Introduction" .PP \&\s-1REST\s0 is an approach to implementing client-server software architecture, in which communications between client and server use the \s-1HTTP\s0 protocol. It turns out that \s-1HTTP\s0 is \*(L"good enough\*(R" for many applications, and using it can save a lot of work. .PP I urge all prospective \s-1REST\s0 server developers to study and \*(L"grok\*(R" the Richardson \s-1REST\s0 Maturity Model , since it is the conceptual basis for this discourse. .PP \fIMore than a web server\fR .IX Subsection "More than a web server" .PP Providing a Web Service implies having a web server. Web::MREST does this for you, with help from Web::Machine and Plack. .PP But the mere presence of a web server does not make a Web Service \*(L"RESTful\*(R". .PP \fILevel 0: tunnelling mechanism\fR .IX Subsection "Level 0: tunnelling mechanism" .PP Some notorious Web Services \- such as those based on the XML-RPC and \s-1SOAP\s0 technologies \- use \s-1HTTP\s0 as a tunnelling mechanism. In this paradigm, each client message is serialized and sent to the server in the body of a \f(CW\*(C`POST\*(C'\fR request. The server always responds with a 200 status code, which in this case signifies no more than that the message was received and processed, and the server's serialized response is placed in the response body. .PP Richardson calls this \*(L"One \s-1URI,\s0 one \s-1HTTP\s0 method\*(R". .PP Example \s-1HTTP\s0 request: .PP .Vb 7 \& Method: POST \& URI: http://myapp.example.com/ \& Header: Accept: application/json \& Body: { \& "command" : "employee.insert", \& "arguments" : { ... } \& } .Ve .PP Example \s-1HTTP\s0 response: .PP .Vb 9 \& Status code: 200 OK \& Content\-Type: application/json \& Body: { \& "status" : { \& "level" : "ERROR", \& "code" : "MYAPP_INSUFFICIENT_PRIVS", \& "text" : "Insufficient privileges" \& } \& } .Ve .PP To quote Richardson: .PP .Vb 4 \& If you look at an XML\-RPC service, or a typical SOAP service . . ., you\*(Aqll \& see something that looks a lot like a C library. There are a bunch of functions, \& sometimes namespaced with periods. All of these functions are accessed by \& sending a POST request to one single URI. .Ve .PP \fILevel 1: resources\fR .IX Subsection "Level 1: resources" .PP The next step, which Richardson calls \*(L"Many URIs, one \s-1HTTP\s0 method\*(R", involves moving some part of the \s-1XML/JSON\s0 body into the \s-1URI.\s0 Though this step might seem insignificant, calling it \*(L"revolutionary\*(R" would be closer to the truth. .PP Let's apply this to our example. If employees can be uniquely identified by their nick, a request for employee \*(L"simona\*(R" might look like this: .PP .Vb 6 \& Method: POST \& URI: http://myapp.example.com/employee/nick/simona \& Header: Accept: application/json \& Body: { \& "command" : "GET" \& } .Ve .PP By moving the object specification to the \s-1URI,\s0 \fIthe object becomes a web resource\fR, and this is what makes it \*(L"revolutionary\*(R". .PP The very purpose of the \s-1HTTP\s0 standard is to facilitate the publishing and manipulation of web resources, and the \s-1URI\s0 is the \*(L"Uniform Resource Identifier\*(R". Moving from level 0 to level 1 involves the same paradigm shift as embracing \s-1OO\s0 principles in your code. .PP But even if you already were using \s-1OO\s0 principles in the underlying code, what benefit is there in bundling the object identifier in the \s-1HTTP\s0 request body? The Uniform Resource Identifier (\s-1URI\s0) is the right tool for that. .PP \fILevel 2: \s-1HTTP\s0 verbs\fR .IX Subsection "Level 2: HTTP verbs" .PP If you know about \s-1HTTP\s0 methods, the previous example should cry out to you (or, rather, you might cry out to it): "why are they using \f(CW\*(C`POST\*(C'\fR for a \s-1GET\s0 request?!" And, while it may seem astonishing, that is exactly what many Web Services do (or used to do before Richardson published his influential paper). .PP The next \*(L"level\*(R" in Richardson's structure involves leveraging \s-1HTTP\s0 methods to distinguish read requests, which should be idempotent, from write requests, which modify the underlying data. When this distinction is hidden in the \s-1API,\s0 there is no way for client code to optimize read-only requests. .PP Illustrating with our example: .PP .Vb 2 \& Method: GET \& URI: http://myapp.example.com/employee/nick/simona .Ve .PP The barest glace is enough to make it obvious that this request is far simpler than its level 1 equivalent. At level 2, the server guarantees that \s-1GET\s0 requests will never change the data, and that means your client code can dispense with whatever special precautions it needs to take to prevent unwanted modifications. .PP Richardson's designation for this level is: \*(L"Many URIs, each supporting multiple \s-1HTTP\s0 methods\*(R". Quoting Richardson again to drive the point home: .PP .Vb 6 \& The web is powerful because it gives you tools for splitting the inherent \& complexity of a task into small chunks. The URI lets you give a name to \& every object in the system. With URIs, every object can be a little bit \& complex. That\*(Aqs the URI level. On the HTTP level, the major advance of the \& web is that although it can handle any kind of operation, it splits out \& read operations, operations that want to fetch data, and treats them specially. .Ve .PP Taking our example a little bit further, let's say we want to create a new employee at this level. Here's what the request might look like: .PP .Vb 8 \& Method: PUT \& URI: http://myapp.example.com/employee/nick/george \& Header: Accept: application/json \& Body: { \& "name" : "George III", \& "occupation" : "King of England" \& ... \& } .Ve .PP The important point here is that the request body now contains content only \- no command or function name. The role of the function name is taken over by the combination of \s-1HTTP\s0 method and \s-1URI.\s0 .PP Now we are really using \s-1HTTP\s0 to its fullest potential. Or are we? .PP \fILevel 3: hypermedia controls\fR .IX Subsection "Level 3: hypermedia controls" .PP Until this point, the discourse has been easy to follow. Yet, Richardson describes a third level, \*(L"hypermedia\*(R", which he defines as: .PP .Vb 1 \& Resources describe their own capabilities and interconnections .Ve .PP This is also sometimes referred to as \*(L"Hypermedia As The Engine Of Application State\*(R", or \s-1HATEOAS.\s0 As Richardson himself acknowledges, this is where the enthusiasm starts to fade. .PP According to Richardson, whereas level 1 is \*(L"the lesson of URIs\*(R" and level 2 is \&\*(L"the lesson of \s-1HTTP\*(R",\s0 the lesson we learn at this level is \*(L"the lesson of \&\s-1HTML\*(R".\s0 That is because \s-1HTML\s0 is an example of hypermedia controls that we are all familiar with. Generalizing this, we can say that a \s-1HATEOAS\s0 client \&\*(L"navigates\*(R" its server very much like a human surfs the web, that is: by parsing and following links. Just like on the \s-1WWW,\s0 in a \s-1HATEOAS\s0 application, resources link to other resources and, crucially, \fIthose links are expressed as URIs\fR. .PP Returning to our example, let us say that our employee objects link to occupation objects. Inside the database, each occupation is identified by its \&\*(L"occupation_id\*(R", an integer value, and linked tables use this as a foreign key. Without hypermedia controls, our request for employee \*(L"george\*(R" and the server's response (the part following the '*') might look like this: .PP .Vb 10 \& Method: GET \& URI: http://myapp.example.com/employee/nick/george \& * \& Status code: 200 OK \& Content\-Type: application/json \& Body: { \& "name" : "George III", \& "occupation_id" : 553, \& ... \& } .Ve .PP In \s-1HATEOAS,\s0 the same request/response might look like this: .PP .Vb 10 \& Method: GET \& URI: http://myapp.example.com/employee/nick/george \& * \& Status code: 200 OK \& Content\-Type: application/json \& Body: { \& "name" : "George III", \& "occupation" : { \& "link" : { \& "href" : "http://myapp.example.com/occupation/catalog/553, \& "rel" : "http://myapp.example.com/occupation", \& "name" : "King of England" \& }, \& ... \& } .Ve .PP While at first glance it seems more complicated, this approach (which we will call the \s-1HATEOAS\s0 approach) is superior to the non-HATEOAS approach illustrated by the first example. .PP In the non-HATEOAS version, the client code needs to know that occupation objects are identified by their 'occupation_id' property. Further, to gain access to the object it needs to know how to transform the occupation \s-1ID\s0 into the appropriate resource so it can issue a \s-1GET\s0 request for it. .PP By putting the full \s-1URI\s0 of the occupation resource into the response, the client no longer needs to know any of that. To get the resource, it directly issues a \&\s-1GET\s0 request to the \s-1URI\s0 provided in 'href'. .PP But the \*(L"link\*(R" property gives us more than this. From the additional properties the client can, for example, derive that the resource can be modified by issuing a \f(CW\*(C`POST\*(C'\fR request to \f(CW\*(C`http://myapp.example.com/occupation\*(C'\fR and including the \*(L"name\*(R" property (with the value \*(L"King of England\*(R") in the request body. .PP The non-HATEOAS variant, by contrast, provides nothing more than a number. The \*(L"knowledge\*(R" of what can be done with it must be embedded in the client code. As Richardson notes, this makes client code more brittle. He cites examples of RESTful Web Service projects where clients were abandoned after being broken repeatedly by server-side changes to the \s-1REST API.\s0 .PP \fIConclusion\fR .IX Subsection "Conclusion" .PP There is more that can be done with the \s-1HATEOAS\s0 approach, of course, than provide \s-1URI\s0 links in the \s-1HTTP\s0 response. The idea is for clients to get information on their state from the server via \s-1HTTP.\s0 This should make the clients less prone to breakage when changes are made on the server side.