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 289 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 290 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 291 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.