addonscript-spec/docs/api/features/env.md

3.9 KiB

Environment builder

Endpoints

Build launch environment

POST {base URL}/v2/env

This endpoint can be used to build the launch environment for an instance addon.

If an instance addon, which has to provide a launch configuration, has the env manifest flag, AddonScript will send a request to this endpoint of an API instance, on which the repository of the namespace of this addon can be found. This request contains information about the AddonScript schema version, which will be used in the request and about which addon this request is for. Moreover it contains for both sides a list of addons, including their version, which will be part of the addon in this environment on that side. The manifest of this addon uses the env relation flag to tell AddonScript, which related addons MAY and which MUST be requested on this endpoint and which versions of them are valid. Which exact version of them and which optional addons will be requested is either decided by the user, if the instance addon is installed manually, or by another instance addon, which delegates the launch configuration to this addon. In later case, that instance addon uses the env relation flag to specify an exact version for each addon, that will be requested. Each required env addon MUST be covered this way while only those optional env addons will be requested, which are covered this way. Lastly the request also contains for each side a list of all related addons of this one, which are or will be installed into this instance, including their version. This does not include relations with the env relation flag.

Since the API instance MAY download files or build/compile things to build the launch environment, this request MAY take some time so the client implementation SHOULD set the request timeout for this endpoint rather high. It is RECOMMENDED to have a timeout of at least 5 minutes, better about 10 minutes.

After the launch environment was build by the API instance, this endpoint will respond with a list of file objects and the AddonScript schema version for the response. These files MUST be considered to be part of the files of the addon, from which the request was send and can then be installed.

Request Body:

The request body MUST be an Environment Builder Request Object.

Responses:

  • 200 OK: The launch environment was successfully build. The response body MUST be an Environment Builder Response Object.
  • 400 Bad Request: The server was not able to build the launch environment because of invalid information send by the client. The client SHOULD NOT try this request on another API instance, since the request is invalid.
  • 404 Not Found: The launch environment can't be build for this addon, because no information about it was found on this API instance. The client SHOULD try to use another API instance to build the environment.
  • 500 Internal Server Error: The server was not able to build the launch environment because of an internal error. The client MAY try to request the environment on another API instance.