ArangoDB 2.6 API Changes: Updates & Enhancements

ArangoDB 2.6 comes with new and changed APIs as well as changed behavior regarding document keys and several graph functions.

If you use Travis-CI for your tests you can download the Travis-CI ArangoDB build here: Travis-CI/ArangoDB-2.6.0-alpha2.tar.gz

The changes so far:

APIs added

• added batch document removal and lookup APIs:

  These APIs can be used to perform multi-document lookup and removal operations efficiently. The arguments to these APIs are the name of the collection plus the array of document keys to fetch or remove.

  The endpoints for these APIs are as follows:

  PUT /_api/simple/lookup-by-keys
  PUT /_api/simple/remove-by-keys
  

  Example call to fetch documents:

  curl -X PUT \ http://127.0.0.1:8529/\_db/\_system/_api/simple/lookup-by-keys \ --data '{"collection":"myCollection","keys":["test1","test3"]}'
  

  The documents will be returned in an attribute documents of the HTTP response. documents is an array containing all documents found. Only those documents that were actually found will be returned. Documents that were searched but do not exist will not be returned and do not trigger any errors.

  Example call to remove documents:

  curl -X PUT \ http://127.0.0.1:8529/\_db/\_system/_api/simple/remove-by-keys \ --data '{"collection":"myCollection","keys":["test1","test3"]}'
  

  The number of documents removed will be returned in the removed attribute of the response. The number of documents not removed (because they did not exist) will be returned in the ignored attribute of the response.

• added dedicated collection export HTTP REST API

  ArangoDB now provides a dedicated collection export API, which can take snapshots of entire collections more efficiently than the general-purpose cursor API. The export API is useful to transfer the contents of an entire collection to a client application. It provides optional filtering on specific attributes.

  The export API is available at endpoint POST /_api/export?collection=.... The API has the same return value structure as the already established cursor API (POST /_api/cursor).

  The API is described here: https://docs.arangodb.com/2.6/HttpExport/index.html

  An introduction to the export API is given in this blog post: http://jsteemann.github.io/blog/2015/04/04/more-efficient-data-exports/

APIs changed

• Document address URLs are now prefixed with the current database name for calls to the REST API method GET /_api/document?collection=... (that method will return partial URLs to all documents in the collection).

  Previous versions of ArangoDB returned the URLs starting with /_api/ but without the current database name, e.g. /_api/document/mycollection/mykey. Starting with 2.6, the response URLs will include the database name as well, e.g. /_db/_system/_api/document/mycollection/mykey.

• Disallow batchSize value 0 in HTTP REST API POST /_api/cursor:

  The HTTP REST API POST /_api/cursor does not accept a batchSize parameter value of 0 any longer. A batch size of 0 newer made much sense, but previous versions of ArangoDB did not check for this value. Now creating a cursor using a batchSize value 0 will result in an HTTP 400 error response

Changed behavior

• allow @ and . characters in document keys, too

  Previous versions of ArangoDB did not allow the @ in document keys so document keys only contained characters which needn’t be URL-encoded.

  Now document keys may contain characters that may need URL-encoding and client applications may need to take this into account when assembling URLs that contain document keys.

  Additionally, document keys returned in the location` HTTP response header from an ArangoDB server may now be URL-encoded and client applications may need to URL-decode them to get the proper document key.

• Create the _graphs collection in new databases with waitForSync attribute set to false

  The previous waitForSync value was true, so default the behavior when creating and dropping graphs via the HTTP REST API changes as follows if the new settings are in effect:

  `POST /_api/graph` by default now returns `HTTP 202` instead of `HTTP 201`
  `DELETE /_api/graph/graph-name` by default now returns `HTTP 202` instead of `HTTP 201`
  

  If the _graphs collection still has its waitForSync value set to true, then the HTTP status codes will not change.

• GRAPH_SHORTEST_PATH return value change

  The AQL function GRAPH_SHORTEST_PATH now provides an additional option includeData. This option allows controlling whether the function should return the complete vertices and edges or just their IDs. Returning only the IDs instead of full vertices and edges can lead to improved performance .

  If provided, includeData is set to true, all vertices and edges in the result will be fully expanded. There is also an optional parameter includePath of type object. It has two optional sub-attributes vertices and edges, both of type boolean. Both can be set individually and the result will include all vertices on the path if includePath.vertices == true and all edges if includePath.edges == true respectively.

  The default value of includeData is false, and paths are now excluded by default. This makes the default function results incompatible with previous versions of ArangoDB.

  To get the old result style in ArangoDB 2.6, please set the options as follows in calls to GRAPH_SHORTEST_PATH:

  GRAPH_SHORTEST_PATH(<graph>, <source>, <target>, { includeData: true, includePath: { edges: true, vertices: true } })
  

• Graph measurements functions return value change

  All graph measurements functions in JavaScript module general-graph that calculated a single figure previously returned an array containing just the figure. Now these functions will return the figure directly and not put it inside an array.

  The affected functions are:

  • graph._absoluteEccentricity
  • graph._eccentricity
  • graph._absoluteCloseness
  • graph._closeness
  • graph._absoluteBetweenness
  • graph._betweenness
  • graph._radius
  • graph._diameter