Actions

Northbound interface:RESTful: Difference between revisions

Line 283: Line 283:
=== HTTP port ===
=== HTTP port ===
The HTTP port for RESTful access is the same as for the Web interface.  By default, HTTP port is 12358.  
The HTTP port for RESTful access is the same as for the Web interface.  By default, HTTP port is 12358.  
Therefore the RESTful URIs should looks something like: http://TMG_IP_ADDR:12358/@[collection_name]/@[resource_name]
Therefore the RESTful URIs should looks something like: '''<br><nowiki>http://TMG_IP_ADDR:12358/@[collection_name]/@[resource_name]</nowiki>'''


=== Credentials ===
=== Credentials ===
The credentials (user/password) used to authenticate a RESTful client application are the same as for the WebPortal.   
The credentials (user/password) used to authenticate a RESTful client application are the same as for the WebPortal.   
Users can be managed from the Web interface under /users.  The same path is used to manage users by the RESTful interface.
Users can be managed from the Web interface under /users.  The same path is used to manage users by the RESTful interface.

Revision as of 15:19, 26 November 2015

In computing, Representational State Transfer (REST) is the software architectural style of the World Wide Web. REST gives a coordinated set of constraints to the design of components in a distributed hypermedia system that can lead to a higher-performing and more maintainable architecture.

To the extent that systems conform to the constraints of REST they can be called RESTful. RESTful systems typically, but not always, communicate over HTTP with the same HTTP verbs (GET, POST, PUT, DELETE, etc.) which web browsers use to retrieve web pages and to send data to remote servers. REST interfaces with external systems using resources identified by URI, for example /people/tom, which can be operated upon using standard verbs, such as DELETE /people/tom.

Reference: Wikipedia

TelcoBridges RESTful Northbound Interface

Introduced in version 2.9, the RESTful API allows the provisioning of a Tmedia VoIP gateway or a Tdev development platforman. The configuration of the device is seen as collections of resources than can be queried/modified through this interface.

HTTP requests are sent to the web server using standard HTTP methods(e.g., GET, PUT, POST, or DELETE). Data exchanged in requests and responses is in JSON format.

Supported RFCs

TelcoBridges supports the following RFCs for RESTful API:

Specification Supported
RFC 7159 The JavaScript Object Notation (JSON) Data Interchange Format Yes
Extensible Markup Language (XML) 1.0 (Fifth Edition) No
RFC 2617 HTTP Authentication: Basic and Digest Access Authentication Basic Scheme Only
RFC 2109 HTTP State Management Mechanism Yes

REST API overview

Supported Methods


Resource

GET

PUT

POST

DELETE

Collection URI
http://host:port/@[collection_name]/

List the resources that are part of the collection. Not used. Create a new element in the collection. Not used.

Element URI
http://host:port/@[collection_name]/@[resource_name]

Retrieve a JSON representation of the specified member of the collection. Modify the specified member of the collection according to the JSON data in the HTTP request. Not used. Delete the specified member of the collection

New Element URI
http://host:port/@[collection_name]/new

Retrieve a JSON representation of a new element of the collection with default values. This new element is not saved until a POST request is sent to create the element in the collection. N/A N/A N/A

GET

List elements of a collection

 GET /users
 <- Content : {"root":{}}
 <- Code    : HTTP/1.0 200 OK

Read a specific element

 GET /users/root
 <- Content : {"name":"root","user_group":"Admin","pass":"Not Shown"}
 <- Code    : HTTP/1.0 200 OK

PUT

Update a configuration element

 PUT /users/root
 -> Content : {"pass":"MyNewSecret"}
 <- Code    : HTTP/1.0 200 OK

Omitted attributes in a PUT are left unchanged on the server.

POST

Create a configuration element into a collection

 POST /users
 -> Content : { "name" : "RogerFluffy", "user_group" : "nobody" , "pass" : "xyz" }
 <- Code    : HTTP/1.0 200 OK

Omitted attributes in a POST are being set to the 'default' value.

DELETE

Delete a configuration element from a collection

 DELETE /users/RogerFluffy
 <- Code    : HTTP/1.0 200 OK

Elements

Elements are found under collection URIs. A collection is generally composed of multiple elements, with a different name for each element. The element name must be provided during the POST:

 POST /users
 -> Content : { "name" : "RogerFluffy", ... }
 <- Code    : HTTP/1.0 200 OK

Elements generally have attributes, and can also include collections. For example, for the configuration element MyCFG, we can find the routes collection using the following URI:

 /configurations/MyCFG/routes

Collections

URI with the plural form generally represent a collection of elements. A collection can be composed of mutiple elements, or limited to 1.

For example, configuration are found under the following collection URI

 /users

Likewise, the list of routes can be found on

 /configurations/MyCFG/routes

