# RESTful API

## TelcoBridges HTTP RESTful Northbound Interface

The [RESTful API](http://en.wikipedia.org/wiki/Representational_state_transfer) is used to provision a Tmedia VoIP gateway or a Tdev development platform. The configuration of the device is seen as collections of resources than can be queried and modified through this interface.

HTTP requests are sent to the [web server](/appendices/appendix-a-glossary/glossary-toolpack/glossary-web-server.md) using standard HTTP methods(e.g., GET, PUT, POST, or DELETE). Data exchanged in requests and responses is in [JSON](http://en.wikipedia.org/wiki/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

| <p><br>Resource</p>                                                                                                                                                                                                                   | <p><br>GET</p>                                                                                                                                                                             | <p><br>PUT</p>                                                                                | <p><br>POST</p>                         | <p><br>DELETE</p>                             |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- | --------------------------------------- | --------------------------------------------- |
| <p>Collection URI<br><code>[http://host:port/@\[collection\_name\]/](https://prosbcdocs.telcobridges.com/tools-tips-and-tricks/http:/host:port/@\[collection_name])</code></p>                                                        | List the resources that are part of the collection.                                                                                                                                        | Not used.                                                                                     | Create a new element in the collection. | Not used.                                     |
| <p>Element URI<br><code>[http://host:port/@\[collection\_name\]/@\[resource\_name](https://prosbcdocs.telcobridges.com/tools-tips-and-tricks/http:/host:port/@\[collection_name]/@\[resource_name)]</code></p>                        | 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 |
| <p>New Element URI<br><code>[http://host:port/@\[collection\_name\]/new](https://prosbcdocs.telcobridges.com/tools-tips-and-tricks/http:/host:port/@\[collection_name]/new)</code></p>                                                | 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                                           |
| <p>Status Element URI<br><code>[http://host:port/@\[collection\_name\]/@\[resource\_name\]/status](https://prosbcdocs.telcobridges.com/tools-tips-and-tricks/http:/host:port/@\[collection_name]/@\[resource_name]/status)</code></p> | Retrieve a JSON representation of the status of an element. This is only valid for elements in the active configuration, and it is not available for all element types.                    | N/A                                                                                           | N/A                                     | N/A                                           |

#### Supported Methods

**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"
      }
    }
```

Note : recursive GET does not apply to status elements.

**Recursive PUT/POST requests**

The recursivity of a PUT/POST 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":"", ...
        }, ...
      }
    }
```

#### Documentation

It is possible to get the documentation for the attributes of an element from a GET by using the documentation=true attribute on the URI, either for the collection, an element or a new element.

```
 GET /configurations?documentation=true
 GET /configurations/NewCFG?documentation=true
 GET /configurations/new?documentation=true
 -> Content : {
        "name": {
          "description" : "Name of this configuration.", 
          "type" : "text",
        },
        "notes": {
          "description" : "Free text field available to add any system/configuration information (this field is ignored by the system)", 
          "type" : "text",
        }, ...
      }
    }
```

**Recursive Documentation**

It is possible to get documentation recursively by using both the documentation=true and the recursive=yes attributes on the URI.

```
 GET /configurations?documentation=true&recursive=yes
 -> Content : { 
      "name": {
          "description" : "Name of this configuration.", 
          "type" : "text",
      }, 
      "notes": {
          "description" : "Free text field available to add any system/configuration information (this field is ignored by the system)", 
          "type" : "text",
      }, 
      "routes": { 
        "called": {
          "description" : "Called number to match this route. Leave empty to match any called number.", 
          "type" : "text",
        },
        "calling": {
          "description" : "Calling number to match this route. Leave empty to match any calling number.", 
          "type" : "6661314",
        }, ...
      }, ...
    }
```

#### 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"                                                                                                             |
| 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\://\[Management\_IP]: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.

## Application implementation example

The [tbconfig](/tools-tips-and-tricks/restful-api/tbconfig-examples.md) tools allows user to directly modify your system's configuration through multiple modes:

* cli
* shell
* command line

More information about [tbconfig tool here](/tools-tips-and-tricks/restful-api/tbconfig-examples.md)

## Ruby implementation example

This ruby script ([httprestapi](https://docs.telcobridges.com/w/images/5/5e/Httprestapi.zip)) is an example of how to use TelcoBridges RESTful Northbound Interface.

* The script can be executed from any computer having access to the management web interface.
* The script can also be copied on the internal host of a *T*media and executed from a SSH client (as shown in the examples below using 127.0.0.1:12358).

Please follow this link for more information: [Ruby Implementation Example](/tools-tips-and-tricks/restful-api/ruby-examples.md)

## Postman tool integration

Postman is an API(application programming interface) development tool provided by third party that helps to test APIs. Almost any functionality that could be needed by any developer is encapsulated in this tool. It has the ability to make various types of HTTP requests(GET, PUT, POST, DELETE).

* Postman tool is another example of how to use TelcoBridges RESTful Northbound Interface.
* The application tool can be run from any computer having access to the management web interface.

Please follow this link for more information: [Postman Tool Integration](/tools-tips-and-tricks/restful-api/postman-examples.md)

## Download Active Configuration

It is possible to download the current active configuration directly from the Web portal in a json file.\
Please follow this link to the forums to add this capability: [Download full Active Configuration](https://forum.prosbc.com/t/download-full-active-configuration-and-other-things-from-webgui-in-json-format/287)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://prosbcdocs.telcobridges.com/tools-tips-and-tricks/restful-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.