Client-Server Web Apps with JavaScript and Java (2014)

Appendix B. RESTful Web API Summary

HTTP 1.1 Request Methods

Table B-1 summarizes the HTTP 1.1 request methods.

Table B-1. HTTP 1.1. request methods

HTTP verb	Action to take on a resource	REST action
GET	Retrieve	Like SQL SELECT
HEAD	Retrieve without response body	LIKE SQL SELECT 1
POST	Create (or append)	Like SQL INSERT
PUT	Update (or create) of full resource	Like SQL UPDATE (or INSERT if doesn’t exist)
PATCH	Partial update	Like SQL UPDATE (part of a resource)
DELETE	Delete	Like SQL DELETE
TRACE	Echo request	Diagnostic to determine changes made by intermediate servers
OPTIONS	Return supported methods	Determine which HTTP methods are allowed for the resource
CONNECT	Support for HTTP tunneling	Support HTTP tunneling

HTTP 1.1 Response Codes

Tables B-2 through B-6 summarize the HTTP 1.1 status codes.

Table B-2. Informational status codes 1xx

Code	Meaning	Description
100	Continue	Interim response indicating that part of the request has been received (and not yet rejected by the server)
101	Switching Protocols	Server switching to protocols defined by the response Upgrade header

Table B-3. Successful status codes 2xx

Code	Meaning	Description
200	OK	Accepted
201	Created	A new resource is being created
202	Accepted	Accepted, but processing not complete
203	Non-Authoritative Information	Subset or superset of metadata returned in the entity header
204	No Content	No response body included
205	Reset Content	Client should initiate a request to view the resource associated with the initial request
206	Partial Content	Response to a request that included a range header

Table B-4. Redirection status codes 3xx

Code	Meaning	Description
300	Multiple Choices	Resource is available in multiple representations in different locations
301	Moved Permanently	Resource has been assigned a new permanent URI
302	Found	Resource has been assigned a new temporary URI
303	See Other	The response to the request is available under a different URI
304	Not Modified	Response to a conditional GET request where the document has not been modified
305	Use Proxy	Requested resource is accessible through a returned URI of the proxy
306	(Unused)	Not used in current HTTP version
307	Temporary Redirect	The requested resource resides temporarily under a different URI

Table B-5. Client error status codes 4xx

Code	Meaning	Description
400	Bad Request	Request not understood
401	Unauthorized	Request not authorized
402	Payment Required	Reserved for future use
403	Forbidden	Request not allowed (even with additional authorization)
404	Not Found	Resource not found
405	Method Not Allowed	Invalid HTTP method for the specified URL
406	Not Acceptable	Resource can be generated using the content specified in the accept headers
407	Proxy Authentication Required	Request not authorized (authentication required through a proxy)
408	Request Timeout	Client did not make a request in the time specified by the server
409	Conflict	Request not completed due to the current state of the resource (e.g., changing due to a PUT)
410	Gone	Resource is no longer available
411	Length Required	Content-length header required
412	Precondition Failed	A precondition in the request-header fields evaluated to false
413	Request Entity Too Large	Request entity is larger than the server-specified threshold
414	Request-URI Too Long	Request URI is longer than the server-specified threshold
415	Unsupported Media Type	Format not supported
416	Requested Range Not Satisfiable	Content range specified in the header could not be processed
417	Expectation Failed	An expectation in the request-header fields not met

Table B-6. Server error status codes 5xx

Code	Meaning	Description
500	Internal Server Error	Unexpected error condition on the server
501	Not Implemented	Functionality not supported
502	Bad Gateway	The server acting as a proxy received an invalid response from an upstream server
503	Service Unavailable	Server unavailable due to a temporary condition
504	Gateway Timeout	The server acting as a proxy did not receive a timely response from an upstream server
505	HTTP Version Not Supported	HTTP protocol version in the request message not supported

Curl for Web APIs

The Curl utility can transfer data to or from a server using a variety of different protocols. A small subset of the command-line options are sufficient for most operations related to RESTful web APIs over HTTP, as shown in Table B-7.

Table B-7. Selected HTTP-related Curl options

Option	Short name	Description
-H	Header	Specify an HTTP header
-d	Data	Sends the specified string data to the server
-s	Silent option	Don’t show progress meter or error messages
-L	Location	If the server responds with a location header and a 3xx response code, redo the request on the new location (limit the redirects with --max-redirs)
-X	Execute option	Specify the HTTP request method
-A	Agent	Specify the user agent
-b	Cookie	Specify a cookie (easier to remember using --cookie rather than -b)
-o	Output	Output to a file (or -O to write to a file named the same as the remote one requested)

Sample call:

curl -s -H "Accept: application/json" \

-H "Content-Type: application/json" \

http://localhost:8080/hello/world \

-X PUT -d '{"hello": "world"}'

JSON Syntax

JSON is a simple data exchange format which is a subset of JavaScript.

JSON Types

§ Array (ordered, comma-separated values enclosed in square brackets)

§ Object (an unordered, comma-separated collection of key:value pairs)

§ Number

§ String

§ Boolean

§ Null

Railroad Diagrams

The following railroad diagrams give more a formal description of the subset of JavaScript that constitutes the JSON data exchange format.

Object

An JSON object is a set of zero or more pairs of strings with associated values enclosed in brackets. Each string is followed by a colon, followed by its associated value. If there is more than one string-value pair, they are separated by commas. See Figure B-1.

Object

Figure B-1. Object

Array

A JSON array is a comma-separated list of values enclosed in square brackets. See Figure B-2.

Array

Figure B-2. Array

Value

A value can be a string, number, object, array, true, false, or null. See Figure B-3.

Value

Figure B-3. Value