HTTP Headers

This topic provides information about HTTP request and response headers used in the platform's API operations. It includes:

HTTP Request Headers

The Akana API Platform 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. 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.

Note: In many cases, an operation works even if you don't specify an Accept header, since a missing Accept header implies a value of */*. In this case, the operation returns the media type that was defined as the default for that operation.

The API Platform API uses the Accept header media type to determine which version of the API response the client is expecting. For this reason, it's important to include the specific Accept header so that the response message is compatible to the API version that the client is tested with, even if the platform is upgraded to a new version.

In some cases, it's possible that if you are relying on a default media type it might no longer work when a new operation is introduced. If the documentation specifies a media type for the Accept header, it's best to always specify one of the valid 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.
Cache-Control Both Used in both request and response to specify whether the message can be cached between the client and the server. Akana API Platform 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 API Platform 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 example, the POST /api/login/renewToken operation.

For information on valid values, see Media Types.
Cookie Request Only An extension header used for client identification and tracking. In the Akana API Platform API the cookie parameter contains the session ID.For more information, see Cookies in the Akana API Platform.
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 API Platform API uses this header, the value is XMLHttpRequest.
X-Csrf-Token_{fedmemberid} Request Only

A custom header used for protection against CSRF attacks. For more information, see CSRF Prevention on the Platform.

Uses the FedmemberID for the tenant.

HTTP Response Headers

The Akana API Platform 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
Allow Response only Returned when the request is using an HTTP method (verb) that is not supported by the operation, and the platform therefore returns an HTTP 405 Method Not Allowed response. The response includes a list of the HTTP methods that are valid for the resource. See also HTTP Status Codes: 405.
Atmo-Renew-Token Response only

A custom response header used when an action, by the current user or another user, causes a change in a value that's stored in the token. The token includes information on the user's permissions to 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.

Two possible values:

  • A value of renew indicates that the operation has changed some information that's stored in the token, and you must therefore renew the token using the POST /api/login/renewToken operation.

    This is the more common value for the Atmo-Renew-Token.

  • force-renew. Indicates that an action has been taken by another user, which should force a change in the current user's permissions as represented in the token. For example, if the current user is an API Admin for a private API, and another user removes that role, the next action that the current user takes that might require permissions returns the Atmo-Renew-Token with a value of force-renew, and the token must then be renewed. You can renew the token using the POST /api/login/renewToken operation.
Cache-Control Both Used in both request and response to specify whether the message can be cached between the client and the server. Akana API Platform 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 API Platform API always returns a gzip-encoded response if the request header indicates that gzip encoding is accepted for responses.
Content-Disposition Response only An opportunity to raise a "File Download" dialog box for a known binary file type, or to suggest a filename. This facilitates prompting the user to save the file directly to disk, bypassing the default behavior of displaying the file in the browser. All operations that return content as a downloadable file, such as app and API export files and metrics, use this header. For more information, see Downloadable Files in Response Messages.
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, application/xml, or text/plain. In many cases, values include vendor-specific versions for application/json and application/xml; for example, application/vnd.soa.v81+json. For more information, see Media Types.
  • 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.

    For more information about uploading files to the platform with the multipart/form-data media type, see Managing Multipart/Form-Data Uploads.
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 HTTP 307 Temporary Redirect, to provide the URL location for the redirect. For example, the GET /api/login/ssoLogin operation uses this response header.

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. For example, the authentication token includes information about groups that the user is a member of, so the POST /api/groups, DELETE /api/groups/{GroupID}, and DELETE /api/groups/{GroupID}/members/{UserID} operations return an updated cookie. Operations relating to signing in, such as POST /api/users/completeSignup, also update the cookie. The POST /api/login/logout operation returns an updated value that expires the browser cookie since the user is logging out.
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 API Platform 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.
X-Frame-Options Response only

Optional header, set up by the Administrator in the Akana Administration Console, com.soa.uif configuration category. Used as a security measure, with services that return content, to indicate whether or not the browser is allowed to render a page in an <iframe> tag. Generally used to prevent clickjacking attacks by ensuring that site content cannot be embedded into another site, displayed in an iFrame. Note that the Community Manager developer portal displays content in iFrames, so if the X-Frame-Options header is set to a value of deny, some site content might not display correctly.

There are two valid values (case does not matter):

  • deny
  • sameorigin

Note: A third value for the X-Frame-Options header, ALLOW-FROM, is obsolete. Do not use it.

For more information about this header, see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options.

For an example, see GET /ui/apps/atmosphere/{version}/{path:resources/.*} (Sample Response section).