RESTCONF API Methods and Message Headers

In this section:

Introduction

Objects in the system are represented as resources, which are 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 look-up, create, modify and delete on the resources in RESTCONF API series. The response to a REST request will be in XML format, containing a status block and a resource block where applicable.

REST API Methods

The REST API operations are HTTP methods which helps retrieve the information.

The table below lists the REST API operations:

Operations	Description
GET	Fetches a resource. GET supports the following query parameters: Deep: Retrieves a resource with all sub resources inline. Shallow: Retrieves a resource with no sub resources inline. Offset: Specifies a limited set of list entries to retrieve. Limit: Specifies a limited set of list entries to retrieve. Select : Select which nodes and sub resources in a resource to retrieve.
POST	Creates a resource and performs an action.The operations are exposed as resources that accept a POST method
PUT	Creates or replace a resource
PATCH	Updates multiple leafs of a resource
DELETE	Removes or deletes a resource

GET

Description: The GET method retrieves information identified by the Request URI.This request is valid only when the user has read access of the resource.The GET method is used to view the resource's configuration and state data. The state data resides in any yang spec list that includes the “config false;” statement.

Media Type:application/vnd.yang.data+xml

Response Format

curl -u admin:admin  -i https://sbxhost/api/config/addressContext/default/zone

HTTP/1.1 200 OK
Server: ConfD
Cache-control: private, no-cache, must-revalidate, proxy-revalidate
Date: Tue, 07 Jan 2014 10:03:12 GMT
Content-Type: application/vnd.yang.data+xml
Transfer-Encoding: chunked
 
<collection xmlns:y="http://tail-f.com/ns/rest">
  <zone xmlns="http://sonusnet.com/ns/mibs/SONUS-ZONE/1.0" y:self="/api/config/addressContext/default/ZONE:zone/defaultSigZone">
    <name>defaultSigZone</name>
    <id>1</id>
    <cac y:self="/api/config/addressContext/default/ZONE:zone/defaultSigZone/cac">
      <ingress y:self="/api/config/addressContext/default/ZONE:zone/defaultSigZone/cac/ingress">
      </ingress>
      <egress y:self="/api/config/addressContext/default/ZONE:zone/defaultSigZone/cac/egress">
      </egress>
    </cac>
    <messageManipulation y:self="/api/config/addressContext/default/ZONE:zone/defaultSigZone/messageManipulation">
    </messageManipulation>
    <y:operations y:path="/addressContext/ZONE:zone">
      <sipSigPortResetAll y:self="/api/config/addressContext/default/ZONE:zone/defaultSigZone/_operations/sipSigPortResetAll"/>
      <sipSigConnResetAll y:self="/api/config/addressContext/default/ZONE:zone/defaultSigZone/_operations/sipSigConnResetAll"/>
      <sipArsEndpointRecoveryAll y:self="/api/config/addressContext/default/ZONE:zone/defaultSigZone/_operations/sipArsEndpointRecoveryAll"/>
      <sipArsEndpointRecoveryByIp y:self="/api/config/addressContext/default/ZONE:zone/defaultSigZone/_operations/sipArsEndpointRecoveryByIp"/>
    </y:operations>
  </zone>
</collection>

Response Status block

SBC shall respond with 200 OK, for a valid GET request on resource which the user has read access.

Error scenarios

Scenarios 1: If the user does not have read access on the resource, SBC returns HTTP error code 403 forbidden.

Scenarios 2: If the resource requested doesn’t exist, SBC returns HTTP error code 404 Page Not Found.

Scenarios 3: If the resource xpath requested doesn’t exist and the user doesn’t have access rights to the xpath, then SBC returns HTTP error code 403 forbidden

Query parameters For GET Request

Parameter: Deep

Deep is used to retrieve all sub resources inline. When it receives a GET request with deep query parameter, SBC respond with all the sub resources associated with the URI.

Example: Deep

curl -s -k -u admin:secret -i https://10.54.170.51/api/config/addressContext/default/zone/defaultSigZone?deep

HTTP/1.1 200 OK
Date: Tue, 25 Feb 2014 13:41:45 GMT
Server: ConfD
Cache-control: private, no-cache, must-revalidate, proxy-revalidate
Content-Type: application/vnd.yang.data+xml
Via: 1.1 169.254.99.1
Transfer-Encoding: chunked

