HTTP Headers

This topic provides information about HTTP request and response headers used in OAuth API operations. It includes:

  • HTTP Request Headers
  • HTTP Response Headers

HTTP Request Headers

The Akana OAuth API uses the HTTP request headers shown in the table below. The significant headers are:

Header Name Used In Description/Values
Accept Request Only

Lists one or more data formats that are valid in the response. For example, application/json or text/xml. The Accept header can include other formats as long as the required format is included. It's a good idea to list only the required format, or at least include it as the first on the list.

For information on valid values, see Media Types.
Accept-Encoding Request Only Lists one or more encoding methods that are valid for compression of the response message. This ties in with the response header Content-Encoding which specifies the method actually used. For example: gzip, deflate
Accept-Language Request Only Lists one or more languages that are valid for the response. en-us is preferred, en is valid. For example: en-us,en;q=0.5
Authorization Some OAuth requests Contains the user authentication information: username and password. It's sent by the client, to authenticate the client with the server. A client includes this header in its request after receiving a 401 Authentication Required response from the server. The Authorization header includes the authorization scheme and the authorization value. Some OAuth services require an Authorization header, as noted for individual operations. For more information, see OAuth 1.0a Authorization Header (reference article).
Cache-Control Both Used in both request and response to specify whether the message can be cached between the client and the server. Akana OAuth operations generally do not cache responses, so the value is generally no-cache. In some instances, such as with avatars and content, it is more efficient to cache the information. In these cases, we set a value in the Cache-Control response header. For example: Cache-Control: public, max-age=604800. This sets the content to be cached for 604800 seconds (one week).
Connection Request Only Instructs the server what to do with the connection once the request is received. The keep-alive value for this header means that the connection is kept open for the response.
Content-Length Request Only Indicates the length of the message body, in bytes. Example: 53.
Content-Type Both

Specifies the media type of a request or response message body.

For request messages, content-type is used for POST and PUT but not for GET or DELETE. Most Akana OAuth operations that use this header use application/json in the request message. Methods involving file upload use multipart/form-data. Methods with POST parameters might use application/x-www-form-urlencoded.

For information on valid values, see Media Types.
Cookie Request Only

Akana OAuth API the cookie parameter contains the session ID.

For more information, see OAuth Cookies.
Host Request Only The hostname and port number of the machine sending the message. Example: api.acmepaymentscorp.com.
Referer Request Only The URL from which the request originated. Example: https://api.acmepaymentscorp.com.
User-Agent Request Only Indicates the software/version making the request. Generally includes browser name and version, and sometimes includes additional information such as operating system. Example: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:13.0) Gecko/20100101 Firefox/13.0.1.
X-Requested-With Request Only An extension header used to identify Ajax requests. Wherever the Akana OAuth API uses this header, the value is XMLHttpRequest.

HTTP Response Headers

The Akana OAuth API uses the HTTP response headers shown in the table below. The significant headers are:

  • Content-Type
  • For the specific operations that require it, Atmo-Renew-Token
Header Name Used In Description/Values
Atmo-Renew-Token Response only renew. This is a custom response header used when the action of the method causes a change in a value that's stored in the token. The token includes information on the user's apps, APIs, and groups, so actions such as adding an app or accepting an invitation to join an app team require update of the token. A value of renew means that the operation has changed some information that's stored in the token, and you must therefore renew the token.
Cache-Control Both Used in both request and response to specify whether the message can be cached between the client and the server. Akana OAuth operations generally do not cache responses, so the value is generally no-cache. In some instances, such as with avatars and content, it is more efficient to cache the information. In these cases, we set a value in the Cache-Control response header. For example: Cache-Control: public, max-age=604800. This sets the content to be cached for 604800 seconds (one week).
Content-Encoding Response only Indicates the type of compression encoding the server used for the response message, so that the client can decode the message. This is the counterpart to the Accept-Encoding request header which specifies which types of compression are acceptable in the response. Example: gzip. The Akana OAuth API always returns a gzip-encoded response if the request header indicates that gzip encoding is accepted for responses.
Content-Type Both

Specifies the media type of a request or response message body.

For response messages, content-type is always used. Refer to specific methods for valid values. Some typical scenarios:

  • Generally, response messages use application/json, text/xml, or text/plain.
  • Methods returning an RSS feed generally use application/json unless another format is requested in the request message's accept header.
  • Methods involving file upload use multipart/form-data. When binary data is included in the response, different content-types are used based on the type of the data; for example, image/gif, image/jpeg, image/png, or application/zip.
Date Response only A date/timestamp representing the time on the server when the message response was sent. Example: Wed, 22 Jan 2014 21:09:23 GMT.
Location Response only Used with 302 Redirect in the context of OAuth authorization. When resource owner authorization is successful, the resource owner is redirected back to the client Redirect URL (previously provided by the client) and an HTTP 302 code is returned. The Redirect URL is the value for the Location response header.
Set-Cookie Response only Sends an updated user cookie. Cookies are used for the authentication token, and some operations require an update to the cookie
Transfer-Encoding Response only

If encoding was used to transfer the message safely, this value indicates the encoding method used. Example: chunked. For HTTP 1.1 messages, the Akana OAuth API always uses the value chunked. For HTTP 1.0, transfer-encoding is not used.

Note: We recommend using HTTP version 1.1 since it includes several enhancements; chunking is one of them.