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 operation 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. Some examples are included in the 4.0 migration guide as well.

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 heaers 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

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

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. For requests for data that return a list, the former XML format cannot be used because the list of elements needs a root elemet in order to be valid XML (as stated in section 4.3). To cater to such situations, the non-standard application/vnd.yang.collection+xml media type can be requested. As a simple rule of thumb, make requests with the following Accept header: Accept: application/yang-data+xml;q=0.8, application/vnd.yang.collection+xml or just Accept: application/yang-data+json. Using either of those is always sure to produce a non-error response.

Authentication¶

Like the legacy REST API, basic authentication is used to identify oneself to 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.).

Migration¶

Refer to the 4.0 upgrade guide for information about upgrading from the Legacy REST API. By and large, this process should be relatively straight-forward and minimally impactful because the legacy REST API was nearly compliant with RESTCONF.