Lukasz Czerpak

PAPI JSON: Syntax checking and code completion

Blog Post created by Lukasz Czerpak Employee on Feb 9, 2018

One of the features that is hard to live without is static code analysis and code completion when editing source code. This is pretty standard feature for most of programming languages these days and supported by all IDEs. It helps to early identify typos, common mistakes and helps with code development. You can get immediate feedback during typing as it doesn't require to make any API call.

 

The good news is that we publish JSON Schema for PAPI Rules which can be used to apply static code analysis and code completion when you edit your configuration in JSON format. Let me show you how to do it in Visual Studio Code.

 

Prerequisities

 

The JSON Schema vary across product types so it's important to use the one that matches product associated with your configuration.

 

The schema can be obtained from OPEN API and you need to provide with the following information:

  • Contract ID 
  • Product ID
  • Ruleset version

 

However, Contract ID is the only information you need to know beforehand. Everything else can be fetched from the API.

 

Note: In all examples I use fantastic HTTPie and equally cool jq for filtering JSON results. Here you can find more details on this tandem: Exploring Akamai OPEN APIs from the command line using `HTTPie` and `jq` 

 

In order to get Product ID from OPEN API, run the following command:

❯❯❯ http --auth-type edgegrid -a GCS: ':/papi/v0/products?contractId=ctr_C-1ED34DY' | jq '.products.items[].productId'
"prd_Obj_Caching"
"prd_Site_Defender"
"prd_Rich_Media_Accel"
"prd_Web_App_Accel"
"prd_Site_Accel"
"prd_Progressive_Media"
"prd_Site_Del"
"prd_HTTP_Downloads"
"prd_Alta"
"prd_SPM"
"prd_Adaptive_Media_Delivery"
"prd_EdgeConnect"
"prd_Security_Failover"

 

Ruleset versions can be obtained via the following API call:

❯❯❯ http --auth-type edgegrid -a GCS: ":/papi/v1/rule-formats" | jq '.ruleFormats.items[]'
"v2017-06-19"
"v2016-11-15"
"v2015-08-17"
"latest"

 

Now, once we have all necessary information, we can download the JSON Schema and store in a file. I save it in the same folder where I plan to keep my configuration file:

❯❯❯ http --auth-type edgegrid -a GCS: ":/papi/v1/schemas/products/prd_Site_Accel/v2017-06-19" > schema.json

 

Enabling PAPI JSON schema validation in Visual Studio Code

 

I saved the file in the same directory where I keep configuration files. This is useful if you have different products under the contract as validation rules may vary. Keeping them together with configuration files makes it also easy to setup in VSCode.

 

Go to VSCode --> Preferences, choose WORKSPACE Setting and put the following snippet:

{
    "json.schemas": [
        {
            "fileMatch": [
                "*.papi.json"
            ],
            "url": "./schema.json"
        }
    ]
}

 

The above enables validation of all files in the workspace which name matches "*.papi.json".

 

Here is short screencast demonstrating how to do it. Please note that at the end I intentionally wrap true value with brackets in example code to see if the validation works. After this change, corresponding fragment is highlighted and the error message says that only "true" or "false" values are allowed, not literals:

 

 

Action!

 

Once the IDE is setup, let's create a very simple configuration and leverage static code validation and code completion:

 

 

Summary

 

By using IDE's built-in JSON validation and code completion, we can significantly reduce number of typos and syntax errors when working on PAPI code. It doesn't replace full validation which is done eventually by Property Manager API when the rules are submitted, however makes life much easier. Happy coding!

Outcomes