ArangoDB Oasis, the cloud service of ArangoDB, has been available for a few months now and is growing quickly. The Oasis team got a lot of requests to provide more ways to manage deployments, access policies and other aspects of Oasis.

After adding support for Azure earlier this year, we’re now opening up the Oasis API for all supported cloud providers like Google Cloud and AWS.

What is it (not)?

So what is the API about and what can you do with it? And didn’t ArangoDB already have an API? How is this different?

The Oasis API is an API to control all resources in your Oasis account. These resources include projects, certificates, IP whitelists and of course deployments. The API does NOT cover resources inside your deployments such as collections, graphs and documents. For those, you should use the standard ArangoDB HTTP API.

So to summarize, everything you can do in the Oasis dashboard, you can now also do using the API. In fact, the Oasis dashboard is built on top of the Oasis API.

What can you do with it?

The list of cases you can now automate using the Oasis API is very long.

We want to give a few examples.

Continuous integration

Let’s say you’re working on an application that is using ArangoDB as the database layer. Your application components are being tested on every commit and probably also nightly in a CI system. Of course you want these tests to be repeatable and in order to do so, the underlying data must also be repeatable.

This is where the Oasis API can help you. Using the API, the CI server can spin up an ArangoDB deployment and wait for it to be ready. Then using standard ArangoDB import and/or document APIs you fill the deployment with a well known set of data. Once that is done, your CI server runs all the component tests against that data and finally removes the deployment again to save money.

In the not so far future, you’ll also be able to clone your production deployment, run tests of your actual data and remove this cloned deployment afterwards.

Automatic scaling

Let’s assume that you’re running a website that has very low traffic, with the exception of a few specific dates. In order to save cost, you do not want to run a database with lots of CPU and memory reserves all the time, just to cope with the high load on these few dates.

You can now schedule a job that uses the Oasis API to increase your node-size just before each of these special dates and reduce it again afterwards.

Of course, if the load actually becomes even higher than expected, you can use the same API to increase the resources even further. Please note that only CPU and memory can be scaled back.

How does the API look and how do I use it?

The Oasis API uses protocol buffers as interface definition and gRPC as the underlying protocol. This means that the number of languages in which you can access the API is huge.

We provide you directly with a Go client but using the standard protoc tool and language-specific plugins, you can create clients for many languages such as Java, Python, Ruby, NodeJS, PHP, C# and many more.

Here’s how it looks (in the Go language) to connect to the Oasis API.

And then you can list all your deployments in a project like this:

Note that the API is split into various services, each contained in its own file & namespace.

For example there is:

  • IAMService
  • ResourceManagerService,
  • a DataService and so on.

Each of these services cover a specific set of features of the overall Oasis platform.

What about scripting?

The Oasis API is usable from many languages, but still requires some form of programming to use it. We recognize there are also many cases where you just want to script something. For those cases, we’ve created oasisctl. See the tutorial for Oasisctl.

Oasisctl is a commandline utility that wraps almost the entire API. Instead of using the code above to list deployment, one can also run:

Oasisctl has many commands. To get an overview of these commands, run:

Note that oasisctl is also a very easy companion for when you do use the full API. For example, there are many places in the API where you need to fill IDs. Oasisctl has many commands that show these IDs.

For example, to make a deployment, you need the ID of the node size.
With Oasisctl you can query these node sizes using the following command:

See how to authenticate with Oasis and create, manage or delete deployments in the tutorial.

I’m a big fan of Terraform. Can I use that?

At ArangoDB we’re also big fans of Terraform, so we’ve got you covered. We’ve created a terraform provider for Oasis, which we’ve now made open source as well.

This provider is currently in preview, so its exact API may still change. We welcome your feedback! Feel free to tell us on GitHub.

What is next for the API?

The Oasis API is at the heart of the Oasis platform. As we add more features to Oasis, we will extend the API as well.

In order to allow us to extend the API, we’ve included a “v1” version identifier in all API services. If at some point we find that we need to break an existing API, we will not do so. Instead we’ll introduce a “v2” version of the API (or of a specific service in the API). That keeps the “v1” part of the API at least backwards compatible.

To know exactly which version of the API is currently available, each service in the API has a method called GetAPIVersion. This method returns the current major, minor & patch version of that service. You should compare those numbers against the APIMajorVersion, APIMinorVersion & APIPatchVersion constants that are in every service of the API. As soon as we’re adding features to a service, we will change those version constants.

Once we reach a “v2” of a service within the API, the GetAPIVersion of that service will return 2 as its major version number, even when the GetAPIVersion is called on the “v1” API of the service.

Note that it is possible that GetAPIVersion returns a lower version number than what is currently listed in the GitHub repository. The reason for this is that we develop the API in a public repository, but not all changes are being made available onto our production environment at the time we commit a change into our APIs repository. For that reason, you should always check (using GetAPIVersion) what the currently available version of a service is.

We think it is a pretty neat extension of Oasis and appreciate any feedback you have! If you made something cool with the Oasis API, please let us know.

How can I get started?

If you are new to Oasis, just create a free account and deployment (no credit card needed).

For getting started with oasisctl, you can check out the oasisctl tutorial or visit Oasis API Documentation for more details.