REST API - Resource Design

In this section:

1. Introduction

Objects in the system are represented as resources. A resource is identified using a logical URL. The URL along with the HTTP method will identify the resource and the operation to be performed by the server. All REST services are stateless, which means that the request must contain enough state to answer the request. Every resource will have a specified URI which will be documented.

Users can perform lookup, create, modify and delete on the resources in the SBC Edge. The response to a REST request will be in XML format, containing a status block and a resource block where applicable.

2. Response Format

The response to the REST requests is in XML format. The response has two parts:

Status - contains status code in case of success or error.
Resource - contains the returned state of the resource from the system as part of the request. The resource block will not be present in case of DELETE requests. Also, the resource block will be present if the request did not fail.

The HTTP header will contain the HTTP status code 200.

<?xml version="1.0">
<root>
	<status>
		Status of the request indicating success or failure.
	</status>
	<resource>
		Data relevant to the particular request.
	</resource>
</root>
</xml>

2.1 Response Status Block

The status block in the response XML contains the following structure:

<status>
    <http_code></http_code>
    <app_status href=" ">
	<app_status_entry code=" " params=" "/>
    </app_status>
</status>

XML Tag	Description	Child Elements
`<status>`	Present is all responses.	`<http_code>` `<app_status>`
`<http_code>`	Standard HTTP code. Application error codes will be mapped to HTTP status code. If the request is successful http_code will be 200. Attributes: None	None
`<app_status>`	Present only if there are application errors. Attributes: href - This contains the URI of the resource that the request was made on.	`<app_status_entry>`
`<app_status_entry>`	There will be one of these tags for every application error for this request. Attributes: code - This is a non-zero number that represents the application error code. params - This is a string that contains the error tokens in a '\|' separated format. Refer to 2.1.1 to see how to use the code and params to obtain the error message.	None

Many of the application errors will have to be mapped to an appropriate HTTP status code. For e.g, if the resource does not exist in case of a modify, the response would contain HTTP status code 404. Application processing error codes that do not match logically to any particular HTTP status code can be mapped to HTTP error 500.

2.1.1 How to obtain error message from code and params

The <app_status_entry> tag will contain the application error code and params as attributes. The code is a non-zero number and the params is a string that contains the tokens in a '|' separated format. These tokens need to be substituted into a detailed error message for the corresponding error code. The error messages for each error code is published in XML format - access the full application error code listing from the API reference doc. Users can substitute the tokens in sequential order in the error message to get the actual error description. The following status block provides an example of an error code with the params.

<status>
	<http_code>200</http_code>
        <app_status href=" ">
            <app_status_entry code="31003" params="1|1"/>
        </app_status>
</status>

In this case, the error message for error code 31003 is: "Cannot delete SIP to Q.850 mapping (%1%). It is in use by SG (%2%).". Substituting the error params in the response in the message, gives the error message as:
"Cannot delete SIP to Q.850 mapping 1. It is in use by SG 1."
Message params and error code can be used to construct any custom application level error that the client wants to construct.

2.2 Response Resource Block

The resource block in the response contains the state of the resource returned after the request. The resource tag is the resource name that the request was made upon. Sometimes a POST can result in a resource name in the response being different from the resource sent in the request. Usually actions on resources return only status block.

The resource block in the response XML contains the following structure:

XML Tag	Description	Child Elements
`<resource_list>`	Present only if a bulk lookup is performed, where multiple instances are listed. Attributes: count - This contains the number of resources in the list	`<resource_pk>` `<resource>`

