Which HTTP headers to include?

[ps]

I searched but didn't find much discussion about this. Are there specific headers you recommend including in a good API?

Some of these may be context or use-case dependent, but are there ones you consider essential?

GitHub, for example, seems to include 24 or so by default:

curl -I https://api.github.com/

[Ben Schaaf]

hey there ps :)

Good question- a question that has no right or wrong answer.

Each header and value serve a purpose. The header fields that are sent and returned will differ for each app depending on the functionality you need to support. 

For example, if your app needs to support authentication (uses Authorization), CORS (uses Access-Control-Expose-Headers, Access-Control-Allow-Origin, etc), and support XML and JSON (uses Accept and Content-Type) you will use a variety of headers.

Instead of rattling headers with little context, I would recommend you continue down your current path of discovery. Review APIs that you are familiar with (Github is a good one) and learn what headers they use, and then look up what each means. Resource: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers

One last note from me: In addition to standard HTTP headers, your app may require custom headers (sometimes prefixed with "X-"). If you are reviewing Github, see X-RateLimit-Limit for an example.

Good luck!!

--
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.

[ps]

Thanks Ben, this is more or less ground I already covered, but I'm looking more toward different API frameworks to see what, if any, commonality they share.

Are there some headers that any good framework should include? (Content-type for returning JSON, for example.)

[Chris Mullins]

For the API Guidelines that I'm involved with, I have the following (apologies for the wacky formatting):

1 Standard Request Headers

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.

All header values MUST follow the rules set forth in RFC2616; see “token.” 

 

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= representation	If 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. 

Cheers,

Chris

[ps]

Interesting (and the formatting looks good over here). Thanks!

I hadn't encountered the Prefer header before.

[Ben Schaaf]

Our API supports CORS, so in addition to some of the headers Chris mentions, we use the italicized subset of the common CORS-related headers.

Response Headers

Access-Control-Allow-Origin

Access-Control-Expose-Headers

Access-Control-Max-Age

Access-Control-Allow-Credentials

Access-Control-Allow-Methods

Access-Control-Allow-Headers

Request Headers

Origin

Access-Control-Request-Method

Access-Control-Request-Headers

Resource: https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS#The_HTTP_response_headers

--

[Chris Mullins]

The list I posted was the standard set that pretty much all APIs prefer. I've got a fairly detailed section on CORS in that same document.

If you're at the Detroit event later this month, I'm hoping to solicit some feedback on the API Standards doc I've been working on for the past few months.

Cheers,

Chris

[Ben Schaaf]

I wish I was going. I won't be back in town until Tuesday.