Beginning Java EE 6 with GlassFish 3, Second Edition

CHAPTER 15 ■ RESTFUL WEB SERVICES■ Note Here I am using cURL (http://curl.haxx.se/) as a client, but I could have used Firefox or any other webclient that deals with HTTP requests. cURL is a command-line tool for transferring files with URL syntax viaprotocols such as HTTP, FTP, Gopher, SFTP, FTPS, SCP, TFTP, and many more. You can send HTTP commands,change HTTP headers, and so on. It is a good tool for simulating a user’s actions at a web browser.HTTP MethodsThe Web consists of well-identified resources linked together and accessed through simple HTTPrequests. The main types of requests standardized in HTTP are GET, POST, PUT, DELETE. These are alsocalled verbs, or methods. HTTP defines four other methods that are less frequently used: HEAD, TRACE,OPTIONS, CONNECT.GETGET is a simple read that requests a representation of a resource. GET should be implemented in a safeway, meaning it shouldn’t change the state of the resource. In addition, GET must be idempotent, whichmeans it must leave the resource in the same state when called once, twice, or more. Safety andidempotence bring greater stability. When a client does not get a response (e.g., due to a networkfailure), it might renew its requests, and those new requests will expect the same answer it should havereceived originally, without corrupting the resource state on the server.POSTGiven a representation (text, XML, etc.), calling a POST method creates a new resource identified by therequested URI. Examples of POST could be appending a message to a log file, a comment to a blog, a bookto a booklist, and so on. Consequently, POST is not safe (the resource state is updated) nor idempotent(sending the request twice will result in two new subordinates). If a resource has been created on theorigin server, the response should be status 201 (Created). Most modern browsers generate only GET andPOST requests.PUTA PUT request is intended to update the state of the resource stored under a given URI. If the request URIrefers to a nonexistent resource, the resource will be created under this same URI. Examples of PUT couldbe updating the price of a book or the address of a customer. PUT is not safe (because the state of theresource gets updated), but it is idempotent: you can send the same PUT request many times, and thefinal resource state will always be the same.DELETEA DELETE request deletes the resource. The response to a DELETE may be a status message as part of thebody or no status at all. DELETE is also idempotent but not safe.455