RESTCONF API¶

General Concepts¶

The RESTCONF API introduced in version 4.0 of the Curity Identity Server is a standard-compliant, REST-like protocol that exposes all management data over a secure communication channel. The API is defined in RFC 8040, and supports common HTTP verbs (like GET and POST) as well as more exotic ones like OPTIONS and PATCH). There are multiple media-types supported, allowing clients to request data in both XML and JSON format. The API is completely stateless, and expose each resource within the configuration as URIs. The API also exposes rollback information, and exposes RPC commands (e.g., to generate new keys). Like the legacy REST API, it is possible to use the RESTCONF API to perform Create, Read, Update, and Delete (CRUD) operations on all data. Unlike, the previous REST API, RESTCONF also allows the entire schema to be obtained, so that clients can knowledgeably traverse the hierarchical data exposed by the RESTCONF API.

RESTCONF Endpoint¶

If the Admin UI is enabled, the RESTCONF API will be exposed on the same server and port with the same SSL certificate. By default, this is port 6749. The base path of the RESTCONF API is available at /admin/api/restconf. All data is exposed under the subroute data. Consequently, the default base URL is:

https://localhost:6749/admin/api/restconf/data.

Besides the data endpoint, the other standard compliant resources are also exposed under the base path /admin/api/restconf. These are the operations and yang-library-version resources. The former is used to invoke operations, like those used to create a new key. The later can be helpful to obtain the schema of the entire API. This schema can be useful for defining smart clients that can traverse the schema; it can also be helpful when debugging a plug-in’s configuration model.

URIs¶

One of the primary benefits provided by the RESTful API design is that each resource can be accessed using URLs. The path to a resource follows the hierarchical data model. This can be determined by locating a resource in the Configuration Reference. It is also possible to obtain from the YANG data model included with the product and exposed via the RESTCONF API. For those unfamiliar with YANG, the only potentially tricky part is locating a resource is determining the key when that resource is in a list. The exact algorithm for doing this is described in section 3.5.3 of RFC 8040.

RESTCONF Operations¶

As defined in section 4 or the REST CONF RFC, the API supports the following operations:

RESTCONF	Description
OPTIONS	Determine which methods are supported by the server.
GET	Retrieve data and metadata about a resource.
HEAD	The same as GET, but only the response headers are returned.
POST	Create a resource or invoke an RPC operation.
PUT	Create or replace a resource.
PATCH	Create or update (but not delete) various resources. Both plain HTTP patch (RFC 7589) and YANG patch (RFC 8072) are supported.
DELETE	Sent by a client to delete a target resource.

Querying Data¶

The RESTCONF API accepts various parameters on the query string. The allowed parameters and their values depend on the HTTP method being used and the type of resource. The allowed parameters and the situations in which they can be used are summarized in the following table:

Query Parameter	Possible Values	HTTP Method	Description
`content`	`all`, `config`, `nonconfig`	`GET`, `HEAD`	Whether config and/or operational data is returned – default is `all` if `content` is not provided in the request
`depth`	Any positive integer value	`GET`, `HEAD`	Number of subtrees of configuration, relative to the resource, which are returned
`fields`	A semi-colon-separated list of path string values	`GET`, `HEAD`	Request a subset of the content exposed by the resource or its children (e.g., `id,other-elem/name` to select only the ID and name of the `other-elem` child)
`with-defaults`	`report-all`, `trim`, `explicit`, `report-all-tagged`	`GET`, `HEAD`	Allows the content of a resource to be included or excluded depending on whether the value is equal to the schema default
`rollback-comment`	A text value	`POST`, `PUT`, `PATCH`, `DELETE`	Used to specify a comment to be added to the rollback file
`rollback-label`	A text value	`POST`, `PUT`, `PATCH`, `DELETE`	Used to specify a label to be added to the rollback file
`rollback-id`	true	`POST`, `PUT`, `PATCH`, `DELETE`	Returns the rollback id in the response if the rollback file was created during the operation

There are additional parameters that are less often used. For details, refer to section 4.8 of the RFC.

Rollback using RESTCONF¶

RESTCONF also uses the same transactional engine as used by other configuration interfaces, so essentially it means that it is possible to rollback to a previous state using RESTCONF as well.

Listing 290 Listing rollbacks using curl¶

$ curl --location --request GET 'https://localhost:6749/admin/api/restconf/data/tailf-rollback:rollback-files/' \
  --header 'Accept: application/yang-data+json' \
  --user 'admin:Password1'

Listing 291 Applying a specific rollback using curl¶

$ curl --location --request POST 'https://localhost:6749/admin/api/restconf/data/tailf-rollback:rollback-files/apply-rollback-file' \
  --header 'Content-Type: application/yang-data+json' \
  --user 'admin:Password1' \
  --data-raw '{
      "input": {
          "fixed-number": "10000"
      }
  }'

Invoking YANG Actions Using RESTCONF¶

Invoking YANG actions using RESTCONF is done by using the operations resource. For example, to invoke the add-signature-verification-key action that is defined under the /facilities/crypto path, this request needs to be sent:

Listing 292 Invoking a YANG action using curl¶

$ curl --location --request POST 'https://localhost:6749/admin/api/restconf/operations/facilities/crypto/add-signature-verification-key' \
  --header 'Content-Type: application/yang-data+json' \
  --user 'admin:Password1' \
  --data-raw '{
        "input" : {
            "id" : "signature-verification-key",
            "keystore" : "MIIF8DCCA9igAwIBAgIGD1ZEUb8...yXQh/DW5K+inxVN"
    }
}'

The input field inside the request body would contain the input parameters for the action to be invoked.

Message Encoding¶

Messages are encoded as described in section 3.6 or RFC 8040. The media types that are to be used are specified in section 3.2 of the same RFC. In particular, they are application/yang-data+xml and application/yang-data+json.

Authentication¶

Basic authentication is used to identify a user of the RESTCONF API. The accounts are the same as those used to authenticate to the admin UI. By default, these are managed in the configuration database (CDB), but can be configured to be any externally supported data (e.g., RDBMS, LDAP, etc.). To use this functionality, a credential manager should be configured. When that credential manager is one that uses an LDAP data source, it is possible to return the set of groups that the user is in. This should be done by including the memberOf attribute on the authenticated user LDAP entry. The Common Name (CN) of that group is the value that needs to match the group of any rule-list that should be applied to that user. For instance, if the memberOf attribute of the authenticated user is cn=my-good-group,o=example,c=se, then the group will be my-good-group. Refer to Access Control for more details on access control.

It is also possible to authenticate using OAuth. In such a case, the specific client(s) that can be used must be configured. These have certain restrictions that will be enforced when the configuration is validated (e.g., the configured scopes, audiences, etc.). If this access contains a group claim, these values will be used for access control.

Any group provided by the LDAP server or in the OAuth access token need not be defined in the NACM section of the CDB. However, creating rules in the UI does require them to be explicitly created. Otherwise, the UI is not aware of them.