GDB Public API

Overview

The GrapheneDB API is organized around REST. It has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. Tools such as cURL or httpie can be used to debug and develop on top of this API.

In the API spec section of the Support portal view, you can find general information on how the process works/looks and example requests for authentication and request data. Navigate to Help icon at the upper right corner > GDB API > API spec.

Which operations can I automate?

With GrapheneDB API, you can automate deployment related operations, some of them being Create a Database, Pause/Resume database, and schedule a Snapshot. Please note that with our API you can achieve all operations available to Operator Role.

Operator is a role that has access only to assigned Environments and management abilities for deployments within those Environments, which means it has access to the deployment endpoint only. Permissions include the following operations, among many others:

• Deploy database
• Pause/Resume database
• Restart database
• Clone database
• Import database
• Switch Connection URL
• Terminate database

There are many use cases for our API, some of them being:

• Pause non-production databases when not in use and save costs.
• Automate your disaster recovery plan.
• Restore your production data into your other environments periodically.

API root

Our Console API endpoint is: https://api.db.graphenedb.com/

API Reference

This API is organized around REST, which means that:

• Resources can be accessed in a stateless, predictable manner.
• Each resource is identified by a URL.
  • Entities are identified by a UUID
    • /databases/822b16bb0c0d4631ae30719cab74c352
  • Collections of entities can be obtained by not specifying a UUID:
    • deployments/databases/graphneo
  • Nested subresources are used:
    • deployments/databases/822b16bb0c0d4631ae30719cab74c352/restart
• The entities and collections handled by this API can be obtained using standard HTTP/1.1 methods.
  • POST creates a new entity.
  • GET reads an entity or collection.
  • PUT updates an entity or executes a command on it.
  • DELETE deletes an entity.
• Each method can return HTTP success or error responses, always following the guidelines of RFC 2616, but with an additional meaning to our API:
  • 200: Immediate, synchronous responses from GET, PUT.
  • 201: New entities created via POST.
  • 202: The new database details.
  • 204: Empty content from PUT, DELETE.
  • 400: Indicates that the request sent to the API was malformed, incomplete or failed validation. Check the API documentation to ensure that your request is valid before trying again.
  • 401: Indicates that authentication failed. Either credentials were not provided or the provided credentials are not valid.
  • 403: Indicates that the user has been identified, but is not allowed access to this resource.
  • 404: Indicates that a resource could not be found. Retrying the request later may successfully find the resource.
  • 500: There was a temporary server error while handling the request. Please try again later once it has been resolved.
• The standard encoding for all requests and responses is JSON.
• The accepted charset for all communications is UTF-8.
• All dates are expressed in compliance with RFC 7231.
  • Sun, 06 Nov 1994 08:49:37 GMT.

API Reference is available to you directly within the Console, simply navigate to Help icon at the upper right corner > GDB API > API spec. Then, please scroll down where you can expand the API reference view.

Authentication and security

The only way to access the API is through HTTPS. We’re using the machine-to-machine communications method, where the key aspect lies in the fact that the element to establish trust in the system is the client.

Authentication works in a way where, in the client credentials grant, the client holds two pieces of information: the Client ID and the Client secret. With this information, the client can request a JWT token for GrapheneDB API usage. The GrapheneDB API Client ID and Client secret you’ll receive when creating a client are required to request the JWT token needed for GrapheneDB management API authorization.

How to create API Client?

To create the API Client, please navigate to GrapheneDB Console > API Clients from the side menu > API Clients tab > and click on +New API Client button.

You’ll be prompted to the next screen, where you’ll need to choose a name for the API Client and Select access (choose the Environments the API client will have access to. Access can be changed after creation). You can select multiple environments and important to note is that Environment type (color) determines the privilege scope for API clients.

⚠️ Important

• Never expose API client key.
• Consume GrapheneDB API in protected environments.
• Environment type (color) determines the privilege scope for API clients.

How to obtain Access Token?

As we mentioned, authentication works in a way where, in the client credentials grant, the client holds two pieces of information: the Client ID and the Client secret. With this information, the client can request a JWT token for GrapheneDB API usage.

⚠️ Important

Token expires after 1 hour. Prepare your scripts to refresh the token periodically.

To obtain a token you will need to locate the Client ID and Client secret, and then run a command, or use Postman for example, to get the token. Please click on Confirm button to create the API Client.

Now, the modal window will show where you’ll see your Client secret, and you can easily copy it to save it. Please keep it safe. We won’t show it again.

If you have missed saving it for any reason, you can refresh the token to get a new secret.

Your Client ID will be shown in the Client ID column.

Now, you have everything you need to obtain a token. You need to run a GET to the following endpoint: https://api.db.graphenedb.com/organizations/oauth/token, and below you can find the curl request example.

curl https://api.db.graphenedb.com/organizations/oauth/token \
-d "client_secret"="SECRET" \
-d "client_id"="ID" \
-d "grant_type"="client_credentials"

ID = API client ID
SECRET= API client secret

If you’re using Postman, create a new Collection and go to the Authorization tab. Select 0Auth2.0 from the Type dropdown menu. Next, go to Configure New Token and select/add the needed info.

• Grant type: Client Credentials
• Access token URL: https://api.db.graphenedb.com/organizations/oauth/token
• Client ID: from Console API Clients view
• Client Secret: from Console API Clients view - if not saved, you can refresh the token to get a new one.
• Click on the Get New Access Token button.

Response Objects

Errors

4xx errors indicate that there is something wrong with the client’s request. For example, it indicates that the request sent to the API was malformed, incomplete, or failed validation. 5xx errors point to an unhandled failure in the server. The message returned by the server is:

{ "error": "string" }`

The value of the string points to the actual cause.

Catalogs

Versions

The example below will guide you through the steps needed to get the available database versions.

Step 1: Get Access token

curl https://api.db.graphenedb.com/organizations/oauth/token \
-d "client_secret"="SECRET" \
-d "client_id"="ID" \
-d "grant_type"="client_credentials" 

Step 2: Get the available database versions

curl https://api.db.graphenedb.com/deployments/versions \
-H "authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json"

Plans

The example below will guide you through the steps needed to get the available GrapheneDB plans.

Step 1: Get Access token

curl https://api.db.graphenedb.com/organizations/oauth/token \
-d "client_secret"="SECRET" \
-d "client_id"="ID" \
-d "grant_type"="client_credentials" 

Step 2: Get available GrapheneDB plans

curl https://api.db.graphenedb.com/deployments/plans \
-H "authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json"

Regions

The example below will guide you through the steps to get the supported EC2 regions.

Step 1: Get Access token

curl https://api.db.graphenedb.com/organizations/oauth/token \
-d "client_secret"="SECRET" \
-d "client_id"="ID" \
-d "grant_type"="client_credentials" 

Step 2: Get supported EC2 regions

curl https://api.db.graphenedb.com/deployments/regions \
-H "authorization: Bearer ACCESS_TOKEN" \
-H "content-type: application/json"

Operation (graphneo)

The same API endpoint can return a sync or async operation, depending on the database size and plan. The “operation” object represents an asynchronous operation.

Request Objects

Database (graphneo)

Database Import (graphneo)

API Request examples

To help you get started easily, we’ve prepared several API request examples of requests that you can use to automate operations such as Create a database, Restart a database, Clone a database, Pause and Resume a database, Disaster recovery and more.

Please follow this link to find the API request examples.