<zone xmlns="http://sonusnet.com/ns/mibs/SONUS-ZONE/1.0" y:self="/api/config/addressContext/default/ZONE:zone/defaultSigZone" xmlns="http://sonusnet.com/ns/mibs/SONUS-ZONE/1.0" xmlns:y="http://tail-f.com/ns/rest" xmlns:ZONE="http://sonusnet.com/ns/mibs/SONUS-ZONE/1.0" xmlns:ADDRESS_CONTEXT="http://sonusnet.com/ns/mibs/SONUS-ADDRESS-CONTEXT/1.0"
 
y:path="/ADDRESS_CONTEXT:addressContext%5BADDRESS_CONTEXT:name%3D%27default%27%5D/ZONE:zone%5BZONE:name%3D%27defaultSigZone%27%5D">
 <name>defaultSigZone</name>
 <id>1</id>
 <cac y:self="/api/config/addressContext/default/ZONE:zone/defaultSigZone/cac">
 <callLimit>5555</callLimit>
 <ingress y:self="/api/config/addressContext/default/ZONE:zone/defaultSigZone/cac/ingress">
 </ingress>
 <egress y:self="/api/config/addressContext/default/ZONE:zone/defaultSigZone/cac/egress">
 </egress>
 </cac>
 <messageManipulation y:self="/api/config/addressContext/default/ZONE:zone/defaultSigZone/messageManipulation">
 </messageManipulation>
</zone>

Parameter: Shallow

Shallow is used to retrieve all sub resources inline. When it receives a GET request with shallow query parameter, SBC responds with the resource requested associated with the URI excluding any sub resource.

Example: Shallow

curl -s -k -u admin:secret -i https://10.54.170.51/api/config/addressContext/default/zone/defaultSigZone?shallow

HTTP/1.1 200 OK
Date: Tue, 25 Feb 2014 13:43:10 GMT
Server: ConfD
Cache-control: private, no-cache, must-revalidate, proxy-revalidate
Content-Type: application/vnd.yang.data+xml
Via: 1.1 169.254.99.1
Transfer-Encoding: chunked

<zone xmlns="http://sonusnet.com/ns/mibs/SONUS-ZONE/1.0" 
y:self="/api/config/addressContext/default/ZONE:zone/defaultSigZone" 
xmlns="http://sonusnet.com/ns/mibs/SONUS-ZONE/1.0" 
xmlns:y="http://tail-f.com/ns/rest" 
xmlns:ZONE="http://sonusnet.com/ns/mibs/SONUS-ZONE/1.0" 
xmlns:ADDRESS_CONTEXT="http://sonusnet.com/ns/mibs/SONUS-ADDRESS-CONTEXT/1.0"
 
y:path="/ADDRESS_CONTEXT:addressContext%5BADDRESS_CONTEXT:name%3D%27default%27%5D/ZONE:zone%5BZONE:name%3D%27defaultSigZone%27%5D">
 <name>defaultSigZone</name>
 <id>1</id>
 <cac y:self="/api/config/addressContext/default/ZONE:zone/defaultSigZone/cac"/>
 <messageManipulation y:self="/api/config/addressContext/default/ZONE:zone/defaultSigZone/messageManipulation"/>
</zone>

Parameter: Offset

Offset is used by REST clients to specify a limited set of entries when fetching list entries. Offset is used to specify the starting index of a list of resources. The first entry’s offset value is zero. The example lists zones from offset 3.

Example: Offset

curl -u admin:admin  -i 'https://sbxhost/api/running/addressContext/AC-2/zone?offset=3'

HTTP/1.1 200 OK
Server: ConfD
Cache-control: private, no-cache, must-revalidate, proxy-revalidate
Date: Tue, 07 Jan 2014 13:31:08 GMT
Content-Type: application/vnd.yang.data+xml
Transfer-Encoding: chunked

 <collection xmlns:y="http://tail-f.com/ns/rest">
  <zone xmlns="http://sonusnet.com/ns/mibs/SONUS-ZONE/1.0" y:self="/api/running/addressContext/AC-2/ZONE:zone/ZON-2-4">
    <name>ZON-2-4</name>
    <id>5</id>
    <cac y:self="/api/running/addressContext/AC-2/ZONE:zone/ZON-2-4/cac">
      <ingress y:self="/api/running/addressContext/AC-2/ZONE:zone/ZON-2-4/cac/ingress">
      </ingress>
      <egress y:self="/api/running/addressContext/AC-2/ZONE:zone/ZON-2-4/cac/egress">
      </egress>
    </cac>
    <messageManipulation y:self="/api/running/addressContext/AC-2/ZONE:zone/ZON-2-4/messageManipulation">
    </messageManipulation>
    <y:operations y:path="/addressContext/ZONE:zone">
      <sipSigPortResetAll y:self="/api/running/addressContext/AC-2/ZONE:zone/ZON-2-4/_operations/sipSigPortResetAll"/>
      <sipSigConnResetAll y:self="/api/running/addressContext/AC-2/ZONE:zone/ZON-2-4/_operations/sipSigConnResetAll"/>

      <sipArsEndpointRecoveryAll 
