# `Arangox.API.Client`
[🔗](https://github.com/ArangoDB-Community/arangox/blob/v0.8.0/lib/arangox/api/client.ex#L1)

The adapter every `Arangox.API.*` operation calls.

An operation names a method, a list of path segments, and the query
parameters it accepts. This module turns that into a driver request, so the
pool, timeout budget, transaction handling and error contract apply to
`Arangox.API` calls exactly as they do to hand-written ones. It holds no
connection state and opens no socket: a transport change touches this
module, never the operations above it.

## Options every operation accepts

  * `:database` - the database to run a database-scoped operation against.
    Falls back to the pool's own `:database`, and then to `_system`.
    Server-global operations ignore it and never receive a `/_db/` prefix.
  * `:headers` - extra request headers as `{name, value}` tuples, for the
    header parameters an operation does not expose (`if-match`, and so on).
  * any query parameter the operation declares, written in snake_case
  * every per-request option `Arangox.request/6` accepts, such as
    `:transaction`, `:timeout` and `:request_timeout`

## What comes back

A successful call returns `{:ok, body}` — the decoded response body, not a
response struct. A success that carries no body (`204 No Content`) returns
`{:ok, nil}`.

Any error status returns `{:error, %Arangox.Error{}}`, carrying the HTTP
status and ArangoDB's own `errorNum`. A `404` is an error like any other:
ask for a document that is not there and you get
`{:error, %Arangox.Error{status: 404}}`.

The `!` form of each operation returns the body directly and raises on any
error.

## Bounds

Every value a caller can influence is bounded here, because every
`Arangox.API` call passes through:

  * path segments are percent-encoded one segment at a time, so a value
    carrying `/` or `?` becomes part of that segment instead of altering the
    path. A control character is refused outright — it is never a legitimate
    part of a name.
  * a few parameters are themselves paths — an index identifier is
    `collection/number` — and are declared as such by the operation. Their
    separators survive; everything between them is still encoded, so such a
    value can add path depth but cannot introduce a query or a fragment.
  * query and header names and values must not carry carriage return, line
    feed, or null.
  * an `authorization` or `host` header is refused: the pool's endpoint and
    credentials are not an operation's to override.
  * a refusal names the field and the rule, never the value, because a
    rejected header or path segment may be a credential or a transaction
    identifier.

---

*Consult [api-reference.md](api-reference.md) for complete listing*