Chapter 2. REST Interface
The management REST component maps REST requests to management requests. To map the requests first the REST component locates the managed resource then maps the request URL to a management address and invokes an operation on that managed resource. The management REST component defines an entry point for REST clients, and exposes the registered managed resources and operations over REST.
2.1. Accessing REST Interface
To gain access to management resources and operations over REST a RESTful client must know the entry point URL.
Example 2.1. Entry point URL syntax
http(s)://<host>:<port>/<rest-context-name>/private/managed-components
where the rest-context-name is the portal container's rest context name.
For the default portal, the rest context name is 'rest'.
For a portal running on localhost and port 8080 the URL changes.
Example 2.2. URL for a portal running on localhost
http://localhost:8080/rest/private/managed-components/
Note
The REST URL is protected, and the authenticated user must belong to the 'administrators' group of the portal.
2.2. Resource URLs for REST Interface
REST resource URLs are mapped to management addresses, and since every managed resource has a unique management address, each managed resource can be represented by a unique REST URL.
Example 2.3. URL for identifying managed resources
http://<host>:<port>/<rest-context-name>/private/managed-components/<component-name>/<managed-resource-name>/<sub-resource-name>/.../<sub-resource-name>
Example 2.4. URL for identifying managed sub-resource
This URL uniquely identifies a managed resource named 'foo-bar', which is a sub-resource of 'bar', and 'bar' being a managed resource of the managed component 'foo'.
http://localhost:8080/rest/private/managed-components/foo/bar/foo-bar
2.3. HTTP Method
Table 2.1. Mapping HTTP methods to Operation names.
| HTTP Method | Management Operation |
|---|---|
| GET | read-resource |
| PUT | update-resource |
| POST | add-resource |
| DELETE | remove-resource |
This means that the same URL can invoke four different operations just by changing the HTTP method of the REST request.
2.4. Using Request Parameter
The management system supports more than four operations. These operations can be explicitly defined by including HTTP parameters as part of the REST request.
For example by adding the query parameter
op to the request URL, clients can define what operation to invoke.
Example 2.5. Custom operation defined in request parameter
http://localhost:8080/rest/private/managed-components/foo/bar?op=some-custom-operation
Best practice to use the HTTP method
You can use the HTTP method to dictate the operation name. But a client can explicitly set operation names as request parameters.
URLs equivalent to a GET request are:
2.5. Using URL Extension
REST resources can be represented as files, so two URL extensions have been added to support two common operations:
read-config-as-xml and export-resource.
To invoke these operations add the following URL extensions at the end of the URL
Table 2.2. List of URL Extensions
| URL Extension | Management Operation | Example URL |
|---|---|---|
| xml | read-config-as-xml | http://localhost:8080/rest/private/managed-components/foo/bar.xml |
| zip | export-resource | http://localhost:8080/rest/private/managed-components/foo/bar.zip |
It is easier to specify the operation name as a file extension instead of specifying it as a request parameter.
The following URLs mean the same:
2.6. Management Attributes
Management attributes are part of a management request. They are mapped by including all request parameters of the HTTP request as attributes. If an operation supports certain attributes, query parameters can be added to the request URL to be used as attributes of the management request.
Example 2.6. Attributes first-name and last-name as request parameters
http://localhost:8080/rest/private/managed-components/foo/bar?first-name=john&last-name=doe
2.6.1. Multivalue Attributes
Management attributes can be multi-valued which means having more than one value associated with an attribute. HTTP query parameters can be multi-valued.
Example 2.7. Multi-valued attribute colors as request parameters
http://localhost:8080/rest/private/managed-components/foo/bar?colors=red&colors=green&colors=blue
2.7. Content Control
The management framework defines Content Type to indicate the format of management requests and responses. Clients can dictate the content type of the management request by specifying the
Accept and Content-Type headers of the HTTP request. The Accept header indicates the format of the response and the Content-Type header specifies the format of the request.A list of request headers that map to the Content Type of the management system is as follow.
Table 2.3. List of Request headers
| Header | Content Type |
|---|---|
| application/json | JSON |
| application/xml | XML |
| application/zip | ZIP |
Note
JSON is the default content type.
2.7.1. Browser Content Control
To control the content type of management requests through the browser, the REST component supports the
format HTTP parameter to dictate the format of the response. This is because most browsers already send an Accept header.
Example 2.8. Specifying that the response should be returned as XML
http://localhost:8080/rest/private/managed-components/foo/bar?format=xml
The
format HTTP parameters that map to Content Types are shown in here:
Important
Content negotiation is ignored for content type specific operations such as
read-config-as-xml and export-resource since these cannot return different formats.
2.7.2. Operation Control
The
read-resource operation is a built-in operation provided by the management component. The response is formatted as follows.
Example 2.10. Response as JSON
HTTP/1.1 200 OK
Content-Type: application/json
{
"description": "Available operations and children (sub-resources).",
"children": [
{
"name": "foo",
"description": "Some description",
"link": {
"rel": "child",
"href": "http://localhost:8080/rest/private/managed-components/foo"
}
}
],
"operations": [
{
"operation-name": "read-resource",
"operation-description": "Lists information about a managed resource, including available operations and children (sub-resources).",
"link": {
"rel": "self",
"href": "http://localhost:8080/rest/private/managed-components"
"type": "application/json"
"method": "get"
}
}
]
}
Example 2.11. Response as XML
HTTP/1.1 200 OK Content-Type: application/xml <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <resource> <description>Available operations and children (sub-resources).</description> <children> <child> <name>foo</name> <description>Some description</description> <link href="http://localhost:8080/rest/private/managed-components/foo" rel="child"/> </child> </children> <operations> <operation> <operation-name>read-resource</operation-name> <operation-description>Lists information about a managed resource, including available operations and children (sub-resources).</operation-description> <link href="http://localhost:8080/rest/private/managed-components" rel="self" type="application/xml" method="get"/> </operation> </operations> </resource>