maglietti/SDLC.md

## SDLC.md

      
    Raw
  

              SDLC.md
            
          
    Akamai OPEN APIs Software Development Life Cycle

Whether you're deeply integrating configuration into your system or automating purge requests based on site changes, there's a process to follow before the code is ready to be put into production.  This post covers the ideal process for getting your API integration into a stable code setup.
Getting Started

The first thing you'll likely want to do is to learn how to get setup using the APIs.  To get started, you can use the sample code in the api-kickstart. There are code examples there for Python and PHP.  If you have already created API credentials in Luna, you can jump right in by reading the README files for each of the languages in the examples directory of your repository.
Follow the Getting Started tutorial to get your credentials set up and run some sample code.
If you want additional output, you can set command line flags:

Use --verbose to see the output from the command, with the JSON formatted for readability.
Use --debug flags to see the HTTP trace, useful for debugging client/server issues.

Command Line Exploration

The next step you'll likely want to do is to have a way to explore the various APIs from the command line, so you can easily see how the various endpoints work without having to update the code.
We recommend that you install and use HTTPie to explore the OPEN APIs from the command line using the http tool.  There's a blog post with helpful information on getting started at Exploring Akamai OPEN APIs from the command line using HTTPie and jq.
Once your credentials are setup as in the previous step, you will be able to make simple calls such as:
$ http --auth-type=edgegrid -a default: :/diagnostic-tools/v1/locations
HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 1576
Content-Type: application/json;charset=UTF-8
Date: Wed, 02 Sep 2015 17:58:04 GMT
Server: Apache-Coyote/1.1
X-Content-Type-Options: nosniff
X-RateLimit-Limit: 180
X-RateLimit-Remaining: 179

{
    "errorString": null, 
    "locations": [
        "Miami, United States", 
        "Newark, United States", 
      ...
        "Skondal, Sweden", 
        "Stockholm, Sweden", 
        "Skarholmen, Sweden", 
        "Seoul, South Korea"
    ]
}

As you can see, the headers from the server are printed by default.  With this command, you can easily see the HTTP status of the command, as well as other information like the rate limit information and Content-Type.
Once you have the basic call to locations working, you can make a more extensive call to dig using the command line flags supported by HTTPie.  Check the reference documentation for Diagnostic Tools to determine which parameters to pass.  In this case, you need to pass the following parameters:

hostname - the hostname to check the network traffic to
location - the akamai location to check the network traffic from
queryType - What type of record you want to query - A, AAAA, PTR, SOA, MX, or CNAME

$ http --auth-type=edgegrid -a default: :/diagnostic-tools/v1/dig hostname=="developer.akamai.com" location=="Skondal, Sweden" queryType==A
HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 3287
Content-Type: application/json;charset=UTF-8
Date: Wed, 02 Sep 2015 18:18:38 GMT
Server: Apache-Coyote/1.1
X-Content-Type-Options: nosniff
X-N: S
X-RateLimit-Limit: 90
X-RateLimit-Remaining: 89

