The Questions


The Answers

How do I get permissions for a Client Authorization?

In order to create an OPEN client:

  1. The user authorizing the client must have admin permissions on the Akamai Property in the Luna Control Center. If you do not have admin permissions, you can ask Luna Control Center Administrators.

  2. When granting authorizations, a user with enough permissions must be selected, as the user’s credentials will be used in the background to access the API info.

  3. There is a video on this topic on Akamai University. Check it out!

  4. And the best contact point for help is the Developer Space in the Akamai Community.

How do I build that URL?

Q: These {OPEN} URLs are a bit more complicated than the old-fashioned kind, and the directions for building them are kind of scattered. Can we get it all in one place?

A: Of course!

First off, note that the detailed explanation is in the Client Auth page. Refer there if you need additional info.

But in brief:

You probably first ask this question while looking at some API Reference document. Let’s start from the Billing Center API reference.

There are two things to fill in:

The BASE_URL

In this context, this is really just the hostname portion of the URL, but it encapsulates a lot of information about the rights that are available to your program (the one you’re writing right now, the one that will use the URL we’re building). To grant those rights, and to get a BASE_URL you can use for API access, someone with administrative rights in your account needs to visit the Luna Control Center’s Manage APIs page.

If you are navigating directly from within Luna Control Center, you can find the API provisioning capability in the ConfigureManage APIs menu pick of the main menu. At the end of that process, the application will give you several items, all of which should be treated as security keys, guarded just like a username and password:

  • Client Token
  • Client Secret
  • Access Token
  • Hostname (or full BASE_URL)

A sample BASE_URL might be

https://akzz-vesvjee7gbimrryr-oganfff5qiat27gb.luna.akamaiapis.net/...

The …

Now, what about those dots?

These you get from the Reference document. When the document says something like

POST /billing-usage/v1/contractUsageData/csv

that has to be combined with the BASE_URL info. So, actually, you would issue

POST https://akzz-vesvjee7gbimrryr-oganfff5qiat27gb.luna.akamaiapis.net/billing-usage/v1/contractUsageData/csv

And that’s all there is to it!


How do I build the message?

You can use httpie

If you’re working at the shell prompt, in shell scripts, or in any language that provides something like popen(), then grab the EdgeGrid Client Authentication HTTPie Library from GitHub, or simply run pip install httpie-edgegrid if you have pip installed.

This library extends the HTTPie client to allow for authentication using the standard .edgerc credentials file.

An .edgerc file looks like this:

[default]
client_secret = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=
host = xxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.luna.akamaiapis.net/
access_token = akab-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
client_token = akab-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

With that configuration, you can issue a

GET /diagnostic-tools/v1/locations

http --auth-type edgerc -a default: :/diagnostic-tools/v1/locations

What are these funky “%22” message bodies?

As you read through the {OPEN} Reference documentation, you’ll occasionally find examples like this (from the Billing Center):

reportSources=reportSources%3D%5B%7B%22id%22%3A%20%221-123456%22%2C%20%22type%22%3A%20...

“What in the world is that?” If you’re familiar with our older SOAP APIs, you may even recall something more like this:

reportSources=reportSources=[{"id": "1-123456", "type": ...

which is much less painful.

What’s going on here is this: the API definition (both APIs) requires “a JSON body, url-encoded.” The old documentation shows the JSON body, and has an associated note that you need to encode it. The new documentation, on the other hand, shows the encoded JSON body.

Why the difference? The new documentation needs an exact example of the body, because it has facilities for evaluating messages to see if they conform to the documentation. And we’ll be adding additional design and test tooling that depends on this.

Here’s an example of url-encoding in action.

From the billing-center API reference, to get a list of all products available for a given report set, POST a set of parameters to the /billing-usage/v1/products resource.

Parameters to POST:

reportSources=[{"id":"X-XXXXXXX","type":"contract"}]
startDate={"month":3, "year": 2014}
endDate={"month":3, "year": 2014}

Which, when url-encoded looks like this:

reportSources=%5B%7B%22id%22%3A%22X-XXXXXXX%22%2C%22type%22%3A%22contract%22%7D%5D&startDate=%7B%22month%22%3A3%2C%20%22year%22%3A%202014%7D&endDate=%7B%22month%22%3A3%2C%20%22year%22%3A%202014%7D

Fortunately, httpie makes this fairly straightforward. You can send this request as a POST as follows:

http --auth-type edgegrid -a billingusage: POST :/billing-usage/v1/products reportSources=='[{"id":"X-XXXXXXX","type":"contract"}]' startDate=='{"month":3, "year": 2014}' endDate=='{"month":3, "year": 2014}'

And the API responds with a productId list in JSON.

{
  "status": "ok",
  "contents": [
    {
      "id": "X-X-XXXXX",
      "name": "HTTP Downloads"
    },
    {
      "id": "X-X-XXXXX",
      "name": "NetStorage"
    },
    {
      "id": "X-X-XXXXX",
      "name": "Web Application Accelerator"
    },
    {
      "id": "X-X-XXXXX",
      "name": "All Streaming Delivery"
    },
    {
      "id": "X-X-XXXXX",
      "name": "Kona Site Defender"
    }
  ]
}