arangodb/Documentation/ImplementorManual/Communication.md

HTTP Handling in ArangoDB

@NAVIGATE_Communication @EMBEDTOC{CommunicationTOC}

ArangoDB will always respond to client requests with HTTP 1.1. Clients should therefore support HTTP version 1.1.

Keep-Alive and Authentication

ArangoDB supports HTTP keep-alive. If the client does not send a Connection header in its request, and the client uses HTTP version 1.1, ArangoDB will assume the client wants to keep alive the connection. If clients do not wish to use the keep-alive feature, they should explicitly indicate that by sending a Connection: Close HTTP header in the request.

ArangoDB will close connections automatically for clients that send requests using HTTP 1.0, except if they send an Connection: Keep-Alive header.

The default Keep-Alive timeout can be specified at server start using the \-\-server.keep\-alive\-timeout parameter.

Client authentication is done by using the Authorization HTTP header. ArangoDB supports Basic authentication.

Authentication is optional. To enforce authentication for incoming requested, the server must be started with the option \-\-server.disable-authentication. Please note that requests using the HTTP OPTIONS method will be answered by ArangoDB in any case, even if no authentication data is sent by the client or if the authentication data is wrong. This is required for handling CORS preflight requests (see @ref CommunicationCors). The response to an HTTP OPTIONS request will be generic and not expose any private data.

Error Handling

The following should be noted about how ArangoDB handles client errors in its HTTP layer:

• ArangoDB will reject client requests with a negative value in the Content-Length request header with HTTP 411 (Length Required).

• if the client sends a Content-Length header with a value bigger than 0 for an HTTP GET, HEAD, or DELETE request, ArangoDB will process the request, but will write a warning to its log file.

• when the client sends a Content-Length header that has a value that is lower than the actual size of the body sent, ArangoDB will respond with HTTP 400 (Bad Request).

• if clients send a Content-Length value bigger than the actual size of the body of the request, ArangoDB will wait for about 90 seconds for the client to complete its request. If the client does not send the remaining body data within this time, ArangoDB will close the connection. Clients should avoid sending such malformed requests as they will make ArangoDB block waiting for more data to arrive.

• when clients send a body or a Content-Length value bigger than the maximum allowed value (512 MB), ArangoDB will respond with HTTP 413 (Request Entity Too Large).

• if the overall length of the HTTP headers a client sends for one request exceeds the maximum allowed size (1 MB), the server will fail with HTTP 431 (Request Header Fields Too Large).

• if clients request a HTTP method that is not supported by the server, ArangoDB will return with HTTP 405 (Method Not Allowed). ArangoDB offers general support for the following HTTP methods:

  • GET
  • POST
  • PUT
  • DELETE
  • HEAD
  • PATCH
  • OPTIONS

  Please note that not all server actions allow using all of these HTTP methods. You should look up up the supported methods for each method you intend to use in the manual.

  Requests using any other HTTP method (such as for example CONNECT, TRACE etc.) will be rejected by ArangoDB.

Cross Origin Resource Sharing (CORS) requests

ArangoDB will automatically handle CORS requests as follows:

• when the client sends an Origin HTTP header, ArangoDB will return a header access-control-allow-origin containing the value the client sent in the Origin header.

• for non-trivial CORS requests, clients may issue a preflight request via an additional HTTP OPTIONS request. ArangoDB will automatically answer such preflight HTTP OPTIONS requests with an HTTP 200 response with an empty body. ArangoDB will return the following headers in the response:

  • access-control-allow-origin: will contain the value that the client provided in the Origin header of the request

  • access-control-allow-methods: will contain a list of all HTTP methods generally supported by ArangoDB. This list does not depend on the URL the client requested and is the same for all CORS requests.

  • access-control-allow-headers: will contain exactly the value that the client has provided in the Access-Control-Request-Header header of the request. This header will only be returned if the client has specified the header in the request. ArangoDB will send back the original value without further validation.

  • access-control-max-age: will return a cache lifetime for the preflight response as determined by ArangoDB.

• any access-control-allow-credentials header sent by the client is ignored by ArangoDB its value is not true. If a client sends a header value of true, ArangoDB will return the header access-control-allow-credentials: true, too.

Note that CORS preflight requests will probably not send any authentication data with them. One of the purposes of the preflight request is to check whether the server accepts authentication or not.

A consequence of this is that ArangoDB will allow requests using the HTTP OPTIONS method without credentials, even when the server is run with authentication enabled.

The response to the HTTP OPTIONS request will however be a generic response that will not expose any private data and thus can be considered "safe" even without credentials.