Operations

This chapter describes the operations that can be performed on the authorization domains.

Storing a domain

An Authorization Domain document format version 2 file can be represented in JSON and YAML.

• A file stored in JSON will be retrieved as JSON.

• A file stored in YAML will also be retrieved as JSON.

Storing a domain in ADM is done in the following way:

Using a YAML-format domain:

curl -X POST http://<host:applicationConnectorsPort>/api/namespaces/<namespace>/names/<domain_name> -H "Content-Type:application/yaml" --data-binary\@filename.yaml -u user:password

Using a JSON-format domain:

curl -X POST http://<host:applicationConnectorsPort>/api/namespaces/<namespace>/names/<domain_name> -H "Content-Type:application/json" --data-binary\@filename.json -u user:password

The domain identifier is generated by ADM when storing a domain.

Note: Storing a YAML-format domain that includes a large policy (>10MB) formatted as one line may adversely affect performance. If the domain is stored or retrieved in JSON format, no performance penalty has been observed.

Retrieving a domain

Retrieving a domain in ADM can be done by name or by identifier.

Retrieving a domain by name

curl http://<host:applicationConnectorsPort>/api/namespaces/<namespace>/names/<domain_name>/domain -u user:password

Conditional requests

ADM supports HTTP conditional requests for the retrieve domain by name operation. HTTP conditional requests makes use of specific headers that can define a precondition that will change the result of the request based on whether the precondition is met or not.

An ADM client fetching a domain by name can include a header to indicate which authorization domain(s) it is already in possession of. If any of those domains match the domain currently pointed to by the domain name, ADM will indicate this to the client and avoid including a complete representation of the domain in the response thus reducing network load. This is implemented using an "Etag" header field as validator value, compliant with IETF RFC 7232, §2.3.

Furthermore, this implementation is compliant with IETF RFC 7232, §3.2, which delineates the name and semantics of the header information that clients must use for an "If-None-Match" header field, and IETF RFC 7232, §4.1, which describes the definition of the "304 (Not Modified)" status code and header information ADM will use in its response if the representation has not changed since the previous request.

For clients that do not provide such domain information, the response from ADM always includes a representation of the domain currently pointed to by the name.

Retrieving a domain by identifier

curl http://<host:applicationConnectorsPort>/api/domains/<domain_id> -u user:password

Retrieving a list of domain names

This operation is used to get a list of the domain names available in the namespace.

curl http://<host:applicationConnectorsPort>/api/namespaces/<namespace>/names -u user:password

Retrieving a domain name history

This operation is used to retrieve the history of a domain name. It takes namespace and domain name as arguments and returns an array of the historical changes of this domain name in the form of pairs of dates and domain IDs sorted by time.

curl http://<host:applicationConnectorsPort>/api/namespaces/<namespace>/names/<domain_name>/history -u user:password

The information shows which domains have been active and for which time periods, which in turn can be used to roll back to a previous point in time.

Rolling back a domain name

This operation is used to roll back changes to a domain name. It takes namespace, domain name, and domain ID as arguments and points the domain name to the given domain ID, thus restoring the domain name to a previous state represented by the domain ID.

curl -X POST http://<host:applicationConnectorsPort>/api/namespaces/<namespace>/names/<domain_name>/rollback/<domain_id> -u user:password

After successfully running the operation, the domain name is pointed to the given domain ID.

Note: The operation will fail if the domain ID given as part of the argument has never been associated with the domain name.

Deleting a domain name

A domain name can be deleted using the following operation:

curl -X DELETE http://<host:applicationConnectorsPort>/api/namespaces/<namespace>/names/<domain_name> -u user:password

Note: What is being deleted here is the mapping, or association, of the domain name to the namespace, not the actual domain. The domain itself cannot be deleted, and the domain ID remains unchanged for audit and forensic purposes.

Deleting a namespace

A namespace can be deleted using the following operation:

curl -X DELETE http://<host:applicationConnectorsPort>/api/namespaces/<namespace> -u user:password

Copying a domain name

The contents of a domain name can be copied to another domain name using the following operation:

curl -X PUT http://<host:applicationConnectorsPort>/api/namespaces/<namespace>/names/<sourceName>/copy/<destinationName> -u user:password