ArangoDB v3.12 is under development and not released yet. This documentation is not final and potentially incomplete.

HTTP interface for Foxx

The HTTP API for Foxx allows you to manipulate Foxx microservices installed in a database

For more information on Foxx and its JavaScript APIs see the Foxx documentation.

Management

List the 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
Path Parameters
    Query Parameters
    • Whether or not system services should be excluded from the result.

    HTTP Headers
      Responses
      • Returned if the request was successful.

      Get the service description

      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
      Path Parameters
        Query Parameters
        • Mount path of the installed service.

        HTTP Headers
          Responses
          • Returned if the request was successful.

          • Returned if the mount path is unknown.

          Install a 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.

          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.

          Path Parameters
            Query Parameters
            • Mount path the service should be installed at.

            • Set to true to enable development mode.

            • Set to false to not run the service’s setup script.

            • Set to true to install the service in 2.8 legacy compatibility mode.

            HTTP Headers
              Responses
              • Returned if the request was successful.

              Uninstall a 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.

              Path Parameters
                Query Parameters
                • Mount path of the installed service.

                • Set to false to not run the service’s teardown script.

                HTTP Headers
                  Responses
                  • Returned if the request was successful.

                  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.

                  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.

                  Path Parameters
                    Query Parameters
                    • Mount path of the installed service.

                    • Set to false to not run the old service’s teardown script.

                    • Set to false to not run the new service’s setup script.

                    • Set to true to install the new service in 2.8 legacy compatibility mode.

                    • Set to true to force service install even if no service is installed under given mount.

                    HTTP Headers
                      Responses
                      • Returned if the request was successful.

                      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.

                      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.

                      Path Parameters
                        Query Parameters
                        • Mount path of the installed service.

                        • Set to true to run the old service’s teardown script.

                        • Set to false to not run the new service’s setup script.

                        • Set to true to install the new service in 2.8 legacy compatibility mode.

                        • Set to true to force service install even if no service is installed under given mount.

                        HTTP Headers
                          Responses
                          • Returned if the request was successful.

                          Configuration

                          Get the configuration options

                          get /_api/foxx/configuration

                          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).

                          Path Parameters
                            Query Parameters
                            • Mount path of the installed service.

                            HTTP Headers
                              Responses
                              • Returned if the request was successful.

                              Update the configuration options

                              patch /_api/foxx/configuration

                              Replaces the given service’s configuration.

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

                              Path Parameters
                                Query Parameters
                                • Mount path of the installed service.

                                HTTP Headers
                                  Request Body application/json
                                  • A JSON object mapping configuration option names to their new values. Any omitted options will be ignored.

                                  Responses
                                  • Returned if the request was successful.

                                  Replace the configuration options

                                  put /_api/foxx/configuration

                                  Replaces the given service’s configuration completely.

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

                                  Path Parameters
                                    Query Parameters
                                    • Mount path of the installed service.

                                    HTTP Headers
                                      Request Body application/json
                                      • A JSON object mapping configuration option names to their new values. Any omitted options will be reset to their default values or marked as unconfigured.

                                      Responses
                                      • Returned if the request was successful.

                                      Get the dependency options

                                      get /_api/foxx/dependencies

                                      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).

                                      Path Parameters
                                        Query Parameters
                                        • Mount path of the installed service.

                                        HTTP Headers
                                          Responses
                                          • Returned if the request was successful.

                                          Update the dependency options

                                          patch /_api/foxx/dependencies

                                          Replaces the given service’s dependencies.

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

                                          Path Parameters
                                            Query Parameters
                                            • Mount path of the installed service.

                                            HTTP Headers
                                              Request Body application/json
                                              • A JSON object mapping dependency names to their new mount paths. Any omitted dependencies will be ignored.

                                              Responses
                                              • Returned if the request was successful.

                                              Replace the dependency options

                                              put /_api/foxx/dependencies

                                              Replaces the given service’s dependencies completely.

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

                                              Path Parameters
                                                Query Parameters
                                                • Mount path of the installed service.

                                                HTTP Headers
                                                  Request Body application/json
                                                  • A JSON object mapping dependency names to their new mount paths. Any omitted dependencies will be disabled.

                                                  Responses
                                                  • Returned if the request was successful.

                                                  Miscellaneous

                                                  List the service scripts

                                                  get /_api/foxx/scripts

                                                  Fetches a list of the scripts defined by the service.

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

                                                  Path Parameters
                                                    Query Parameters
                                                    • Mount path of the installed service.

                                                    HTTP Headers
                                                      Responses
                                                      • Returned if the request was successful.

                                                      Run a service script

                                                      post /_api/foxx/scripts/{name}

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

                                                      Returns the exports of the script, if any.

                                                      Path Parameters
                                                      • Name of the script to run.

                                                      Query Parameters
                                                      • Mount path of the installed service.

                                                      HTTP Headers
                                                        Request Body application/json
                                                        • An arbitrary JSON value that will be parsed and passed to the script as its first argument.

                                                        Responses
                                                        • Returned if the request was successful.

                                                        Run the service tests

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

                                                        Path Parameters
                                                          Query Parameters
                                                          • Mount path of the installed service.

                                                          • Test reporter to use.

                                                          • Use the matching format for the reporter, regardless of the Accept header.

                                                          • Only run tests where the full name (including full test suites and test case) matches this string.

                                                          HTTP Headers
                                                            Responses
                                                            • Returned if the request was successful.

                                                            Enable the development mode

                                                            post /_api/foxx/development

                                                            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.

                                                            Path Parameters
                                                              Query Parameters
                                                              • Mount path of the installed service.

                                                              HTTP Headers
                                                                Responses
                                                                • Returned if the request was successful.

                                                                Disable the development mode

                                                                delete /_api/foxx/development

                                                                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.

                                                                Path Parameters
                                                                  Query Parameters
                                                                  • Mount path of the installed service.

                                                                  HTTP Headers
                                                                    Responses
                                                                    • Returned if the request was successful.

                                                                    Get the service README

                                                                    get /_api/foxx/readme
                                                                    Fetches the service’s README or README.md file’s contents if any.
                                                                    Path Parameters
                                                                      Query Parameters
                                                                      • Mount path of the installed service.

                                                                      HTTP Headers
                                                                        Responses
                                                                        • Returned if the request was successful.

                                                                        • Returned if no README file was found.

                                                                        Get the Swagger description

                                                                        get /_api/foxx/swagger

                                                                        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.

                                                                        Path Parameters
                                                                          Query Parameters
                                                                          • Mount path of the installed service.

                                                                          HTTP Headers
                                                                            Responses
                                                                            • Returned if the request was successful.

                                                                            Download a service bundle

                                                                            post /_api/foxx/download

                                                                            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.

                                                                            Path Parameters
                                                                              Query Parameters
                                                                              • Mount path of the installed service.

                                                                              HTTP Headers
                                                                                Responses
                                                                                • Returned if the request was successful.

                                                                                • Returned if the mount path is unknown.

                                                                                Commit the local service state

                                                                                post /_api/foxx/commit

                                                                                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.

                                                                                Path Parameters
                                                                                  Query Parameters
                                                                                  • Overwrite existing service files in database even if they already exist.

                                                                                  HTTP Headers
                                                                                    Responses
                                                                                    • Returned if the request was successful.