Get to know the Aiven API with Postman

Choosing cloud providers with APIs is a smart move; having an API available means you can build any additional integrations that your application requires, in addition to what's provided as standard. The downside is getting to know someone else's API, which can be a slow and painful process if good developer resources aren't available.

At Aiven we'd love you to get to know our API, so we created a Postman collection to help you get started. If you haven't used Postman, it's a friendly interface for humans to work with APIs. We use it ourselves, so we created something you could use too. In this post, you'll use Postman to take your first steps with the Aiven API.

Before you start

You can use Postman either in your web browser or as a desktop application. Whichever you choose, sign up for a free account, or sign in if you have one already.

Navigate to the collection. To get your own copy of the collection to work with, right-click on the collection and choose "Create a fork".

You're prompted to give the collection a name, and which workspace to move it to. "My workspace" is a good choice if you're not sure.

Get your head in the clouds

The first API call we'll make is simple: ask the Aiven API for a list of all the clouds that a user can deploy their services to on Aiven.

Expand your collection in the left-hand bar and click on "Clouds". The request you want is called "List available cloud platforms", and it doesn't need any editing or changes. Go ahead and click the "Send" button over on the right-hand side.

Well done - you've made your first API call! The results display in the lower half of the screen; Postman autodetects that the response is in JSON, and format it nicely so that us mere mortals can read it. Have a scroll down and pick a location that sounds like a fun place to host your database.

This is fun, but it'll be more fun when you're working with your own databases in the cloud, so the next step is to identify yourself to the API when you make a request.

Send credentials with your API request

When you sign in to a website, you probably use a username and password (Aiven also supports SSO and allows you to add 2FA, in case you're interested). For APIs, we usually use an authentication token. This is good practice because you can create a new token for each application; those credentials can each be independently rotated or revoked without affecting any other applications - because they each use their own tokens.

1. If you don't already have an Aiven account, sign up for a free trial.

2. Visit your Aiven profile page and scroll down to "Authentication tokens" to create a new token.

3. Enter a description so that you will know which token this is, and set the expiry in hours for your token (leave it blank for a token that does not expire). Click "Generate token".

4. Copy the token, ready to set it in the Postman collection.

5. Back in Postman, click the collection menu, and go to "Edit". On the "Variables" tab, paste your token value in under "Current value" for the "authToken" variable. Press the "Save" button on the right-hand side above the tabs.

All the requests in the collection are set up to use this variable, so by setting it here, it's used for all the API calls. Speaking of which, shall we make another one?

Create a cloud database

Aiven offers a variety of different databases and other data things, like Apache Kafka (technically not a database) and Grafana (definitely not a database), and we call them all "services".

In the "Services" folder within the collection, select the request called "Create a service". You can create whichever service type you like, but the example values create a Redis, which is a great place to start.

• Under the "Params" section, update the path variable project with a project name that exists in your account that you want to use.

• This is a POST request, so most of the interesting parts are in the body data; this can be found on the "Body" tab of the request. Have a look at the data, you might like to set a nicer value for service_name, for example.

When you are happy with the values, click "Send". The response should have status 200 and show information about your new service.

The right status code and some JSON is a good outcome, but it's not very exciting, is it? Head back to your Aiven console and you should see a new Redis service.

A whole new Redis to play with! If you click on the service, you'll see an overview page for the service including lots of configuration and the connection information to use it. Check out our docs on connecting to Redis using the redis_cli tool.

Power off the services when you don't need them

One big concern about working with cloud services is how easy it is to start services that then hang around, running up the bills. So, once you've finished playing with your cloud Redis service, let's remove it. It's only a Postman call to get it back, after all.

Look in the "Services" folder of the collection again, and this time select "Delete a service".

On the "Params" tab, enter both the project and service name that you used. Send the request - and again we're looking for a response status of 200 OK.

Check back on your Aiven services list: as if by magic, your service is gone.

Tip: You can also use the "Update service configuration" request and set the powered value to true or false to power off your services when you're not using them. This is especially handy for development platforms that only need to run while you are working, which is hopefully not all hours of the day. Please note that this fully removes the service, and powering it on restores it from a backup. This can cause settings to reset.

Postman, Aiven and APIs

Whether you use Postman for your day-to-day tasks, or use it as an excellent way to get to know a new API, the Aiven Postman collection gives you a way to get started quickly.

Learn more about our API by checking out a detailed blog post about using Aiven's API from cURL and Postman, and the Aiven API reference docs.

The Postman collection has just a handful of endpoints. Tell us what we should add there next! And let us know what you build, we love to see it (and we accept guest blog posts if it's something really cool).