Page History

Panel

In this section:

Table of Contents

maxLevel	4

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

Spacevars

0	product

. 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:

...

Code Block

lang	XML

<?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:

...

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.

...

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.

...

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:

...

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.

...

Code Block

lang	XML

<?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.

...

Code Block

lang	XML

<?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 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 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.

Code Block

lang	XML

<?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 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.

Code Block

lang	XML

<?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 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.

Code Block

lang	XML

<?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 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.

...

Space shortcuts

Page tree

Versions Compared

Old Version 2

New Version 3

Key

1. Introduction

2. Response Format

2.1 Response Status Block

2.1.1 How to obtain error message from code and params

2.2 Response Resource Block

3. Resource Methods

3.1 Lookup Resource(s)

3.1.1 Lookup Request

3.1.2 Bulk Lookup Response

3.1.3 Single Lookup Response

3.1.4 Categories of Resource Attributes

3.2 Create Resource

3.2.1 Create Request

3.2.2 Create Response

3.3 Modify Resource

3.3.1 Modify Request

3.3.2 Modify Response

3.4 Delete Resource

3.4.1 Request

3.4.2 Delete Response

3.5 Actions on Resources

3.5.1 Action Request

3.5.2 Action Response