Opening the ArangoDB ArangoGraph API & Terraform Provider

Estimated reading time: 6 minutes

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

After adding support for Azure earlier this year, we’re now opening up the ArangoGraph 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 ArangoGraph API is an API to control all resources in your ArangoGraph 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 ArangoGraph dashboard, you can now also do using the API. In fact, the ArangoGraph dashboard is built on top of the ArangoGraph API.

What can you do with it?

The list of cases you can now automate using the ArangoGraph 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 ArangoGraph 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 ArangoGraph 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 ArangoGraph 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 ArangoGraph API.

import (
  "context"
 
  "google.golang.org/grpc"
  "google.golang.org/grpc/credentials"
  "github.com/arangodb-managed/apis/common/auth"
  common "github.com/arangodb-managed/apis/common/v1"
  data "github.com/arangodb-managed/apis/data/v1"
  iam "github.com/arangodb-managed/apis/iam/v1"
)
 
...
 
// Set up a connection to the API.
tc := credentials.NewTLS(&tls.Config{})
conn, err := grpc.Dial("https://api.cloud.arangodb.com",
  grpc.WithTransportCredentials(tc))
if err != nil {
  // handle error
}
 
// Create client for IAM service
iamc := iam.NewIAMServiceClient(conn)
 
// Call AuthenticateAPIKey to create token
resp, err := iamc.AuthenticateAPIKey(ctx,
  &iam.AuthenticateAPIKeyRequest{
  Id:     keyID,
  Secret: keySecret,
})
if err != nil {
  // handle error
}
token := resp.GetToken()

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

// Create client for Data service
datac := data.NewDataServiceClient(conn)
 
// Prepare context with authentication token
ctx := auth.WithAccessToken(context.Background(), token)
 
// Call list deployments
list, err := datac.ListDeployments(ctx,
  &common.ListOptions{ContextId: myProjectID})
if err != nil {
  // handle error
}
for _, depl := range list.GetItems() {
  fmt.Printf("Found deployment with id %s\n", depl.GetId())
}

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 ArangoGraph platform.

What about scripting?

The ArangoGraph 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 list deployments -o <organization> -p <project>

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

oasisctl --help

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:

oasisctl list nodesizes

See how to authenticate with ArangoGraph 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 ArangoGraph, 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 ArangoGraph API is at the heart of the ArangoGraph platform. As we add more features to ArangoGraph, 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 ArangoGraph and appreciate any feedback you have! If you made something cool with the ArangoGraph API, please let us know.

How can I get started?

If you are new to ArangoGraph, 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 ArangoGraph API Documentation for more details.

Hear More from the Author

Implementing data center to data center replication for a distributed database by Ewout Prangsma

Save time and do more cool stuff with ArangoDB ArangoGraph

Continue Reading

ArangoDB Easter Egg Hunt

Using the ArangoDB Swagger.io Interactive API Documentation

The ArangoDB Operator for Kubernetes – Stateful Cluster Deployments in 5min