`<resource_pk>`	Present only if a bulk lookup is performed without details=true query parameter. Attributes: id - This represents the resource identifier. href - This represents the resource URI for the resource.	None
`<resource>`	Present if a bulk lookup with details=true query parameter is performed or if a single GET, PUT or POST without action query parameter is performed. Attributes: id - This represents the resource identifier. href - This represents the resource URI for the resource. app_code_config - This is an error code into the error messages file. This is present only in case of GET and if there were errors in looking up the config attributes of the resource, if applicable. app_params_config - This is a '\|' separated string of the error tokens to be substituted into the error message. This is present only in case of GET and if there were errors in looking up the config attributes of the resource, if applicable. app_code_runtime - This is an error code into the error messages file. This is present only in case of GET and if there were errors in looking up the runtime attributes of the resource, if applicable. app_params_runtime - This is a '\|' separated string of the error tokens to be substituted into the error message. This is present only in case of GET and if there were errors in looking up the runtime attributes of the resource, if applicable. app_code_statistics - This is an error code into the error messages file. This is present only in case of GET and if there were errors in looking up the statistics attributes of the resource, if applicable. app_params_statistics - This is a '\|' separated string of the error tokens to be substituted into the error message. This is present only in case of GET and if there were errors in looking up the statistics attributes of the resource, if applicable. app_code_inventory - This is an error code into the error messages file. This is present only in case of GET and if there were errors in looking up the inventory attributes of the resource, if applicable. app_params_inventory - This is a '\|' separated string of the error tokens to be substituted into the error message. This is present only in case of GET and if there were errors in looking up the inventory attributes of the resource, if applicable.	`<resource_attr>` `<resource_attr_list>`
`<resource_attr>`	Every resource attribute in the resource schema is shown as a separate tag. Attributes: href - This is present when the attribute is a link to another resource and contains the URI for that resource.	None
`<resource_attr_list>`	This is present only when the resource attribute contains multiple instances of another resource. Attributes: count - This represents the number of `<entry>` tags within this list.	`<entry>`
`<entry>`	This is present within a `<resource_attr_list>` tag and represents an individual resource. Attributes: href - This represents a link to another resource and contains the URI for that resource.	None

3. Resource Methods

Lookup, create, modify, delete, action methods can be performed on resources. Some resources do not have all methods applicable.

3.1 Lookup Resource(s)

3.1.1 Lookup Request

Lookup of a resource will be performed using HTTP method GET. For lookup of all resources of a certain type, the resource URI needs to be provided as:

/rest/<resource>

For e.g., /rest/routingtable --> looks up all call route tables in the system.

For looking up all child resources under a parent resource, the URI needs to have the parent id in it.
/rest/linecard/1/telcods1   --> looks up all TelcoDS1 ports under linecard 1.

For lookup of a single object, the resource URL needs to be provided as:

/rest/<resource>/<id>

For e.g., /rest/routingtable/1 --> looks up call route table with ID as 1.

If a lookup is performed on a child object the entire id of the child needs to be provided in the URI:

/rest/linecard/1/telcods1/1  --> looks up TelcoDS1 port under line card 1. The port id is 1:1

The id is the actual instance (rowID) of the resource in the system. This can be obtained by doing a bulk lookup first, which will return the list of instances, each having an id. This in turn can then be used to do single lookup for details of that particular resource. Singleton resources do not have any id, hence lookup of a singleton resource does not require an id.

For lookup of a singleton resource, the URL needs to be provided as:
/rest/<resource>

For e.g. /rest/system  --> looks up the system resource

There will be no bulk lookup for a singleton - the response will always be the details of the singleton resource.

The response for a lookup will be either a link to all the individual resources (bulk lookup) or the details of the resource itself. In case of bulk lookup, an additional query parameter "details=true" can be passed in to get the details of the resources along with the link.

3.1.2 Bulk Lookup Response

The response to a bulk lookup of a resource contains links to the existing resources of that type. These links can be used to further get the details of the individual resource.

<?xml version="1.0"> 
<root>
	<status> 
	</status> 
	<resource_list count="2">
		<resource_pk id="1" href="...."/>
		<resource_pk id="2" href="...."/>
	</resource_list>
</root>

If the details=true parameter was passed in the request, the response will contain individual resource blocks for each resource present in the system of that type.

<?xml version="1.0"> 
<root>
	<status> 
	</status> 
	<resource_list count="2">
		<resource id="1" href="....">
                    <attr1></attr1>
                    <attr2></attr2>
                    ....
                </resource>
		<resource id="2" href="....">
                    <attr1></attr1>
                    <attr2></attr2>
                    ....
                </resource>
	</resource_list>
</root>

3.1.3 Single Lookup Response

Lookup of a single resource returns the resource along with all the attributes in it. Also, if an resource contains an attribute which is an index to another resource, then the attribute contains a link to that referred resource, along with the attribute value. The client can then use the link provided to get the details of that resource.

The attributes are all listed one after the other without any ordering.

<?xml version="1.0"> 
<root>
	<status> 
	</status> 
	<resource id="1" href="....">
		<attr1></attr1>
		<attr2></attr2>
		<attr3 href="....">id</attr3>
		..... 
		..... 
	</resource>
</root>

3.1.4 Categories of Resource Attributes

