Northbound interface:RESTful
(→HTTP headers) |
|||
| Line 1: | Line 1: | ||
| − | |||
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. | ||
| Line 6: | Line 5: | ||
Reference: [http://en.wikipedia.org/wiki/RESTful Wikipedia] | Reference: [http://en.wikipedia.org/wiki/RESTful Wikipedia] | ||
| − | + | = TelcoBridges RESTful Northbound Interface = | |
As of Release 2.9, TelcoBridges gateways support a RESTful configuration interface using JSON for data exchange. | 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: | TelcoBridges supports the following RFCs for RESTful API: | ||
| Line 31: | Line 30: | ||
|} | |} | ||
| − | == | + | == REST API overview == |
| − | + | === Supported Methods === | |
| − | + | ==== GET ==== | |
List collection entries | List collection entries | ||
GET /users | GET /users | ||
| Line 42: | Line 41: | ||
<- Content : {"name":"root","user_group":"Admin","pass":"Not Shown"} | <- Content : {"name":"root","user_group":"Admin","pass":"Not Shown"} | ||
<- Code : HTTP/1.0 200 OK | <- Code : HTTP/1.0 200 OK | ||
| − | + | ==== PUT ==== | |
Update a configuration entry | Update a configuration entry | ||
PUT /users/root | PUT /users/root | ||
-> Content : {"pass":"MyNewSecret"} | -> Content : {"pass":"MyNewSecret"} | ||
<- Code : HTTP/1.0 200 OK | <- Code : HTTP/1.0 200 OK | ||
| − | + | ==== POST ==== | |
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 a configuration entry from a collection | Delete a configuration entry from a collection | ||
DELETE /users/RogerFluffy | DELETE /users/RogerFluffy | ||
<- Code : HTTP/1.0 200 OK | <- 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. | 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''': | ||
| Line 66: | Line 65: | ||
/configurations/MyCFG/routes | /configurations/MyCFG/routes | ||
| − | + | === Collections === | |
URI 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. | ||
| Line 82: | Line 81: | ||
<- 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. | The following result class are used to as HTTP status code to indicate the result of request. | ||
* 2XX - success | * 2XX - success | ||
| Line 97: | Line 96: | ||
This ''message'' can be used to find the exact reason why a RESTful API call failed. | 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: | The following HTTP header should be used in requests: | ||
{| border="1" | {| border="1" | ||
| Line 165: | Line 164: | ||
| To be ignored | | To be ignored | ||
|} | |} | ||
| + | |||
| + | == API Access == | ||
| + | === HTTP port === | ||
| + | The HTTP port for RESTful access is the same as for the Web interface. By default, the port is 12358. | ||
| + | |||
| + | === 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. | ||
Revision as of 14:45, 23 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
Contents |
TelcoBridges RESTful 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 |
REST 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
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, the port is 12358.
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.
