Semantics of Web API Objects and Methods
Each category of FTL server web API objects has a distinct semantic.
Realm Definition Objects
Realm definition objects correspond to aspects of the realm definition.
The main realm definition objects are applications, bridges, eftl, formats, persistence, and transports. Objects nested within these objects also belong to this category and have similar method semantics; for example, formats/format_name and eftl/clusters/cluster_name/channels.
For objects in this category, POST, PUT, and DELETE methods require the modification lock. These methods always affect the realm definition in the workspace, not in the FTL server database.
- If you hold the modification lock, GET methods retrieve information from your workspace.
- If you do not hold the modification lock, and even if another user holds the lock, GET methods retrieve information from the FTL server database.
- While a deploy transaction is active, GET methods return an error response.
POST methods define new objects.
- If the object already exists,
PUT updates its definition, completely replacing the old definition with method's input data.
To change the name of a definition object, supply the old name in the URI, and the new name in the JSON input data.
- If the object does not exist, PUT creates an object using the definition in the JSON input data (like POST).
Workspace
The workspace represents a modified realm definition that has not yet been deployed.
The main workspace object is realm/workspace.
GET methods retrieve or validate the workspace.
POST methods create a workspace.
DELETE methods delete the workspace.
Deployments
Deployments represent the current state of the realm definition. The FTL server maintains a history of successful deployments (this history excludes attempted deploy transactions that failed and rolled back).
The main deployment object is realm/deployments.
GET methods retrieve a collection of deployments or an individual deployment.
POST methods start a deploy transaction or test.
PUT methods can redeploy an earlier deployment.
DELETE methods delete a deployment from the history list.
Status Objects
Status objects correspond to executable processes and to objects within those processes. For example, executable processes include your own client processes, as well as operating components of TIBCO FTL software, such as transport bridge services, eFTL services, and persistence services. Some components contain nested objects; for example, persistence services contain stores and durables.
The main status objects are server, clients, bridges, eftl, groupservice, and persistence. Objects nested within these objects also belong to this category, and have similar method semantics; for example, persistence/cluster_name/stores/store_name/durables.
For objects in this category, GET methods report the status or metrics related to a process or its nested objects. GET methods can also retrieve a collection of nested objects from a process.
POST methods update the operating parameters of a process, such as logging behavior. POST methods can also deliver commands to a process, for example, to suspend it.
DELETE methods can delete a client status object from the FTL server, so the FTL server no longer tracks that client. Delete methods can also remove a nested object from within a client, for example, removing a durable subscriber from within a client.