When the collection is limited to 1 element, the element name is fixed. For example, only one H.248 stack can be defined, therefore the name is fixed to gateway_h248 The element name must be NOT be provided during the POST:

 POST /configurations/MyCFG/h248_stacks
 -> Content : { "enabled" : true, "naps" : [ "NAP_TDM", "RTP_NAP"], ... }
 <- Code    : HTTP/1.0 200 OK

Recursivity

Non-recursive GET requests (default)

By default, requests are non-recursive. This means that when a GET request is made on a URI, only objects on that element will be returned.

 GET /configurations/NewCFG
 <- Content : {"name":"NewCFG", "notes":"This is a new demo configuration", "routes":{}, ... }

In the response, we see two attribute value pairs : name and notes, along with another object named routes. The later is a collection, and should be queried individually to get its sub-elements.

 GET /configurations/NewCFG/routes
 <- Content : {"Route1":{}, ...}
 GET /configurations/NewCFG/routes/Routes1
 <- Content : {"name":"Route1", "called":"5551212","calling":"", ...}

Recursive GET requests

It is possible to get all sub-elements from a GET by using the recursive=yes attribute on the URI.

 GET /configurations/NewCFG?recursive=yes
 <- Content : { 
      "name":"NewCFG", 
      "notes":"This is a new demo configuration", 
      "routes": { 
        "Route1": {
          "name":"Route1", 
          "called":"5551212",
          "calling":"", ...
        },
        "Route2": {
          "name":"Route2", 
          "called":"5551314",
          "calling":"", ...
        }, ...
      }
    }

This is also true to get the content of all elements of a collection

 GET /users?recursive=yes
 <- Content : {
      "RogerFluffy":{
        "name":"RogerFluffy",
        "user_group":"nobody",
        "pass":"Not Shown"
      },
      "root":{
        "name":"root",
        "user_group":"Admin",
        "pass":"Not Shown"
      }
    }

Recursive PUT/POST requests

The recusivity of a PUT/POST is depends on the content. It is possible to specify the content of all sub-elements under a URI. For example, to change the complete routing table, we could do something like:

 PUT /configurations/NewCFG/routes
 -> Content : {
        "Route1": {
          "name":"Route1", 
          "called":"5551212",
          "calling":"", ...
        },
        "Route2": {
          "name":"Route2", 
          "called":"5551314",
          "calling":"", ...
        }, ...
      }
    }

Or even change a complete configuration in a single PUT

 PUT /configurations/NewCFG
 -> Content : { 
      "name":"NewCFG", 
      "notes":"This is a new demo configuration", 
      "routes": { 
        "Route1": {
          "name":"Route1", 
          "called":"6661212",
          "calling":"", ...
        },
        "Route2": {
          "name":"Route2", 
          "called":"6661314",
          "calling":"", ...
        }, ...
      }
    }


Request Status code

The following result class are used to as HTTP status code to indicate the result of request.

* 2XX - success
* 3XX - redirection (304 Not Modified)
* 4XX - client error
* 5XX - server error

In Addition to HTTP status code, every HTTP response also inlcudes a JSON payload with a verbose message.

 POST /configurations/MyCFG/h248_stacks
 -> Content : { ... }
 <- Code    : HTTP/1.0 200 OK
 <- Content : { "message" : "Tbgw h248 cfg creation failed: Public ip address can't be blank, Public ip address is invalid, Local ip address is invalid, Local ip address When not using virtual ip, an ip address must be entered"}

This message can be used to find the exact reason why a RESTful API call failed.

HTTP headers

The following HTTP header should be used in requests:

HTTP Header Description
Host Mandatory
Authorization RFC2617 WWW Authentication, basic mode. Can be used on each requests, or first request only by using Cookie/Set-Cookie headers
Cookie RFC2109 HTTP Session management
Content-Type "application/json; charset=utf-8"
Content-Length Length of content for PUT and POST requests
User-Agent Optional
If-None-Match Optional (HTTP ETag/If-None-Match caching mechanism)
Cache-Control HTTP Cache control, use is optional
Connection "keep-alive"

The following HTTP header are to be expected for a server response:

HTTP Header Description
Authorization RFC2617 WWW Authentication
Set-Cookie RFC2109 HTTP Session management
Content-Type "application/json; charset=utf-8"
Content-Length Length of content
E-Tag Optional (HTTP ETag/If-None-Match caching mechanism)
Cache-Control Optional
Date Can be ignored
X-Runtime Can be ignored
X-Frame-Option To be ignored

API Access

HTTP port

The HTTP port for RESTful access is the same as for the Web interface. By default, HTTP port is 12358. Therefore the RESTful URIs should looks something like:
http://TMG_IP_ADDR:12358/@[collection_name]/@[resource_name]

Credentials

The credentials (user/password) used to authenticate a RESTful client application are the same as for the WebPortal. Users can be managed from the Web interface under /users. The same path is used to manage users by the RESTful interface.