--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.
The table of request headers below SHOULD be used by Microsoft Services. Using these headers is not mandated, but if used they MUST be used consistently.
Header
Type
Description
Authorization
String
Authorization header for the request
Date
RFC 1123 date
Timestamp of the request
Accept
Content type
The requested content type for the response such as:
· application/xml
· text/xml
· application/json
· text/javascript (for JSONP)
Per the HTTP guidelines, this is just a hint and responses MAY have a different content type, such as a blob fetch where a successful response will just be the blob stream as the payload. For services following OData, the preference order specified in OData SHOULD be followed.
Accept-Encoding
Gzip, deflate
REST endpoints SHOULD support GZIP and DEFLATE encoding, when applicable. For very large resources, services MAY ignore and return noncompressed data.
Accept-Language
“en,” “es,” etc.
Specifies the preferred language for the response. Services are not required to support this, but if a service supports localization it MUST do so through the Accept-Language header.
Accept-Charset
Charset type like “UTF-8”
Default is UTF-8, but services SHOULD be able to handle ISO-8859-1.
Content-Type
Content type
Mime type of request body (PUT/POST/PATCH)
Prefer
return=minimal, return=
representationIf the return=minimal preference is specified, services SHOULD return an empty body in response to a successful insert or update. If return=representation is specified, services SHOULD return the created or updated resource in the response. Services SHOULD support this header if they have scenarios where clients would sometimes benefit from responses, but sometimes the response would impose too much of a hit on bandwidth.
If-Match, If-None-Match, If-Range
String
Services that support updates to resources using optimistic concurrency control MUST support the If-Match header to do so. Services MAY also use other headers related to ETags as long as they follow the HTTP specification.
1.2 Standard Response headers
Services SHOULD return the following response headers, except where noted in the “required” column.
Response Header
Required
Description
Date
All responses
The date the request was processed, in RFC 1123 format
Content-Type
All responses
The content type
Content-Encoding
All responses
GZIP or DEFLATE, as appropriate
Preference-Applied
When specified in request
Whether a preference indicated in the Prefer request header was applied
ETag
When the requested resource has an entity tag
The ETag response-header field provides the current value of the entity tag for the requested variant. Used with If-Match, If-None-Match and If-Range to implement optimistic concurrency control.
1.3 Custom Headers
Custom headers MUST NOT be required for basic operation of a given API.
Some of the guidelines in this document prescribe the use of nonstandard HTTP headers. In addition, some services MAY need to add extra functionality, which is exposed via HTTP headers. The following guidelines help maintain consistency across usage of custom headers.
Headers that are not standard HTTP headers MUST have one of two formats:
1) A generic format for headers that are registered as “provisional” with IANA (RFC 3864)
2) A scoped format for headers that are too usage-specific for registration
These two formats are described below.
--