Foxx Service Management

This is an introduction to ArangoDB's HTTP interface for managing Foxx services.

List installed services

list installed services

GET /_api/foxx

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

Return Codes

  • 200: Returned if the request was successful.

Service description

service metadata

GET /_api/foxx/service

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

Query Parameters

  • mount (required): Mount path of the installed service.

Return Codes

  • 200: Returned if the request was successful.
  • 400: Returned if the mount path is unknown.

Install new service

install new service

POST /_api/foxx

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.

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.

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.

Query Parameters

  • mount (required): Mount path the service should be installed at.
  • development (optional): Set to true to enable development mode.
  • setup (optional): Set to false to not run the service's setup script.
  • legacy (optional): Set to true to install the service in 2.8 legacy compatibility mode.

Return Codes

  • 201: Returned if the request was successful.

Uninstall service

uninstall service

DELETE /_api/foxx/service

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

Returns an empty response on success.

Query Parameters

  • mount (required): Mount path of the installed service.
  • teardown (optional): Set to false to not run the service's teardown script.

Return Codes

  • 204: Returned if the request was successful.

Replace service

replace a service

PUT /_api/foxx/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.

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.

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.

Query Parameters

  • mount (required): Mount path of the installed service.
  • teardown (optional): Set to false to not run the old service's teardown script.
  • setup (optional): Set to false to not run the new service's setup script.
  • legacy (optional): Set to true to install the new service in 2.8 legacy compatibility mode.

Return Codes

  • 200: Returned if the request was successful.

Upgrade service

upgrade a service

PATCH /_api/foxx/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.

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.

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.

Query Parameters

  • mount (required): Mount path of the installed service.
  • teardown (optional): Set to true to run the old service's teardown script.
  • setup (optional): Set to false to not run the new service's setup script.
  • legacy (optional): Set to true to install the new service in 2.8 legacy compatibility mode.

Return Codes

  • 200: Returned if the request was successful.

© ArangoDB - the native multi-model NoSQL database