A resource has attributes which are of type configuration, runtime, statistics or inventory. Most runtime and statistics attribute names are prefixed with an 'rt_'. On lookup, the user will have the option to provide a filter for looking up only the certain category of attributes. A filter is a certain view of the resource. The default behavior will return attributes belonging to all categories applicable for that resource.

The filter will be passed as a URL parameter. Multiple filters can be passed in the same request as a comma-separated string, as shown in the example below. Every resource has a specified set of applicable filters. Providing an invalid filter for a resource will result in error. If multiple filters are passed, each filter will be validated. If any filter is invalid, the request will fail. Filter parameter will be applicable only for HTTP GET.

/rest/linecard/1/telcods1/1?filter=config --> returns only config attributes for the DS1 port with ID 1.

/rest/linecard/1/telcods1/1?filter=config,runtime --> returns config and runtime attributes for the DS1 port with ID 1

The response for a GET operation can have success from one filter and failure from another. This will be sent back to the user as error codes in the response.

3.2 Create Resource

3.2.1 Create Request

A resource can be created on the system using the HTTP method PUT.

The resource URI for creating a resource needs to be provided as:

/rest/<resource>/<id>

For e.g., /rest/routingtable/1 --> creates a new call route table with id 1.

For creation of a resource, only config attributes need to be provided in the form elements.

The request needs to have the ID of the resource that is being created. Absence of an ID in the request will cause it to fail. The REST service will assume that the resource is provided in its entire state for the provision.

The response to a Create Request will contain the details of the newly created resource if it was a success.

3.2.2 Create Response

The response to a create request returns the newly created resource along with a link to it. The link can be used to get the details of the resource.

<?xml version="1.0"> 
<root>
	<status> 
	</status> 
	<resource id="1" href="....">
		<attr1></attr1>
		<attr2></attr2>
		...
		<attr3 href="....">id</attr3>
	</resource> 
</root>

3.3 Modify Resource

3.3.1 Modify Request

A resource can be modified or updated using the HTTP method POST.

The resource URI for modifying an object needs to be provided as:

/rest/<resource>/<id>

For e.g., /rest/routingtable/1 -->modifies an existing call route table with id 1.

For a modify, the user has a choice to send the whole resource (all configuration attributes) or just the attributes that are being modified. If the resource contains only the set of the attributes to be modified, the server will apply the changes on top of the existing values for the other attributes in the resource. This is done so that the resource is preserved in its current state and the updated attributes are applied to the current state of the resource, instead of applying the default values for the attributes that are not being updated.

For e.g., if the client wants to enable or disable a resource, the request can just contain the appropriate attribute to enable or disable the resource, and all other attributes will hold their current value.

The response to a modify resource request will contain the details of the modified resource if the request was a success. The resource will represent the new state of the resource.

3.3.2 Modify Response

The response to a modify request returns the whole resource in its new state.

<?xml version="1.0">
<root>
	<status> 
	</status> 
	<resource id="1" href="....">
		<attr1></attr1>
		<attr2></attr2>
		<attr3 href="....">id</attr3>
		....
		....
	</resource>
</root>

3.4 Delete Resource

3.4.1 Request

A resource can be deleted from the system using the HTTP method DELETE.

The resource URI for deleting an object needs to be provided as:

/rest/<resource>/<id>

For e.g., /rest/routingtable/1 --> deletes an existing call route table with id 1.

The response to a delete resource request will contain only a status block, indicating a success or failure.

3.4.2 Delete Response

The response to a delete request has only a status block. There is no resource data to be provided.

<?xml version="1.0">
<root>
	<status> 
		....
	</status>
</root>

3.5 Actions on Resources

3.5.1 Action Request

A resource can have actions performed on it. Actions can be performed on a resource by passing the action name as a value to the query parameter "action" in the resource URI. The permitted actions for a resource will be documented.

The HTTP method needs to be POST.

The resource URI for performing an action on a resource needs to be provided as:

/rest/<resource>/<id>?action=<action name>

For e.g., /rest/system?action=reboot--> performs "reboot" action on the system resource

If an action requires certain attributes, they need to be provided in the request as POST parameters. The list of attributes for every action is documented.

The response to an action on a resource usually contains only the status block. There is no resource returned as a response to an action. There are very few exceptions where the response to an action on a resource returns the same/different resource. If the action failed, the status would contain the error code, otherwise it would report a success.

3.5.2 Action Response

The response to an action request contains just the status block showing success or error.

<?xml version="1.0">
<root>
	<status> 
		....
	</status> 
</root>

Space shortcuts

Page tree