Yesterday, Amazon announced a major update to their Python client, boto3. The core functionality is unchanged but they used a clever solution to make it easier to add, modify, and remove endpoints. By coming up with a standardized representation for each of the endpoints they’re able to write wrappers in different languages that generate the API calls programmatically. For example, I’ve included a subset of the EC2 definition below. It contains the information necessary to programatically generate the API wrapper to hit the appropriate EC2 endpoints.

{
  "service": {
    "actions": {
      "CreateDhcpOptions": {
        "request": { "operation": "CreateDhcpOptions" },
        "resource": {
          "type": "DhcpOptions",
          "identifiers": [
            { "target": "Id", "source": "response", "path": "DhcpOptions.DhcpOptionsId" }
          ],
          "path": "DhcpOptions"
        }
      },
      "CreateInstances": {
        "request": { "operation": "RunInstances" },
        "resource": {
          "type": "Instance",
          "identifiers": [
            { "target": "Id", "source": "response", "path": "Instances[].InstanceId" }
          ],
          "path": "Instances[]"
        }
      },
      ...
    }
  }
}

This domain specific approach is great when working with APIs and I’m surprised more libraries don’t adopt it. The benefits include being able to keep the actual code the same and only updating the definitions as well as having definitions shared across various language implementations. An additional benefit that can be gotten is actually downloading the latest definitions at runtime. This way you’re always running against the latest version of the API and don’t have to worry about upgrading versions.

I’d love to see more companies adopt this approach and even come up with a standard API declaration language. Then a single set of scripts can be used to wrap any API. Imagine how much simpler it would be to integrate with third party APIs when all you need to do is read the docs and have everything else wired. In fact the docs themselves can be generated from the base definitions.