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

ArangoDB's Foxx operations.

Every function takes the pool as its first argument and returns the decoded
response body. See `Arangox.API.Client` for the options they all accept and
for what a `404` returns.

# `all`

```elixir
@spec all(
  Arangox.conn(),
  keyword()
) :: {:ok, term()} | {:error, Exception.t()}
```

List the installed services

Fetches a list of services installed in the current database.

Returns a list of objects with the following attributes:

- `mount`: the mount path of the service
- `development`: `true` if the service is running in development mode
- `legacy`: `true` if the service is running in 2.8 legacy compatibility mode
- `provides`: the service manifest's `provides` value or an empty object

Additionally the object may contain the following attributes if they have been set on the manifest:

- `name`: a string identifying the service type
- `version`: a semver-compatible version string

## Returns

Recorded against ArangoDB 3.12.10:

    [%{
      "development" => boolean,
      "legacy" => boolean,
      "mount" => string,
      "name" => string,
      "provides" => %{},
      "version" => string
    }]

# `all!`

```elixir
@spec all!(
  Arangox.conn(),
  keyword()
) :: term()
```

List the installed services. Raises on error.

See `all/1`.

# `all_scripts`

```elixir
@spec all_scripts(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

List the service scripts

Fetches a list of the scripts defined by the service.

Returns an object mapping the raw script names to human-friendly names.

# `all_scripts!`

```elixir
@spec all_scripts!(Arangox.conn(), binary(), keyword()) :: term()
```

List the service scripts. Raises on error.

See `all_scripts/2`.

# `commit_state`

```elixir
@spec commit_state(
  Arangox.conn(),
  keyword()
) :: {:ok, term()} | {:error, Exception.t()}
```

Commit the local service state

Commits the local service state of the Coordinator to the database.

This can be used to resolve service conflicts between Coordinators that cannot be fixed automatically due to missing data.

# `commit_state!`

```elixir
@spec commit_state!(
  Arangox.conn(),
  keyword()
) :: term()
```

Commit the local service state. Raises on error.

See `commit_state/1`.

# `configuration`

```elixir
@spec configuration(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Get the configuration options

Fetches the current configuration for the service at the given mount path.

Returns an object mapping the configuration option names to their definitions
including a human-friendly `title` and the `current` value (if any).

# `configuration!`

```elixir
@spec configuration!(Arangox.conn(), binary(), keyword()) :: term()
```

Get the configuration options. Raises on error.

See `configuration/2`.

# `create`

```elixir
@spec create(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Install a new service

Installs the given new service at the given mount path.

The request body can be any of the following formats:

- `application/zip`: a raw zip bundle containing a service
- `application/javascript`: a standalone JavaScript file
- `application/json`: a service definition as JSON
- `multipart/form-data`: a service definition as a multipart form

A service definition is an object or form with the following properties or fields:

- `configuration`: a JSON object describing configuration values
- `dependencies`: a JSON object describing dependency settings
- `source`: a fully qualified URL or an absolute path on the server's file system

When using multipart data, the `source` field can also alternatively be a file field
containing either a zip bundle or a standalone JavaScript file.

When using a standalone JavaScript file the given file will be executed
to define our service's HTTP endpoints. It is the same which would be defined
in the field `main` of the service manifest.

If `source` is a URL, the URL must be reachable from the server.
If `source` is a file system path, the path will be resolved on the server.
In either case the path or URL is expected to resolve to a zip bundle,
JavaScript file or (in case of a file system path) directory.

Note that when using file system paths in a cluster with multiple Coordinators
the file system path must resolve to equivalent files on every Coordinator.

# `create!`

```elixir
@spec create!(Arangox.conn(), binary(), keyword()) :: term()
```

Install a new service. Raises on error.

See `create/2`.

# `delete`

```elixir
@spec delete(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Uninstall a service

Removes the service at the given mount path from the database and file system.

Returns an empty response on success.

# `delete!`

```elixir
@spec delete!(Arangox.conn(), binary(), keyword()) :: term()
```

Uninstall a service. Raises on error.

See `delete/2`.

# `dependencies`

```elixir
@spec dependencies(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Get the dependency options

Fetches the current dependencies for service at the given mount path.

Returns an object mapping the dependency names to their definitions
including a human-friendly `title` and the `current` mount path (if any).

# `dependencies!`

```elixir
@spec dependencies!(Arangox.conn(), binary(), keyword()) :: term()
```

Get the dependency options. Raises on error.

See `dependencies/2`.

# `description`

```elixir
@spec description(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Get the service description

Fetches detailed information for the service at the given mount path.

Returns an object with the following attributes:

- `mount`: the mount path of the service
- `path`: the local file system path of the service
- `development`: `true` if the service is running in development mode
- `legacy`: `true` if the service is running in 2.8 legacy compatibility mode
- `manifest`: the normalized JSON manifest of the service

Additionally the object may contain the following attributes if they have been set on the manifest:

- `name`: a string identifying the service type
- `version`: a semver-compatible version string

# `description!`

```elixir
@spec description!(Arangox.conn(), binary(), keyword()) :: term()
```

Get the service description. Raises on error.

See `description/2`.

# `disable_development_mode`

```elixir
@spec disable_development_mode(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Disable the development mode

Puts the service at the given mount path into production mode.

When running ArangoDB in a cluster with multiple Coordinators this will
replace the service on all other Coordinators with the version on this
Coordinator.

# `disable_development_mode!`

```elixir
@spec disable_development_mode!(Arangox.conn(), binary(), keyword()) :: term()
```

Disable the development mode. Raises on error.

See `disable_development_mode/2`.

# `download`

```elixir
@spec download(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Download a service bundle

Downloads a zip bundle of the service directory.

When development mode is enabled, this always creates a new bundle.

Otherwise the bundle will represent the version of a service that
is installed on that ArangoDB instance.

# `download!`

```elixir
@spec download!(Arangox.conn(), binary(), keyword()) :: term()
```

Download a service bundle. Raises on error.

See `download/2`.

# `enable_development_mode`

```elixir
@spec enable_development_mode(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Enable the development mode

Puts the service into development mode.

While the service is running in development mode the service will be reloaded
from the filesystem and its setup script (if any) will be re-executed every
time the service handles a request.

When running ArangoDB in a cluster with multiple Coordinators note that changes
to the filesystem on one Coordinator will not be reflected across the other
Coordinators. This means you should treat your Coordinators as inconsistent
as long as any service is running in development mode.

# `enable_development_mode!`

```elixir
@spec enable_development_mode!(Arangox.conn(), binary(), keyword()) :: term()
```

Enable the development mode. Raises on error.

See `enable_development_mode/2`.

# `readme`

```elixir
@spec readme(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Get the service README

Fetches the service's README or README.md file's contents if any.

# `readme!`

```elixir
@spec readme!(Arangox.conn(), binary(), keyword()) :: term()
```

Get the service README. Raises on error.

See `readme/2`.

# `replace`

```elixir
@spec replace(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Replace a service

Removes the service at the given mount path from the database and file system.
Then installs the given new service at the same mount path.

This is a slightly safer equivalent to performing an uninstall of the old service
followed by installing the new service. The new service's main and script files
(if any) will be checked for basic syntax errors before the old service is removed.

The request body can be any of the following formats:

- `application/zip`: a raw zip bundle containing a service
- `application/javascript`: a standalone JavaScript file
- `application/json`: a service definition as JSON
- `multipart/form-data`: a service definition as a multipart form

A service definition is an object or form with the following properties or fields:

- `configuration`: a JSON object describing configuration values
- `dependencies`: a JSON object describing dependency settings
- `source`: a fully qualified URL or an absolute path on the server's file system

When using multipart data, the `source` field can also alternatively be a file field
containing either a zip bundle or a standalone JavaScript file.

When using a standalone JavaScript file the given file will be executed
to define our service's HTTP endpoints. It is the same which would be defined
in the field `main` of the service manifest.

If `source` is a URL, the URL must be reachable from the server.
If `source` is a file system path, the path will be resolved on the server.
In either case the path or URL is expected to resolve to a zip bundle,
JavaScript file or (in case of a file system path) directory.

Note that when using file system paths in a cluster with multiple Coordinators
the file system path must resolve to equivalent files on every Coordinator.

# `replace!`

```elixir
@spec replace!(Arangox.conn(), binary(), keyword()) :: term()
```

Replace a service. Raises on error.

See `replace/2`.

# `replace_configuration`

```elixir
@spec replace_configuration(Arangox.conn(), binary(), term(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Replace the configuration options

Replaces the given service's configuration completely.

Returns an object mapping all configuration option names to their new values.

# `replace_configuration!`

```elixir
@spec replace_configuration!(Arangox.conn(), binary(), term(), keyword()) :: term()
```

Replace the configuration options. Raises on error.

See `replace_configuration/3`.

# `replace_dependencies`

```elixir
@spec replace_dependencies(Arangox.conn(), binary(), term(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Replace the dependency options

Replaces the given service's dependencies completely.

Returns an object mapping all dependency names to their new mount paths.

# `replace_dependencies!`

```elixir
@spec replace_dependencies!(Arangox.conn(), binary(), term(), keyword()) :: term()
```

Replace the dependency options. Raises on error.

See `replace_dependencies/3`.

# `run_script`

```elixir
@spec run_script(Arangox.conn(), binary(), binary(), term(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Run a service script

Runs the given script for the service at the given mount path.

Returns the exports of the script, if any.

# `run_script!`

```elixir
@spec run_script!(Arangox.conn(), binary(), binary(), term(), keyword()) :: term()
```

Run a service script. Raises on error.

See `run_script/4`.

# `run_tests`

```elixir
@spec run_tests(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Run the service tests

Runs the tests for the service at the given mount path and returns the results.

Supported test reporters are:

- `default`: a simple list of test cases
- `suite`: an object of test cases nested in suites
- `stream`: a raw stream of test results
- `xunit`: an XUnit/JUnit compatible structure
- `tap`: a raw TAP compatible stream

The `Accept` request header can be used to further control the response format:

When using the `stream` reporter `application/x-ldjson` will result
in the response body being formatted as a newline-delimited JSON stream.

When using the `tap` reporter `text/plain` or `text/*` will result
in the response body being formatted as a plain text TAP report.

When using the `xunit` reporter `application/xml` or `text/xml` will result
in the response body being formatted as XML instead of JSONML.

Otherwise the response body will be formatted as non-prettyprinted JSON.

# `run_tests!`

```elixir
@spec run_tests!(Arangox.conn(), binary(), keyword()) :: term()
```

Run the service tests. Raises on error.

See `run_tests/2`.

# `swagger_description`

```elixir
@spec swagger_description(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Get the Swagger description

Fetches the Swagger API description for the service at the given mount path.

The response body will be an OpenAPI 2.0 compatible JSON description of the service API.

# `swagger_description!`

```elixir
@spec swagger_description!(Arangox.conn(), binary(), keyword()) :: term()
```

Get the Swagger description. Raises on error.

See `swagger_description/2`.

# `update_configuration`

```elixir
@spec update_configuration(Arangox.conn(), binary(), term(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Update the configuration options

Replaces the given service's configuration partially.

Returns an object mapping all configuration option names to their new values.

# `update_configuration!`

```elixir
@spec update_configuration!(Arangox.conn(), binary(), term(), keyword()) :: term()
```

Update the configuration options. Raises on error.

See `update_configuration/3`.

# `update_dependencies`

```elixir
@spec update_dependencies(Arangox.conn(), binary(), term(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Update the dependency options

Replaces the given service's dependencies.

Returns an object mapping all dependency names to their new mount paths.

# `update_dependencies!`

```elixir
@spec update_dependencies!(Arangox.conn(), binary(), term(), keyword()) :: term()
```

Update the dependency options. Raises on error.

See `update_dependencies/3`.

# `upgrade`

```elixir
@spec upgrade(Arangox.conn(), binary(), keyword()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Upgrade a service

Installs the given new service on top of the service currently installed at the given mount path.
This is only recommended for switching between different versions of the same service.

Unlike replacing a service, upgrading a service retains the old service's configuration
and dependencies (if any) and should therefore only be used to migrate an existing service
to a newer or equivalent service.

The request body can be any of the following formats:

- `application/zip`: a raw zip bundle containing a service
- `application/javascript`: a standalone JavaScript file
- `application/json`: a service definition as JSON
- `multipart/form-data`: a service definition as a multipart form

A service definition is an object or form with the following properties or fields:

- `configuration`: a JSON object describing configuration values
- `dependencies`: a JSON object describing dependency settings
- `source`: a fully qualified URL or an absolute path on the server's file system

When using multipart data, the `source` field can also alternatively be a file field
containing either a zip bundle or a standalone JavaScript file.

When using a standalone JavaScript file the given file will be executed
to define our service's HTTP endpoints. It is the same which would be defined
in the field `main` of the service manifest.

If `source` is a URL, the URL must be reachable from the server.
If `source` is a file system path, the path will be resolved on the server.
In either case the path or URL is expected to resolve to a zip bundle,
JavaScript file or (in case of a file system path) directory.

Note that when using file system paths in a cluster with multiple Coordinators
the file system path must resolve to equivalent files on every Coordinator.

# `upgrade!`

```elixir
@spec upgrade!(Arangox.conn(), binary(), keyword()) :: term()
```

Upgrade a service. Raises on error.

See `upgrade/2`.

---

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