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.
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:
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.
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.
As defined in section 4 or the REST CONF RFC, the API supports the following operations:
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:
There are additional parameters that are less often used. For details, refer to section 4.8 of the RFC.
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.
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.