y:self="/api/running/addressContext/AC-2/ZONE:zone/ZON-2-4/_operations/sipArsEndpointRecoveryAll"/>

      <sipArsEndpointRecoveryByIp 
y:self="/api/running/addressContext/AC-2/ZONE:zone/ZON-2-4/_operations/sipArsEndpointRecoveryByIp"/>
    </y:operations>
  </zone>
</collection>

Parameter: Limit

Query parameter limit is used by REST clients to limit the number of entries when fetching list entries. Limit specifies the number of entries that needs to be fetched.

Example: Limit

curl -u admin:admin  -i 'https://sbxhost/api/running/addressContext/AC-2/zone?limit=2'

HTTP/1.1 200 OK
Server: ConfD
Cache-control: private, no-cache, must-revalidate, proxy-revalidate
Date: Tue, 07 Jan 2014 13:38:30 GMT
Content-Type: application/vnd.yang.data+xml
Transfer-Encoding: chunked

 <collection xmlns:y="http://tail-f.com/ns/rest">
  <zone xmlns="http://sonusnet.com/ns/mibs/SONUS-ZONE/1.0" y:self="/api/config/addressContext/AC-2/ZONE:zone/ZON-2">
    <name>ZON-2</name>
    <id>2</id>
    <cac y:self="/api/config/addressContext/AC-2/ZONE:zone/ZON-2/cac">
      <ingress y:self="/api/config/addressContext/AC-2/ZONE:zone/ZON-2/cac/ingress">
      </ingress>
      <egress y:self="/api/config/addressContext/AC-2/ZONE:zone/ZON-2/cac/egress">
      </egress>
    </cac>
    <messageManipulation y:self="/api/config/addressContext/AC-2/ZONE:zone/ZON-2/messageManipulation">
    </messageManipulation>

    <sipTrunkGroup 
xmlns="http://sonusnet.com/ns/mibs/SONUS-SIP-TRUNK-GROUP/1.0" 
y:self="/api/config/addressContext/AC-2/ZONE:zone/ZON-2/SIP_TRUNK_GROUP:sipTrunkGroup/SIPTG-2">
      <name>SIPTG-2</name>
    </sipTrunkGroup>
    <y:operations y:path="/addressContext/ZONE:zone">
      <sipSigPortResetAll y:self="/api/config/addressContext/AC-2/ZONE:zone/ZON-2/_operations/sipSigPortResetAll"/>
      <sipSigConnResetAll y:self="/api/config/addressContext/AC-2/ZONE:zone/ZON-2/_operations/sipSigConnResetAll"/>

      <sipArsEndpointRecoveryAll 
y:self="/api/config/addressContext/AC-2/ZONE:zone/ZON-2/_operations/sipArsEndpointRecoveryAll"/>

      <sipArsEndpointRecoveryByIp 
y:self="/api/config/addressContext/AC-2/ZONE:zone/ZON-2/_operations/sipArsEndpointRecoveryByIp"/>
    </y:operations>
  </zone>
  <zone xmlns="http://sonusnet.com/ns/mibs/SONUS-ZONE/1.0" y:self="/api/config/addressContext/AC-2/ZONE:zone/ZON-2-2">
    <name>ZON-2-2</name>
    <id>3</id>
    <cac y:self="/api/config/addressContext/AC-2/ZONE:zone/ZON-2-2/cac">
      <ingress y:self="/api/config/addressContext/AC-2/ZONE:zone/ZON-2-2/cac/ingress">
      </ingress>
      <egress y:self="/api/config/addressContext/AC-2/ZONE:zone/ZON-2-2/cac/egress">
      </egress>
    </cac>
    <messageManipulation y:self="/api/config/addressContext/AC-2/ZONE:zone/ZON-2-2/messageManipulation">
    </messageManipulation>
    <y:operations y:path="/addressContext/ZONE:zone">
      <sipSigPortResetAll y:self="/api/config/addressContext/AC-2/ZONE:zone/ZON-2-2/_operations/sipSigPortResetAll"/>
      <sipSigConnResetAll y:self="/api/config/addressContext/AC-2/ZONE:zone/ZON-2-2/_operations/sipSigConnResetAll"/>

      <sipArsEndpointRecoveryAll 
y:self="/api/config/addressContext/AC-2/ZONE:zone/ZON-2-2/_operations/sipArsEndpointRecoveryAll"/>

      <sipArsEndpointRecoveryByIp 
