Legacy REST API

General concepts

The RESTful configuration interface is follows the REST concepts. It is stateless and each request is treated as a new configuration transaction. It’s possible to target a small subsystem with configuration changes, or the entire server in a single sweep. The REST interface implements a full CRUD system to manage all configuration in the Identity Server.

The RESTful API tries to follow the RESTCONF [draft-ietf-netconf-restconf-07] protocol, which is an upcoming configuration standard sibling to the NETCONF configuration protocol. But since the RESTCONF is still a draft a number of differences exist.

HTTP Operations

The configuration can be created, read, updated and deleted using the following HTTP methods:

  • GET - Retrieve configuration
  • POST - Create configuration elements
  • PUT - Replace configuration
  • PATCH - Update (merge) configuration
  • DELETE - Remove configuration

Accept Headers

The REST API can be used with two data types, XML and JSON.

  • application/vnd.yang.data+xml
  • application/vnd.yang.data+json
  • application/vnd.yang.collection+json
  • application/vnd.yang.collection+xml

Base URL

All operations start at the same base URL:

/admin/api/rest

Note

Note, the port of the configuration interface is different from the runtime ports. The factory default is 6749.

Operations on the configurations are performed on the running datastore.:

/admin/api/rest/running

There are also special datastores. The rollbacks are one example. They are located under:

/admin/api/rest/rollbacks

Authentication

The REST API is protected with BASIC authentication. The same credentials as used with any administrator function should be used.

Query Parameters

Parameter Method Description
deep GET Retrieve a subtree with all it’s children
shallow GET Retrieve a subtree but only one level deep
verbose GET Will add self attributes to provide REL links
with-defaults GET Includes default values in response
operations GET true or false, when set to false only config is present in the result
force-put PUT when set, a PUT operation is allowed on the root (/admin/api/rest/running)

If neither deep nor shallow is passed as argument a variable depth will be returned.

Working with URIs

All resources can be represented with an HTTP URL.

Simple entries

Example - the Identity Server name (default issuer):

/admin/api/rest/running/environments/environment/name

Some resources are lists, like the services and profiles.

Keyed entries

Example - URI of a service:

/admin/api/rest/running/environments/environment/services/service/{nodeId}

/amin/api/rest/running/environments/environment/services/service/Node1

The resource Node1 in this example is a service node, i.e. an instance in the service list. If calling the same resource but omitting the resource Id, all nodes will be returned:

/admin/api/rest/running/environments/environment/services/service

Multi-keyed entries

Some resources have multiple keys that together make up the key for the resource. One example is the Profile list. It has two keys, the profile ID and the profile TYPE, these are comma separated:

/admin/api/rest/running/profiles/profile/{profileId profileType}

/admin/api/rest/running/profiles/profile/authentication,auth:authentication-service

Examples

This section gives the reader some examples on how to work with the REST interface. More detailed configuration examples are found in the configuration sections for each subsystem.

Make a complete dump of all configuration (backup)

GET /admin/api/rest/running?deep

Read the top level tag with the deep query parameter to retrieve all configuration

Request:

GET /admin/api/rest/running?deep HTTP/1.1
Host: localhost

Response:

HTTP/1.1 200 OK
Content-Type: application/vnd.yang.datastore+xml

<data>
        <environments xmlns="https://curity.se/ns/conf/base">
                <environment>
                  <name>DefaultName</name>
                  <localization>
                    <default-locale>en-US</default-locale>
                    <supported-locale>en-US</supported-locale>
                    <supported-locale>sv-SE</supported-locale>
                  </localization>
                  <services>
                    <zones>
                      <default-zone>
                        <authentication-service>
                        ...
Request Headers:
 
  • Authorization – Basic authentication with an Administrators credentials
  • Accept – the response content type depends on Accept header, default is xml based content.
Response Headers:
 
Status Codes:
  • 200 OK – Data returned in the response body