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.
2.1 Response Status Block
The status block in the response XML contains the following structure:
Present is all responses.
Standard HTTP code.
Present only if there are application errors.
There will be one of these tags for every application error for this request.
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
<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.
The resource block in the response XML contains the following structure:
Present only if a bulk lookup is performed, where multiple instances are listed.
Present only if a bulk lookup is performed without details=true query parameter.
Present if a bulk lookup with details=true query parameter is performed or if a single
Every resource attribute in the resource schema is shown as a separate tag.
This is present only when the resource attribute contains multiple instances of another resource.
This is present within a
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:
For lookup of a single object, the resource URL needs to be provided as:
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.
Tthere 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.
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.
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.
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.
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:
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.
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:
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.
3.4 Delete Resource
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:
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.
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:
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.