The Usage API requires a specific request structure that includes the request path, hostname, and both the action and signature headers.

Usage API format structure

Each line in the example reflects content that must exist on its own line in the request, here we define the Variable values:

1. [Method] /[Path] HTTP/1.1
2.    Host: [Connection Hostname]
3.    [Action Header]
4.    [Signature Header 1]
5.    [Signature Header 2]
6.    
7.    [Body (if applicable)]

• Line 1: The method and request path. This includes the applicable [Method] required for the action, the /[Path] to the desired destination in NetStorage originating with the Content Provider (CP) code value that serves as the root of the target storage group, and finally the HTTP version (HTTP 1.1).
• Line 2. The Host: string identifies the [Connection Hostname]. It uses your unique NetStorage HTTP API domain name. This value is also referred to as your Connection Hostname.
• Line 3. The [Action Header] is the applicable X-Akamai-ACS-Action header formatted for the desired call. Individual, per-call usage requirements are found in the description of the specific action.
• Line 4 and Line 5. The [Signature Header] lines are two separate headers used to authenticate and authorize each call made to the API.
• Line 6. This is an empty line.
• Line 7. The [Body]. If the call uses a PUT or POST Method, the applicable [Body] component is required.

📘

Lines 6 and 7 are not required if the call uses a method other than PUT or POST. See the description of the specific call for more details.

Example format of an upload request

PUT /123456/files_baseball/sweep.m4a HTTP/1.1
Host: example-nsu.akamaihd.net
X-Akamai-ACS-Action: version=1&action=upload&md5=0123456789abcdef0123456789abcdef&mtime=1260000000
X-Akamai-ACS-Auth-Data: 5, 0.0.0.0, 0.0.0.0, 1280000000, 382644692, UploadAccountMedia ← [signature header 1]
X-Akamai-ACS-Auth-Sign:yh1MXm/rv7RKZhfKlTuSUBV69Acph5IyOWCU0/nFjms= ← [signature header 2]

[PUT body]

The flow of a typical request

These steps that follow detail the flow of a request and how it is handled for an API call.

Where a "Requirement" is listed, this is an activity that you must perform in the call itself, or prior to the call, when configuring the applicable header.

🚧

Although there are multiple operations (“actions”) available, only one action is supported per request.

1. The X-Akamai-ACS-Action ("action") header is located.
   • If this header is missing: The request is not an API request. It may, however, still be a valid request that can be served.
   • If this header is present: The request is handled by the API, as either a valid operation or an error.
2. The action header is parsed using standard “query string” parsing rules.

📘

Query string syntax already supports escaping arbitrary characters. Use care to escape at least spaces (" "), equal signs ("="), plus signs ("+"), and ampersands ("&") in any values you generate.

3. The header must contain a version action header field with a value set to 1, otherwise the request will fail.
   • Requirement: Any legacy headers are denied. Unexpected X-Akamai-* headers may result in the request being denied to avoid potentially incorrect or ambiguous behavior. Below is an example of the appropriate syntax using the upload action:

PUT /[CP Code]/[path]/[file.ext] HTTP/1.1
  Host: example-nsu.akamaihd.net
  X-Akamai-ACS-Action: version=1&action=upload&md5=0123456789abcdef01234 56789abcdef&mtime=1260000000
  [Signature Header 1]
  [Signature Header 2]
            
  [PUT body]

4. The request URL is checked for validity according to normal NetStorage rules.
   • Requirement: This URL should begin with the same [CP Code] root that you use with other NetStorage protocols to target the associated storage group. The URL will name the file or directory that will be queried or modified in this request.
5. The header field action is reviewed to determine the appropriate operation.
   • Requirement: A supported “Action” must be defined in the context of the X-Akamai-ACS-Action header. This includes the various actions discussed throughout this documentation. (For example, upload, stat, dir, and list are supported actions.) Only the actions discussed in this documentation are valid; anything else will return an error.
6. The validity of the Signature Header Authentication in the X-Akamai-ACS-Auth-Data/X-Akamai-ACS-Auth-Sign headers is verified.
7. The defined action is processed.

Each call requires the proper HTTP version

The HTTP version in use is required in the request path of a call.

📘

When including the version, ensure that it is prefaced by a whitespace.

This requirement is outlined in the Hypertext Transfer Protocol specification that is set by w3.org: http://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html. See Section 5.1.2.

The current version is 1.1.

    PUT /[CP Code]/[path]/[file.ext] HTTP/1.1

Most languages and associated tools will offer automatic support for the inclusion of this value. However, you must ensure that this component is included in the API call.

Each call needs your connection hostname

Each API call requires that you define the HOST: and include your connection hostname. See Gather details for API usage for details.

This full value is your NetStorage HTTP API "Connection Hostname". The [Domain Prefix] is a unique value you set up and associate with the target storage group when it is created. The remaining value, "-nsu.akamaihd.net" is the specific URI associated with the NetStorage Usage API.

You can view your connection hostname in the NetStorage Groups UI in Control Center.

    Host: [Domain Prefix]-nsu.akamaihd.net

Each call uses the "action" header

This API uses a unified “action” HTTP header that specifies which action to perform on the object name specified in the Request Path.

This header may include a variety of “fields” and acceptable HTTP methods include GET, POST, or PUT depending on the operation.

The Edge network can proxy all of the different methods currently used by various clients. (This includes GET, PUT, POST and DELETE.) To keep the API simple, the “action” header is authoritative. If you want to use action-specific HTTP methods, the Edge network can convert methods like DELETE and others to POST and include an “action” header.

Action header "version" and authentication

The header itself includes a version number and any other arguments the operation requires. The version (which at present is always “1”) identifies the protocol, which eliminates backward compatibility concerns. Any request with the “action” HTTP header is treated as an API request and is authenticated with a shared key authentication scheme. If this authentication fails, the request is denied with an HTTP 403 error.

Action header “field” syntax: query string encoding

Action headers can contain required and optional “fields.” Each field is separated by an ampersand (“&”) and its contents must be input using standard “query string encoding” (URL encoding). For example, if the upload action also included a field entitled target which requires the variable, /files/new file-1.txt, it would be input as follows:

    version=1&action=upload&target=%2Ffiles%2Fnew%20file-1.txt

📘

Query string encoding also supports the use of a plus sign (“ + ”) to designate a whitespace.

What to include for the "PUT/POST Body" component

All operations that require either a PUT or POST method must include a request message body.
This body is delimited using the Content-Length: header or a Transfer-Encoding: chunked
header. Most of these PUT/POST operations do not specify any request body content, so an empty body should
be sent using either of these header formats:

• Content-Length: 0
• Transfer-Encoding: chunked - Followed by an empty chunk-encoded body.

📘

This applies to all PUT/POST requests, except when incorporating the upload
action. Specific usage requirements apply, and they're discussed in the description of
the related operations.