{
    "dig": {
        "answerSection": [
            {
                "domain": "developer.akamai.com.", 
                "preferenceValues": null, 
                "recordClass": "IN", 
                "recordType": "CNAME", 
                "ttl": "300", 
                "value": "developer.akamai.com.edgekey.net."
            }, 
            {
                "domain": "developer.akamai.com.edgekey.net.", 
                "preferenceValues": null, 
                "recordClass": "IN", 
                "recordType": "CNAME", 
                "ttl": "21600", 
                "value": "e8952.dscb.akamaiedge.net."
            }, 
            {
                "domain": "e8952.dscb.akamaiedge.net.", 
                "preferenceValues": null, 
                "recordClass": "IN", 
                "recordType": "A", 
                "ttl": "20", 
                "value": "2.17.162.33"
            }
        ], 
        "authoritySection": [
            {
                "domain": "dscb.akamaiedge.net.", 
                "preferenceValues": null, 
                "recordClass": "IN", 
                "recordType": "NS", 
                "ttl": "4000", 
                "value": "n1dscb.akamaiedge.net."
            }, 
            ...
        ], 
        "errorString": null, 
        "hostname": "developer.akamai.com.", 
        "queryType": "A", 
        "result": "\n; <<>> DiG 9.8.1-P1 <<>> developer.akamai.com -t A\n;; global options: +cmd\n;; Got answer:\n;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 6279\n;; flags: qr rd ra; QUERY: 1, ANSWER: 3, AUTHORITY: 8, ADDITIONAL: 8\n\n;; QUESTION SECTION:\n;developer.akamai.com.\t\tIN\tA\n\n;; ANSWER SECTION:\ndeveloper.akamai.com.\t300\tIN\tCNAME\tdeveloper.akamai.com.edgekey.net.\ndeveloper.akamai.com.edgekey.net. 21600\tIN CNAME e8952.dscb.akamaiedge.net.\ne8952.dscb.akamaiedge.net. 20\tIN\tA\t2.17.162.33\n\n;; AUTHORITY SECTION:\ndscb.akamaiedge.net.\t4000\tIN\tNS\tn1dscb.akamaiedge.net.\ndscb.akamaiedge.net.\t4000\tIN\tNS\tn0dscb.akamaiedge.net.\ndscb.akamaiedge.net.\t4000\tIN\tNS\tn2dscb.akamaiedge.net.\ndscb.akamaiedge.net.\t4000\tIN\tNS\tn3dscb.akamaiedge.net.\ndscb.akamaiedge.net.\t4000\tIN\tNS\tn7dscb.akamaiedge.net.\ndscb.akamaiedge.net.\t4000\tIN\tNS\tn4dscb.akamaiedge.net.\ndscb.akamaiedge.net.\t4000\tIN\tNS\tn6dscb.akamaiedge.net.\ndscb.akamaiedge.net.\t4000\tIN\tNS\tn5dscb.akamaiedge.net.\n\n;; ADDITIONAL SECTION:\nn0dscb.akamaiedge.net.\t4000\tIN\tA\t88.221.81.195\nn1dscb.akamaiedge.net.\t6000\tIN\tA\t184.85.223.238\nn2dscb.akamaiedge.net.\t8000\tIN\tA\t82.96.58.97\nn3dscb.akamaiedge.net.\t4000\tIN\tA\t80.239.206.134\nn4dscb.akamaiedge.net.\t6000\tIN\tA\t184.85.223.240\nn5dscb.akamaiedge.net.\t8000\tIN\tA\t184.85.223.239\nn6dscb.akamaiedge.net.\t4000\tIN\tA\t184.85.223.234\nn7dscb.akamaiedge.net.\t6000\tIN\tA\t184.85.223.236\n\n;; Query time: 27 msec\n;; SERVER: 127.0.0.1#53(127.0.0.1)\n;; WHEN: Wed Sep  2 18:18:38 2015\n;; MSG SIZE  rcvd: 432\n\n"
    }
}

Printing out the final section "result" will give you the pretty formatted output given by the initial sample code.
Exploring further with HTTPie

Now that you have your credentials set up and know how to go through the workflow to make a dig call, try experimenting with the other diagnostic-tools endpoints.  For instance, try using the akamaitranslator to see the information about your hostname:
http --auth-type=edgegrid -a default: :/diagnostic-tools/v1/akamaitranslator hostname==princesspolymath.com
HTTP/1.1 200 OK
Connection: keep-alive
Content-Length: 207
Content-Type: application/json;charset=UTF-8
Date: Wed, 02 Sep 2015 18:24:11 GMT
Server: Apache-Coyote/1.1
X-Content-Type-Options: nosniff
X-N: S
X-RateLimit-Limit: 90
X-RateLimit-Remaining: 89

{
    "arl": {
        "cacheControl": null, 
        "cpCode": "384473", 
        "errorString": null, 
        "originServer": "origin.princesspolymath.com", 
        "pragma": null, 
        "serialNumber": "19", 
        "ttl": "Infinite", 
        "typeCode": "Object changes when ARL changes"
    }
}

Try the other commands as well.  Note that the ipgeolocator will only work when you have Edgescape active on the contract.
Now that you're familiar with the httpie command, look through the example code and documentation to pick another API you're interested in.  Go back into luna and create credentials for another API.  Use gen_edgerc.py again to create another section in the edgerc file, and then give that command a try.  Note that when you are using a different section, you will need to tell httpie that you want to use a different one.
http --auth-type edgegrid -a <sectionname>: :/ccu/v2/purge/default
Ready for production

Whatever programming language you prefer, we likely have an EdgeGrid library all ready for you to use.  Using one of these libraries is the most stable way to introduce the Akamai OPEN API interaction into your code.  There is sample code for each example as well.
Prototype

Before you can start thinking about moving your new code into production, you need to get calls working in the language you're comfortable with.  Create a simple application or library using the signing library, and work from there.  It's best not to use HTTPie (or egcurl) for this purpose - calling out to a shell command is unstable and can definitely cause issues.  Use the library so you get back the objects in a way that your language can use them, and integrate this functionality into your own processes.  We see many customers sticking with the egcurl calls, and this method simply isn't production-ready.

mention our REST philosophy
talk about JSON schema for data validation -- future article

Rate Limits


talk about x-headers
talk about request frequency
general BCP recommendations for production request call gaping
synchronous APIs with asynchronous responses (implement retry-after!)

Error Handling


talk about http-problems

If you are able, please consider sharing your code (or parts of it) into the akamai-open repository to help others along.  We'll share credit however you like, and you'll help future developers find their way more quickly.
Thanks for following along.  If you have additional questions or issues, please reply here or elsewhere on the community and we'll do our best to get back to you with a great answer!