ArangoDB 1.2 API Changes: What You Need to Know | 2013

Apart from introducing several new features, the upcoming 1.2 version of ArangoDB will change a few of the existing REST API return values.
The API changes were necessary to make the ArangoDB’s APIs easier to use, more robust and portable.

We hope that the following list provides 3rd party client & driver maintainers with enough information to update drivers to work with ArangoDB 1.2.

The following changes to existing APIs have been introduced in ArangoDB 1.2:

Changed format for document handles (“_id” attribute)

ArangoDB 1.2 uses a modified format for the value returned in the “_id” attribute of a document.

While ArangoDB 1.1 and earlier generated the “_id” value as a combination of server-generated collection id and document id, ArangoDB 1.2 will return a combination of collection name and user-defined document key.

A document returned by ArangoDB 1.1 and earlier looked like this (with “1234” being the collection id, and “6789” being the document id):

{ "_id" : "1234/6789", ... }

In ArangoDB 1.2, the same document will look like this (provided the name of the
collection is “mycollection”):

{ "_id" : "mycollection/6789", ... }

In ArangoDB 1.2, it is possible for users to define their own value for the “_key” attribute of a
document upon document creation. In case the document was created with a “_key” value of “mytest”:

{ "_id" : "mycollection/mytest", ... }

This change in the API is relevant for strictly-typed clients, but it might also matter for clients written in loosely-typed languages. The reason is that using the collection name instead of collection ids might save some HTTP calls for collection id-to-collection name translations that were still required in ArangoDB 1.1.

“_key” attribute returned for documents

In ArangoDB 1.2, all documents returned by the server will have an extra “_key” attribute. This attribute was not present in ArangoDB 1.1. The value of the “_key” attribute is a unique string (unique only in the context of the collection the document is contained in).

The value for “_key” is a server-generated value, or a user-generated value if the user provides “_key” values on document creation. There are some restrictions for “_key” values, which are detailed here.

Document revision id (“_rev” attribute) returned as string

Document revision ids created and returned by ArangoDB 1.2 are now returned as strings with the numeric revision id value inside.

ArangoDB 1.0 and ArangoDB 1.1 returned revision ids as simple numeric values without encapsulating them in a string. The revision id is part of every document stored in ArangoDB and is returned by ArangoDB in the “_rev” attribute.

In ArangoDB 1.1, this looked as follows:

{ "_rev": 1234, ... }

In ArangoDB 1.2, the “_rev” value will be returned as follows:

{ "_rev": "1234", ... }

(with the quotes being the relevant change). This change might not even matter for loosely typed clients and drivers, but for strictly-typed clients, the type of the revision variable needs to be changed from a number to a string.

Collection id returned as string

The same change as for the document revision ids has been carried out for collection ids in ArangoDB 1.2, when collection data is accessed in the /_api/collection APIs.

Thus a collection object returned by ArangoDB 1.2 looks like this:

{ "id": "9327643", "name": "test", ... }

where it looked like this in ArangoDB 1.1:

{ "id": 9327643, "name": "test", ... }

(again, the relevant difference are the quotes around the “id” value).

Cursor id returned as string

In line with the previous changes, cursor ids returned by ArangoDB 1.2 via the /_api/cursor and /_api/query APIs are also returned as numeric values encapsulated inside strings. They have been returned as simple integers numbers in ArangoDB 1.1 and before.

A cursor object returned by ArangoDB 1.2 looks like this:

{ "id": "11734292", "hasMore": true, ... }

and has looked like this before:

{ "id": 11734292, "hasMore": true, ... }

Index id returned as string

Finally, the number-to-string change has also been carried out for index ids. Index ids in ArangoDB 1.2 are also returned as numeric values encapsulated in strings.

Additional return attributes

A few REST API methods in the /_api/collection domain return additional attributes in ArangoDB 1.2:

• GET /_api/collection/…/figures returns an extra attribute “shapes”
• GET /_api/collection/…/figures returns an extra attribute “isVolatile”
• GET /_api/collection/…/properties returns an extra attribute “isVolatile”
• GET /_api/collection/…/count returns an extra attribute “isVolatile”

 Changed error return codes

When an unknown collection was used in an AQL query, ArangoDB 1.1 and before returned the error code 1520 (“Unable to open collection”).

ArangoDB 1.2 will instead return the standard error code “1203” (“Collection not found”),
which is also returned by other parts of ArangoDB in case a non-existing collection is used accessed.

New features

Additionally, ArangoDB 1.2 introduces extra REST APIs for new features.

There is an API to work with graphs available under /_api/graph. It provides several methods to manage graphs, vertices, and edges. More documentation on this is available here.

There are some APIs to create fulltext indexes and to query them. The details are here.

A new “remove-by-example” query API has been added. The details are here.

For more details on any of the above changes or a detailed description of the ArangoDB 1.2 REST APIs, please refer to the online documentation.

If any of the changes should be unclear and needs more clarification, please don’t hesitate to contact us.