URI Specification for RAD Resources

Language:

In a RESTful architecture, RAD objects are modeled as resources. A resource is an entity with a type, associated data, relationships to other resources, and a set of methods that operate on it. A URI is used to identify a resource. Resources can exist individually or as a collection. And a collection can be nested within an individual resource.

The URI format to access RAD resources can include a variety of parameters, for example:

http://host:port/api/{namespace}/[{version}]/{collection}[?query-params]

http://host:port/api/{namespace}/[{version}]/{collection}/{coll-ID}[?query-params]

http://host:port/api/{namespace}/[{version}]/{collection}/{coll-ID}/{property}[?query-params]

http://host:port/api/{namespace}/[{version}]/{collection}/{coll-ID}/{sub-collection}[?query-params]

http://host:port/api/{namespace}/[{version}]/{collection}/{coll-ID}/{sub-collection}/{sub-coll-ID}[?query-params]

http://host:port/api/{namespace}/[{version}]/{collection}/{coll-ID}/{sub-collection}/{sub-coll-
                        ID}/{property}[?query-params]

http://host:port/api/{namespace}/[{version}]/{collection}/{coll-ID}/{sub-collection}/{sub-coll-ID}/{sub-collection}/{sub-coll-ID}/{sub-collection}......[?query-params]

The components in the URIs are as follows:

namespace – Name associated with a RAD module, generally the module API name or domain name of the RAD module.
version – Optional version number that specifies the RAD module version.
collection – Collection resource.
coll-ID – Identifier or path to an individual resource within a collection that identifies a specific RAD instance.
sub-collection – Collection nested within an individual resource. It is an interface property of type struct, a list, a dictionary, or a reference.
sub-coll-ID – Identifier or path to an individual resource within a subcollection. It consists of a struct field, a list index, a dictionary key, or a reference property.
property – An interface property within a specific individual resource.

Sample URI:

http://host:port/api/com.oracle.solaris.rad.zonemgr/1.2/Zone/testzone1?_rad_detail

All REST requests take the optional _rad_detail query parameter. If this query parameter is set to true, you will get the full details of an object in the response. The default setting is false.

In some cases, a server object does not have a name and the use of a standard URI to refer to a RAD instance does not make sense. This situation might occur when a reference to a RAD instance is returned as an error or as the result from a method. In this case, the server generates a URI path that includes a _rad_reference field. For example, the following is a possible URI:

/api/com.oracle.solaris.rad.zonemgr/1.0/Zone/_rad_reference/1234

The URI is valid to use in the remainder of the session but is valid only for the lifetime of a session.

URI for an Individual RAD Resource

Individual resources are identified by a URI that includes a comma-separated list of all primary keys. For example, an individual zone object might be represented by the following URI:

/api/com.oracle.solaris.rad.zonemgr/1.0/Zone/testzone1

URI for a RAD Resource Collection

Collections are identified by a URI which includes the name of the collection. For example, a zone collection object is represented by the following URI:

/api/com.oracle.solaris.rad.zonemgr/1.0/Zone

Invoking RAD Interface Methods

To invoke a method supported by an interface in a URI, include the method name and an ordered list of arguments in the request. The response includes any results or errors returned by the interface method.

Example 57 Listing the anet Properties of a Zone in RAD

The following example shows how to get the anet properties of a zone and the sample response.

# curl -H 'Content-Type:application/json' -X PUT \
   localhost/api/com.oracle.solaris.rad.zonemgr/1.0/Zone/testzone1/_rad_method/getResourceProperties \ 
   --data '{"filter": {"type": "anet"}}' \ 
   --unix-socket /system/volatile/rad/radsocket-http \
 -b cookie.txt

Sample output:

{
        "status": "success",
        "payload": [
                {
                        "name": "linkname",
                        "value": "net0",
                        "type": "PROP_SIMPLE",
                        "listvalue": null,
                        "complexvalue": null
                },
                {
                        "name": "lower-link",
                        "value": "auto",
                        "type": "PROP_SIMPLE",
                        "listvalue": null,
                        "complexvalue": null
                },.....
....]}

In this example, the getResourceProperties method of the Zone interface is invoked. For more information about the methods supported by the Zone interface, see the zonemgr(3RAD) man page.

Note - When using the _rad_method parameter, the request should be of type PUT.