y:self="/api/config/addressContext/AC-2/ZONE:zone/ZON-2-2/_operations/sipArsEndpointRecoveryByIp"/>
    </y:operations>
  </zone>
</collection>

Parameter: Select

Query parameter select is used to fetch nodes or sub resources to be retrieved selectively. Multiple fields is selected using semicolon as separation.

To select Multiple fields : fields1;fields2

To selet a node b" that is nested within node "a": Use "a/b"

To select a node "c" nested within "b":"a/b/c"

Specify node sub selectors to request only specific sub nodes by placing expressions in parentheses "( )" after any selected node.

Example: Select

curl -u admin:admin  -i 'https://sbxhost/api/config/addressContext/AC-2/zone?select=name'

HTTP/1.1 200 OK
Server: ConfD
Cache-control: private, no-cache, must-revalidate, proxy-revalidate
Date: Tue, 07 Jan 2014 14:04:35 GMT
Content-Type: application/vnd.yang.data+xml
Transfer-Encoding: chunked

 <collection xmlns:y="http://tail-f.com/ns/rest">
  <zone xmlns="http://sonusnet.com/ns/mibs/SONUS-ZONE/1.0" y:self="/api/config/addressContext/AC-2/ZONE:zone/ZON-2">
    <name>ZON-2</name>
  </zone>
  <zone xmlns="http://sonusnet.com/ns/mibs/SONUS-ZONE/1.0" y:self="/api/config/addressContext/AC-2/ZONE:zone/ZON-2-2">
    <name>ZON-2-2</name>
  </zone>
  <zone xmlns="http://sonusnet.com/ns/mibs/SONUS-ZONE/1.0" y:self="/api/config/addressContext/AC-2/ZONE:zone/ZON-2-3">
    <name>ZON-2-3</name>
  </zone>
  <zone xmlns="http://sonusnet.com/ns/mibs/SONUS-ZONE/1.0" y:self="/api/config/addressContext/AC-2/ZONE:zone/ZON-2-4">
    <name>ZON-2-4</name>
  </zone>
</collection>

POST

Description: A POST operation is used to create a resource or call an operation. The POST method executes RPCs defined in tailf:action or yang RPC. The inputs needed for executing the RPC is sent as body of the POST request.

Post to create resource

Media type: application/vnd.yang.operations+xml

Response format

curl -u admin:admin -XPOST -i https://sbxhost/api/config/ -H 'Content-type: application/vnd.yang.datastore+xml' --data '
    <addressContext>
        <name>AC_101</name>
    </addressContext>'

HTTP/1.1 201 Created
Server: ConfD
Location: https://sbxhost/api/config/addressContext/AC_101
Cache-control: private, no-cache, must-revalidate, proxy-revalidate
Date: Tue, 07 Jan 2014 14:16:50 GMT
Content-Length: 0
Content-Type: text/html

Response status block

The SBC responds to a successful POST request with the 201 Created.

The response then has new/modified resource definition.

Error scenarios

Scenarios 1: If the user does not have read access on the resource, SBC returns HTTP error code 403 forbidden.

Scenarios 2: If the resource requested doesn’t exist, SBC returns HTTP error code 404 Page Not Found.

Scenarios 3: If the resource xpath requested doesn’t exist and the user doesn’t have access rights to the xpath, then SBC returns HTTP error code 403 forbidden

Post to execute the resource

Description: The POST method is used to execute RPCs that are defined "tailf:action" or yang RPC. The inputs needed for executing the RPC is sent as body of the POST request

Media type: application/vnd.yang.operations+xml

Response format

curl -u admin:admin -X POST  -i https://sbxhost/api/config/addressContext/AC200/_operations/sipRegCountReset -H 'Content-type: application/vnd.yang.data+xml' --data  '<sipRegCountReset/>'
 
curl -u admin:admin -X POST  -i 'https://sbxhost/api/config/addressContext/AC_601/_operations/sipRegistrationDeleteById' -H 'Content-Type: application/vnd.yang.data+xml' --data '
    <sipRegistrationDeleteById>
        <id>1</id>
    </sipRegistrationDeleteById>'

Response status block

The SBC responds to a successful POST request with the 201 Created.

This is regardless of the status of the action executed. Even if the action fails, the status returned will be 200 OK. The response then has new/modified resource definition.

Error scenarios

Scenarios 1: If the user does not have read access on the resource, SBC returns HTTP error code 403 forbidden.

Scenarios 2: If the resource requested doesn’t exist, SBC returns HTTP error code 404 Page Not Found.

