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
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
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
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
498
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
