RESTful Web Services Part 4 - Interaction Design

Interaction Design With HTTP

    REST API USE HTTP 1.1

• Request method

           Request-Line= Method SP Request-URI SP HTTP-Version CRLF

• Response codes

            100            200            300            400

• Message headers

Request Method Rules

• Request methods

            Request-Line=Method SP Request-URI SPHTTP-Version CRLF

                                     GET/greeting Http/1.1

• GET and POST must not be used to tunnel other request methods

            Tunneling: misrepresents a message

                              undermines the protocol’s transparency

Request Methods

• GET – used to retrieve a representation of a resource
  • GET a representation of a resource
  • Safe:Can’t hold the user responsible for side-effects
  • Idempotent:N > 0 identical requests are each the same as a single request
  • Cacheable

                    Example:

                        GET /people  HTTP/1.1

                    Note: HTTP request and response examples in this presentation are meant to be illustrative and are not always complete. Some HTTP headers may be missing.

• POST – used to create a new resource in a collection or execute function oriented controllers
  • POST a new representation of a resource
  • New resource is subordinate to the requested resource
  • Not Safe
  • Not idempotent
  • Can be cached only through the Cache-Control or Expires headers fields

                    Example:

                        POST /leagues/seattle/teams/trebuchet/players

                       POST /alerts/245743/resend

• PUT – used to insert and update a stored/mutable resource
  • PUT a modified representation of a resource
  • Not Safe
  • Idempotent: PUTting the same thing multiple times is the same as doing it once
  • Responses are not cacheable

                    Example:

                        POST /account/4ef2d5do-cb7e-11eo-9572-0200c9a66/objects/4321

• DELETE – used to remove a resource from its parent
  • DELETE a resource
  • Not Safe
  • Idempotent: Deleting something multiple times is the same as doing it once
  • Responses are not cacheable

                    Example:

                        DELETE /account/4ef2d5do-cb7e-11eo-9572-0200c9a66/buckets/objects/4321

• HEAD – used to retrieve response headers

                Example:

                    Date: Sat, 20 Aug 2014 16:02:40 GMT

• OPTIONS – used to retrieve metadata describes a resource’s available interactions

                Allow: GET, PUT, DELETE

Request Method Vocabulary

Term	Description
DELETE	HTTP request method (RM) – remove its parents
GET	HTTP RM – retrieve a representation of a resource’s state
HEAD	HTTP RM – retrieve the metadata associated with the resource’s state
OPTIONS	HTTP RM – retrieve metadata that describes a resource’s available interactions
POST	HTTP RM – create a new resource within a collection or execute a controller
PUT	HTTP RM – insert a new resource into a store or update a mutable resource

Term	Description
Request-Lin	RFC 2616 defines its syntax as:Method SP Request-URI SP HTTP-Version CRLF
Request method	Indicates the desired action to be performed on the request message’s identified resource
Response status	3-digit numeric value communicated by a server to indicate result code of client’s request
Status-Line	RFC 2616 defines its syntax as:HTTP-Version SP Status-Code SP Reason-Phrase CRLF
Tunneling	An abuse of HTTP that masks or misrepresents a message’s intent and undermines the protocol’s transparency

Response Status Codes

    Status-Line= HTTP-Version SP Status-Code SP Reason-Phrase CRLF

Response Status Codes Categories

Category	Description
1xx:	Informational Communicates transfer protocol-level information
2xx:	Success Indicates that the client’s request was accepted successfully.
3xx:	Redirection Indicates that the client must take some additional action in order to complete their request
4xx:	Client Error
5xx:	Server Error

Code	Name	Meaning
200	OK	Indicates a nonspecific success
201	Created	Sent primarily by collections and stores
202	Accepted	Sent by controllers to indicate the start of an asynchronous action
204	No	Content Indicates that the body has been intentionally left blank
301	Moved	New permanent URI has been assigned to the client’s requested resource
303	See Other	Sent by controllers to return results that it considers optional
304	Not Modified	Sent to preserve bandwidth (with conditional GET)
307	Temporary Redirect	Indicates that a temporary URI has been assigned to the client’s requested resource
400	Bad	Request Indicates a nonspecific client error
401	Unauthorized	Sent when the client either provided invalid credentials or forgot to send them
402	Forbidden	Sent to deny access to a protected resource
404	Not Found	Send when the client tried to interact with a URI that the REST API could not map to a resource
405	Method Not Allowed	Sent when the client tried to interact using an unsupported HTTP method
406	Not Acceptable	Sent when the client tried to request data in an unsupported media type format
409	Conflict	Indicates that the client attempted to violate resource state
412	Precondition Failed	Tells the client that one of its preconditions was not met
500	Internal Server Error	Tells the client that the API is having problems of its own

HTTP Headers

    Various forms of metadata conveyed through the entity headers

• HTTP’s request
• HTTP’s response message

    REST API HTTP’s standard headers

• Content-Type – type of data (ex – media type)
• Content-Length – size of the entity-body in bytes
• Last-Modified – should be used in responses only
• Etag – version in the response’s entity

Caching

• Cache-Control,Expires, and Date used to encourage caching

            Date: Tue, 15 Nov 1994 08:12:31 GMT

            Expires: Thu, 01 Dec 1994 16:00:00 GMT

• Expiration caching headers

            should be used with 200 (“OK”) response

            optionally be used with 3xx and 4xx response

• Custom HTTP headers must not be used to change the behavior of HTTP methods

Media Types

    Media Type Syntax

        type“/” subtype *(“;” parameter)

        *type: application            audio            image            message            model            multipart            text            video

        *parameters: follow the type/subtype in the form of attribute=value separated by (;)

        Parameter values case-sensitive and enclosed in (“”) characters.

                Content-type: text/html;charset=ISO-8859-4

                Content-type: text/plain;charset=“us-ascii”

    Registered Media Types

        Governed by Internet Assigned Numbers Authority (IANA)

• text/plain: no specific content structure or markup
• text/html: Content that is formatted using the Hyper Text Markup Language (HTML)
• image/jpeg: An image compression method that was standardized by the Joint Photographic Experts Group (JPEG)
• application/xml: Content that is structured using the Extensible Markup Language (XML)
• application/atom+xml: Content is XML-based format that structures data into lists known as feeds
• application/javascript: Source code written in the JavaScript programming language
• application/json: The JavaScript Object Notation (JSON)text-based format often used to exchange structured data

    Vendor-Specific Media Types

        application/vnd.ms-excel

        application/vnd.lotus-notes

        text/vnd.sun.j2me.app-descriptor

Representation Design

    Message Body Format

        Commonly used XML and JSON formats

        XML (Extensible Markup Language) <> tag paris: XML and other formats may optionally be used for resource representation

        JSON (JavaScript Object Notation) {} hierarchically structure: Supported for resource representation; Must be well-formed

    XML: XML was created to structure, store, and transport information

• XML is a markup language much like HTML
• XML was designed to carry data, not to display data
• XML tags are not predefined. You must define your own tags
• XML is designed to be self-descriptive
• XML is a W3C Recommendation

   

    JSON: JSON is universally accepted as a “front-end” language

        {

            “firstName” : “Osvaldo”,

            “lastName” : “Alonso”,

            “firstNamePronunciation” : “ahs-VAHL-doe”,

            “number” : 6,

            “birthDate” : “1985-11-11”

        }

• all names enclosed in “”
• supports number values directly
• date-time values, typically formatted as strings