Configuring the Realm Definition Using the Web API

Administrators can use the FTL server web API to configure and deploy the realm definition.

Procedure

  1. Create a realm workspace.
    This step simultaneously requests the realm modification lock (see Modification Lock) and creates a workspace. 
    POST realm/workspace

    The realm modification lock ensures that at most one workspace can be open at a time. If another user has an open workspace, this method returns an error code.

    While the workspace is open, the FTL server processes all requests in the context of that workspace. For example, methods that create, modify, or delete definitions affect the workspace, not the FTL server database.

    Perhaps less intuitively, while you hold the modification lock, GET methods get definitions from your workspace, rather than from the database, reflecting changes you have made but not yet deployed. For users who do not hold the lock, GET methods still get definitions from the database. (For background information, see Realm Storage.)

  2. Modify the workspace by adding definition objects and updating existing definition objects. For example: 
    POST realm/transports transport_json_data
    Repeat this step until your realm configuration is complete.
  3. Validate the candidate realm definition.
    Successful validation indicates that all the object definitions are complete, and mutually consistent. 
    GET realm/workspace/validation
    If the validation results indicate errors, you must correct them before proceeding to the next step.
  4. Start the deploy transaction.
    This action corresponds to the full deploy transaction. (See The Deploy Transaction.) 
    POST realm/deployments deployment_json_data
    The success response code 202 indicates that the FTL server has accepted the deployment request. The workspace becomes the active deployment candidate. The deploy transaction continues asynchronously.
  5. Check the results of the deploy transaction.
    You can check the results of named deployment using the web API: 
    GET realm/deployments/name
    You can also see the deployment results on the Deployment History page of the FTL server GUI (see Deployment History).