This API is a HTTP-based REST API with predictable resource URIs. The API accepts and returns data encoded in YAML or JSON.

The API provides a clean separation between configuration, operational state, and operations (RPCs).

Configuration data is read and written under the path /v1/config. This data is called the intended configuration. It is the configuration data provided by the user of the system. All data in the intended configuration is both readable and writable.

The operational state of the system can be read under the path /v1/state. The operational state is read only. The operational state contains the state of all intended configuration (this is called the applied configuration), and all system state.

The state of a configured object under /v1/config/<PATH> can be read from /v1/state/<PATH>.

The table below shows the structure of the API.

URI	GET	POST	PUT	PATCH	DELETE
/v1/config	read all	crud	-	-	-
/v1/config/LIST	read all	create	-	-	-
/v1/config/LIST/NAME	read one	-	create/replace	update	delete
/v1/config/OBJECT	read	-	create/replace	update	delete
/v1/state	read all	-	-	-	-
/v1/state/LIST	read all	-	-	-	-
/v1/state/LIST/NAME	read one	-	-	-	-
/v1/state/OBJECT	read	-	-	-	-
/v1/state/OPERATION	-	invoke	-	-	-
/v1/OPERATION	-	invoke	-	-	-

The PATCH method can be used for simple updates of an existing resource.

The existing object is merged with the data in the payload.

A scalar value in the payload replaces the corresponding value in the object, if it exists; otherwise the given scalar value is created.

Arrays where the order is significant are replaced with the new array.

Arrays where the order is not significant are merged. This means that it is not possible to delete entries in such arrays with PATCH. In order to do that, the entire object must be replaced by using PUT.

All objects in the intended configuration have an entity tag (ETag) that can be used to control concurrent access to the object, and detect if an object has been modified.

Use standard HTTP mechanisms (e.g., the header If-Match) to handle entity tags.

This endpoint represents the tenant's entire intended configuration.

GET

A GET to this endpoint returns the entire intended configuration.

If YAML is requested, each object is returned as a separate YAML document. If JSON is requested, a list of objects is returned.

In the representation of each object, an additional field x-path is included, that contains the path to the object.

If the query parameter send-etag=true is sent, each object also has a field x-etag.

For example, the reply could look like this:

---
x-path: /v1/config/applications/my-app
name: my-app
version: 1.2.2
# more data here ...
---
x-path: /v1/config/application-deployments/my-dep
name: my-dep
application-name: my-app
application-version: 1.2.2
# more data here ...

POST

A POST to this endpoint is used to update multiple objects in one transaction, i.e., either all included operations are accepted, or none.

The format of the POST request is the same as result of a GET request, except that each object also may have an additional field x-operation, that controls how the object is updated. It can have the following values:

• create - The object is created if it doesn't exists. An error is returned if the object already exists.
• replace - The object is replaced if it exists, and create if it doesn't exists.
• update - The existing object is merged with the given fields. An error is returned if the object doesn't exists.
• delete - The object is deleted if it exists. An error is returned if the object doesn't exist.
• remove - The object is deleted if it exists. No error is returned if the object doesn't exist.

The query parameter default-operation can be given to specify which operation is used for a object that doesn't have an x-operation field. If no such query parameter is given, the default operation is replace.

For example, the following request deletes the application other-app and updates the application deployment my-dep:

---
x-path: /v1/config/applications/other-app
x-operation: delete
---
x-path: /v1/config/application-deployments/my-dep
x-operation: update
application-version: 1.2.3

If an object has a field x-etag, the operation succeeds only if the object exists with the same etag.

NOTE: It is not possible to update objects in strongbox through this endpoint.

This endpoint represents the tenant's entire operational state.

GET

A GET to this endpoint returns the entire operational state.

If YAML is requested, each object is returned as a separate YAML document. If JSON is requested, a list of objects is returned.

In the representation of each object, an additional field x-path is included, that contains the path to the object.

For example, the reply could look like this:

---
x-path: /v1/config/applications/my-app
name: my-app
version: 1.2.2
# more data here ...
---
x-path: /v1/config/application-deployments/my-dep
name: my-dep
application-name: my-app
application-version: 1.2.2
# more data here ...

The API uses standard HTTP status codes to indicate success or failure of the requests. When an error body is returned, it is on the form:

{
  "errors": [
    "error-message": "string",
    "error-info": "optional operation-specific error info"
  ]
}

The error is returned as JSON or YAML depending on the given Accept header.

The fields query parameter can be used in GET requests to return only the requested fields in the reply.

The syntax of this parameter is:

  <sequence> = <expr> ( ',' <expr> )*
  <expr> = <path> ( '/'  '[' <sequence> ']' )?
  <path> = <field-name> ( '/' <path> )?
  <field-name> = <identifier> | <identifier>=<identifier>

For example:

• fields=foo,bar - selects the fields foo and bar
• fields=foo/bar - selects the fields bar in foo
• fields=foo/[bar,baz] - selects bar and baz in foo
• fields=foo=x/bar - selects bar in foo, and renames foo to x in the output