Manage Database Infrastructure with Aiven's API

Perhaps you recognise Aiven as the multicloud platform for all your open source data needs, with the lovely web interface. And perhaps, if you didn't already, you recognise us that way now :) But Aiven is more than just a pretty web interface, we also have an API for all your integration/automation needs. In this post, we'll take a look at using the API and what you can do with it.

Meet the API

Aiven offers an HTTP API with token authentication and JSON-formatted data. A great place to start is the API reference documentation which gives you the details of all the endpoints. The API supports pretty much everything you can do with the web console ... because the web console uses the API too!

Get your auth token

To access the API, you'll need an access token. To obtain this, log into your Aiven account and go to your profile page; then under "Authentication Tokens" click "Generate Token". This prompts for a token description (for your own reference) and some expiry configuration. It's probably a good idea to set the token to expire after a while (for example, a week is 168 hours) but of course the choice is yours.

Copy the new token to somewhere safe, you won't be able to access it again.

If you lose your token, revoke it and generate a new one at any time. It's good practice to rotate tokens from time to time. Note to self: revoke the token used in these examples when this post is published!

First steps: using cURL

We'll be using the terminal for this section, so set the token you copied before as an environment variable:

export AIVEN_API_TOKEN=[paste]

Starting simple, try getting a list of projects using the API. Here's a cURL showing this in action.

curl -H "Authorization: aivenv1 $AIVEN_API_TOKEN" https://api.aiven.io/v1/project

I use this call quite often, because many endpoints take the project as a parameter. If reading raw JSON isn't your thing, then one option is to use a tool called jq to make things more readable. Pipe your curl output to it, like this:

curl -s -H "Authorization: aivenv1 $AIVEN_API_TOKEN" https://api.aiven.io/v1/project | jq ".project_membership"

This returns the fields we're most interested in: the project names and our role for each.

API calls with Postman

If you prefer a GUI application for trying out API calls, then that seems pretty reasonable to me! There are lots of options but for this example I'll be using my personal favourite, Postman. It's available as a cross-platform desktop app, or it can be used from the browser.

✨ Magic alert ✨ Since Aiven offers an OpenAPI description of the API, we can use this to get a ready-made set of collections to use in Postman!

1. Download the OpenAPI description file from the API documentation itself, using the "Download" button.

1. Import the OpenAPI file into Postman. This creates a new collection in the left hand bar called "Aiven".

1. On the left side of the window, right-click your new Aiven collection and select Edit. On the "Authorization" tab, on the Type drop-down, select Bearer Token. Copy your API token into the field on the right, or as shown in the screenshot, use Postman's variables feature to store this separately.

You're all set! Check things are working by looking in the "Project" folder in the collection and running the "List projects" request. Postman helpfully detects the JSON response and formats the output nicely for us.

Creating Aiven services from the API

We can do more than just fetch some data fields from the API; let's go ahead and create some services.

By default, Postman organises requests by URL segment, so we need to go digging at this point! Under "project" and then "{project}", it's the "Services" folder we want. And there: "Create a service" is the request to open.

On the "Params" tab, enter the project name that you will be using.

Check the Authorization tab has the type set to "Inherit auth from parent". This will pick up on the token or variable we configured on the collection earlier.

Creating services needs a specific JSON API structure to be sent to the API, but in the "Body" tab Postman already has the outline and we can add the values we want to use. This endpoint allows quite a lot of configuration but checking the API docs for the Create Services endpoint shows not all fields are required. In fact, this payload is enough to get a service going:

{
    "plan": "business-4",
    "service_name": "data-and-clouds",
    "service_type": "pg",
    "cloud": "google-europe-north1"
}

If all goes well, you will get a response with a 200 status, and some data about your new service! It takes a few minutes to be responsive but essentially that's all there is to it.

Wondering which other clouds you could choose? Try the list clouds endpoint and take your pick!

Whatever next?

We'd love to hear how you use our API in your workflow!

Depending what you're interested in, try some of these handy links next:

• The Aiven API reference for more information on any of the endpoints not covered here
• We also have a command line tool; an excellent addition to the developers' toolbox when working with Aiven
• For infrastructure integration, try the Aiven terraform provider
• Check out Postman, the HTTP client used in the examples in this post.