Northbound interface:RESTful

From TBwiki
(Difference between revisions)
Jump to: navigation, search
Line 2: Line 2:
 
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.
 
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.
+
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: [http://en.wikipedia.org/wiki/RESTful Wikipedia]
 
Reference: [http://en.wikipedia.org/wiki/RESTful Wikipedia]
Line 36: Line 36:
 
List collection entries
 
List collection entries
 
   GET /users
 
   GET /users
 +
  <- Content : {"root":{}}
 
   <- Code    : HTTP/1.0 200 OK
 
   <- Code    : HTTP/1.0 200 OK
−
  <- Content : {"root":{}}
 
 
Read a specific configuration entry
 
Read a specific configuration entry
 
   GET /users/root
 
   GET /users/root
−
  <- Code    : HTTP/1.0 200 OK
 
 
   <- Content : {"name":"root","user_group":"Admin","pass":"Not Shown"}
 
   <- Content : {"name":"root","user_group":"Admin","pass":"Not Shown"}
 +
  <- Code    : HTTP/1.0 200 OK
 
===== PUT =====
 
===== PUT =====
 
Update a configuration entry
 
Update a configuration entry
Line 50: Line 50:
 
Create a configuration entry into a collection
 
Create a configuration entry into a collection
 
   POST /users
 
   POST /users
−
   -> Content : {"name":"RogerFluffy","user_group":"nobody","pass":"xyz"}
+
   -> Content : { "name" : "RogerFluffy", "user_group" : "nobody" , "pass" : "xyz" }
 
   <- Code    : HTTP/1.0 200 OK
 
   <- Code    : HTTP/1.0 200 OK
 
===== DELETE =====
 
===== DELETE =====
Line 57: Line 57:
 
   <- Code    : HTTP/1.0 200 OK
 
   <- Code    : HTTP/1.0 200 OK
 
==== Entries ====
 
==== Entries ====
−
Entries are found under collection paths.  A collection is generally composed of multiple entries, with a different name for each entry.   
+
Entries are found under collection URIs.  A collection is generally composed of multiple entries, with a different name for each entry.   
 
The entry name must be provided during the '''POST''':
 
The entry name must be provided during the '''POST''':
 
   POST /users
 
   POST /users
−
   -> Content : { "name":"RogerFluffy", ... }
+
   -> Content : { "name" : "RogerFluffy", ... }
 
   <- Code    : HTTP/1.0 200 OK
 
   <- Code    : HTTP/1.0 200 OK
  
−
Entries generally have attributes, and can also include collections.  For example, for the configuration entry ''MyCFG'', we can find the ''routes'' collection using the follwoing path:
+
Entries generally have attributes, and can also include collections.  For example, for the configuration entry ''MyCFG'', we can find the ''routes'' collection using the following URI:
 
   /configurations/MyCFG/routes
 
   /configurations/MyCFG/routes
  
 
==== Collections ====
 
==== Collections ====
−
Paths with the plural form generally represent a collection of entries.
+
URI with the plural form generally represent a collection of entries.
 
A collection can be composed of mutiple entries, or limited to 1.
 
A collection can be composed of mutiple entries, or limited to 1.
  
−
For example, the path where users configuration entries are grouped into is  
+
For example, the URI where users configuration entries are grouped into is  
 
   /users
 
   /users
 
Likewise, the list of routes can be found on
 
Likewise, the list of routes can be found on
Line 82: Line 82:
 
   <- Code    : HTTP/1.0 200 OK
 
   <- Code    : HTTP/1.0 200 OK
  
 +
==== 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.
  
−
==== JSON status message ====
 
−
==== HTTP status code ====
 
 
==== HTTP headers ====
 
==== HTTP headers ====
 +
Depending on the context, the following HTTP header must be used for requests:
 +
{| border="1"
 +
|-
 +
! HTTP Header
 +
! GET
 +
! PUT
 +
! POST
 +
! DELETE
 +
|-
 +
| Content-Type
 +
|
 +
|
 +
|
 +
|
 +
|-
 +
| User-Agent
 +
|
 +
|
 +
|
 +
|
 +
|-
 +
| Set-cookie
 +
|
 +
|
 +
|
 +
|
 +
|-
 +
| Connection
 +
|
 +
|
 +
|
 +
|
 +
|}

Revision as of 16:59, 18 November 2015

Contents

RESTfull

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 RESTfull Northbound Interface

As of Release 2.9, TelcoBridges gateways support a RESTful configuration interface using JSON for data exchange.

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

API overview

Supported Methods

GET

List collection entries 

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

Read a specific configuration entry 

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

Update a configuration entry 

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

Create a configuration entry into a collection 

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

Delete a configuration entry from a collection 

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

Entries

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

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

Entries generally have attributes, and can also include collections. For example, for the configuration entry 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 entries. A collection can be composed of mutiple entries, or limited to 1.

For example, the URI where users configuration entries are grouped into is 

 /users

Likewise, the list of routes can be found on 

 /configurations/MyCFG/routes

When the collection is limited to 1 entry, the entry name is fixed. For example, only one H.248 stack can be defined, therefore the name is fixed to gateway_h248 The entry 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

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

Depending on the context, the following HTTP header must be used for requests:

HTTP Header GET PUT POST DELETE
Content-Type
User-Agent
Set-cookie
Connection
Retrieved from "https://docs.telcobridges.com/mediawiki/index.php?title=Northbound_interface:RESTful&oldid=19643"
Personal tools