!CHAPTER Incompatible changes in ArangoDB 2.8

It is recommended to check the following list of incompatible changes **before**
upgrading to ArangoDB 2.8, and adjust any client programs if necessary.


!SECTION AQL

!SUBSECTION Keywords added

The following AQL keywords were added in ArangoDB 2.8:

* `GRAPH`
* `OUTBOUND`
* `INBOUND`
* `ANY`
* `ALL`

Usage of these keywords for collection names, variable names or attribute names
in AQL queries will not be possible without quoting. For example, the following
AQL query will still work as it uses a quoted collection name and a quoted
attribute name:

```
FOR doc IN `OUTBOUND`
  RETURN doc.`any`
```

!SUBSECTION Changed behavior

The AQL functions `NEAR` and `WITHIN` now have stricter validations
for their input parameters `limit`, `radius` and `distance`. They may now throw
exceptions when invalid parameters are passed that may have not led
to exceptions in previous versions.


!SUBSECTION Deadlock handling

Client applications should be prepared to handle error 29 (`deadlock detected`)
that ArangoDB may now throw when it detects a deadlock across multiple transactions.
When a client application receives error 29, it should retry the operation that
failed. 

The error can only occur for AQL queries or user transactions that involve 
more than a single collection.


!SUBSECTION Optimizer

The AQL execution node type `IndexRangeNode` was replaced with a new more capable
execution node type `IndexNode`. That means in execution plan explain output there
will be no more `IndexRangeNode`s but only `IndexNode`. This affects explain output
that can be retrieved via `require("org/arangodb/aql/explainer").explain(query)`,
`db._explain(query)`, and the HTTP query explain API.

The optimizer rule that makes AQL queries actually use indexes was also renamed
from `use-index-range` to `use-indexes`. Again this affects explain output
that can be retrieved via `require("org/arangodb/aql/explainer").explain(query)`,
`db._explain(query)`, and the HTTP query explain API.


!SECTION HTTP API

When a server-side operation got canceled due to an explicit client cancel request 
via HTTP `DELETE /_api/job`, previous versions of ArangoDB returned an HTTP status
code of 408 (request timeout) for the response of the canceled operation.

The HTTP return code 408 has caused problems with some client applications. Some 
browsers (e.g. Chrome) handled a 408 response by resending the original request, 
which is the opposite of what is desired when a job should be canceled.

Therefore ArangoDB will return HTTP status code 410 (gone) for canceled operations
from version 2.8 on.


!SECTION Foxx

!SUBSECTION Module resolution

The behaviour of the JavaScript module resolution used by the `require` function has
been modified to improve compatibility with modules written for Node.js.

Specifically

* absolute paths (e.g. `/some/absolute/path`) are now always interpreted as absolute
  file system paths, relative to the file system root

* global names (e.g. `global/name`) are now first intepreted as references to modules
  residing in a relevant `node_modules` folder, a built-in module or a matching
  document in the internal `_modules` collection, and only resolved to local file paths
  if no other match is found

Previously the two formats were treated interchangeably and would be resolved to local
file paths first, leading to problems when local files used the same names as other
modules (e.g. a local file `chai.js` would cause problems when trying to load the
`chai` module installed in `node_modules`).

For more information see the [blog announcement of this change](https://www.arangodb.com/2015/11/foxx-module-resolution-will-change-in-2-8/) and the [upgrade guide](./Upgrading28.md#upgrading-foxx-apps-generated-by-arangodb-27-and-earlier).

!SUBSECTION Module `org/arangodb/request`

The module now always returns response bodies, even for error responses. In versions
prior to 2.8 the module would silently drop response bodies if the response header
indicated an error.

The old behavior of not returning bodies for error responses can be restored by
explicitly setting the option `returnBodyOnError` to `false`:

```js
let response = request({
  //...
  returnBodyOnError: false
});
```


!SUBSECTION Controllers

* the method `del` of Foxx controllers is deprecated, it will raise a warning if you use 
  it. Please use the `delete` method instead.

* the method `addInjector` of controllers is deprecated, it will raise a warning if you use it. 
  Please use regular variables instead.

* the property `assets` in manifests has been removed entirely. Please use the `files` 
  property and an external build tool instead.

* properties `setup` and `teardown` in manifests have been removed entirely. Please use the 
  `scripts` property instead.

* the built-in support for CoffeeScript source files is deprecated, it will raise a warning 
  if you use it. Please pre-compile CoffeeScript source files.


!SECTION Client tools

arangodump will now fail by default when trying to dump edges that
refer to already dropped collections. This can be circumvented by 
specifying the option `--force true` when invoking arangodump