Scenarios 3: If the resource xpath requested doesn’t exist and the user doesn’t have access rights to the xpath, then SBC returns HTTP error code 403 forbidden

PUT

Description: The PUT request is used to replace a resource

Media type:application/vnd.yang.data+xml

Response format

curl -u admin:admin -XPUT -i https://sbxhost/api/config/addressContext -H 'Content-type: application/vnd.yang.data+xml' --data '
    <addressContext>
        <name>AC_102</name>
    </addressContext>'

HTTP/1.1 204 No Content
Server: ConfD
Cache-control: private, no-cache, must-revalidate, proxy-revalidate
Date: Tue, 07 Jan 2014 14:23:08 GMT
Content-Length: 0
Content-Type: text/html

Response status block

The SBC responds to a valid for a valid PUT request on resource which the user has write access with 204 No Content

Error scenarios

Scenarios 1: If the user does not have read access on the resource, SBC returns HTTP error code 403 forbidden.

Scenarios 2: If the resource requested doesn’t exist, SBC returns HTTP error code 404 Page Not Found.

Scenarios 3: If the resource xpath requested doesn’t exist and the user doesn’t have access rights to the xpath, then SBC returns HTTP error code 403 forbidden

PATCH

Description: The PATCH request is used to update a resource.

Media type: application/vnd.yang.data+xml.

Response format

curl -u admin:admin -XPATCH -i https://sbxhost/api/config/addressContext -H 'Content-type: application/vnd.yang.data+xml' --data '
   <addressContext>
      <name>AC_102</name>
      <ipInterfaceGroup>
        <name>IP_INT_GRP_102</name>
      </ipInterfaceGroup>
   </addressContext>'

HTTP/1.1 204 No Content
Server: ConfD
Cache-control: private, no-cache, must-revalidate, proxy-revalidate
Date: Tue, 07 Jan 2014 14:32:31 GMT
Content-Length: 0
Content-Type: text/html

Response status block

The SBC responds to a valid for a valid PATCH request on resource which the user has write access with 204 No Content

Error scenarios

Scenarios 1: If the user does not have read access on the resource, SBC returns HTTP error code 403 forbidden.

Scenarios 2: If the resource requested doesn’t exist, SBC returns HTTP error code 404 Page Not Found.

Scenarios 3: If the resource xpath requested doesn’t exist and the user doesn’t have access rights to the xpath, then SBC returns HTTP error code 403 forbidden

DELETE

Description: The Delete request is used to delete a resource.

Media type: Not required.

Response format

curl -u admin:admin -XDELETE -i 'https://sbxhost/api/config/addressContext/AC_102'

HTTP/1.1 204 No Content
Server: ConfD
Cache-control: private, no-cache, must-revalidate, proxy-revalidate
Date: Tue, 07 Jan 2014 14:34:27 GMT
Content-Length: 0
Content-Type: text/html

Response status block

The SBC responds to a valid for a valid DELETE request on resource which the user has delete permission, with 204 No Content

Error scenarios

Scenarios 1: If the user does not have read access on the resource, SBC returns HTTP error code 403 forbidden.

Scenarios 2: If the resource requested doesn’t exist, SBC returns HTTP error code 404 Page Not Found.

Scenarios 3: If the resource xpath requested doesn’t exist and the user doesn’t have access rights to the xpath, then SBC returns HTTP error code 403 forbidden

Message Headers

Description: The SBC supports uses the headers in response to the REST API call.

The Headers supported include:

Accept : The Accept request-header field specifies the media types which are acceptable for the response by the client (supported in Request).

Content-Type: The media type of the request body(supported in Request and Response)

SBC supports the following media types: application/vnd.yang.api+xml application/vnd.yang.data+xml application/vnd.yang.datastore+xml.

The data accessible through well-known URI /api, uses media type application/vnd.yang.api+xml .The resources available in root (/) are of type application/vnd.yang.datastore+xml. The resources found in non-root path shall be of type application/vnd.yang.data+xml.

Host: The host address of the server (supported in Request).

Location: The resource identifier for a newly created resource (supported in response only).

Page tree

RESTCONF API Methods and Message Headers

Introduction

REST API Methods

GET

Response Format

Response Status block

Error scenarios

Query parameters For GET Request

Parameter: Deep

Parameter: Shallow

Parameter: Offset

Parameter: Limit

Parameter: Select

POST

Post to create resource

Response format

Response status block

Error scenarios

Post to execute the resource

Response format

Response status block

Error scenarios

PUT

Response format

Response status block

Error scenarios

PATCH

Response format

Response status block

Error scenarios

DELETE

Response format

Response status block

Error scenarios

Message Headers