Custom Operations
The RESTful API defines a set of common interactions (read, update, search, etc.) performed on a repository of typed resources. These interactions follow the RESTful paradigm of managing state by Create/Read/Update/Delete actions on a set of identified resources. While this approach solves many use cases, there is some functionality that can be met more efficiently using an RPC-like paradigm, where named operations are performed with inputs and outputs (Execute)1.
In the following example, a system operation will be defined to retrieve underlying deployment details, using the end-point \$version. First, create a VersionOperation.
Instance: VersionOperation
InstanceOf: OperationDefinition
Usage: #definition
* version = "0.1.0"
* name = "$version"
* status = #draft
* title = "Retrieve Release ID and Component Semver"
* kind = #operation
* code = #version
* system = true
* type = false
* instance = false
* parameter[0].name = #return
* parameter[=].use = #out
* parameter[=].min = 1
* parameter[=].max = "1"
* parameter[=].documentation = "Result of the version operation."
* parameter[=].type = #OperationOutcome
This defines the following expected body in the POST request
{
"resourceType": "Parameters",
"parameter": [
{
"name": "string",
"valueString": "string",
"additionalProp1": {}
}
]
}
then reference this by extending the CapabilityStatement.
// system interactions
* rest.interaction[+].code = #transaction
// system custom operations
* rest.operation[+].name = "version"
* rest.operation[=].definition = Canonical(VersionOperation)