~~Title: REST~~
====== REST ======
This API provides applications the ability to query and manage services available on the DuVoice system. The API is a collection of HTTP methods, all with URLs in the form **//<nowiki>http://<server>:10022/rest/RESOURCE</nowiki>//**.

This interface uses standard HTTP protocol and schemes in order to be used by the widest number of software languages and computer systems. It's been used by both C++, Python and PHP interfaces equally well.

A //resource// is defined as either a specific feature set or physical resource on the system. For example the [[dev:rest:api:config:system:home|system]] resource provides information about the local server including date, time, licensed features and product version details.

The mailbox is the basic unit for managing subscribers, guest rooms and system (auto attendant) menus within the DuVoice system. In cases of hospitality systems the mailbox number is typically configured to match the room number. In some cases it's configured as the primary extension number.

===== Internet Access =====
DuVoice does not recommend exposing the system directly to the internet. It should only be accessible via the local network or exposed via a firewall with rules which limit what machines or networks can access it.

===== Features =====
  * Wakeup call management.
  * Mailbox management.
  * User account control.
  * IVR integration
    * Room Status
    * Inventory (minibar).
  * Message delivery.
  * Custom prompt management.
  * Emergency Alerts.

===== Requirements =====
  * DuVoice 6.03.10 or above.

====== Basics ======

===== Authentication =====
Most all access is restricted using accounts which are configured either using System Configuration or Administration. Each account has access to only those resources associated with their tenant.

==== User based ====
The API provides a login/logout designed for a single user access application similar to InnDesk or phone application. When using these any connection using the same account will be disconnected upon another user logging on with the same username. Using this method is best when designing a base user application because additional permissions and reporting is performed by the server.

==== Server based ====
If your application is a server based, the use of login/logout is not necessary and authentication can be provided with each call using a user account and //Basic// authentication. Using this method will not force any existing user accounts to be disconnected.

===== Connection =====
^ HTTP Port | 10022 |
^ POST / PUT Content-Type | application/x-www-form-urlencoded |
^ Response Content-Type | application/json |
^ Result codes | Use of HTTP response codes only. |

===== Methods =====
The API uses standard HTTP methods to retrieve or manipulate data.

^ Method ^ Usage ^
| DELETE | Delete a resource. |
| GET | Get a resource. |
| POST | Create a new resource. |
| PUT | Update or replace an existing resource. |

===== Response =====
All responses are HTTP Content-Type //application/json//.

==== Headers ====
These header fields will always be returned.

^ Field ^ Description ^
| Date | Date of the response. |
| Connection | close |
| Content-Language | en |
| Server | Server version information. |
| Access-Control-Allow-Origin | * |
| Location | Address and port of the server. |
| Content-Type | Response content type. |
| Content-Length | Length of the content. |

=== Sample ===
<code yaml>
HTTP/1.1 OK 200
Date: Thu, 26 Sep 2019 22:05:10 GMT
Connection: Close
Content-Language: en
Server: DuVoice/6.03.32 DVREST/6.0.1
Access-Control-Allow-Origin: *
Location: 127.0.0.1:10022
</code>

==== Codes ====
The API uses standard HTTP reason codes to inform the caller if the request was performed correctly. Some methods and resources may define the meaning of a specific value, however most have standardized to the following.

^ Value ^ Reason ^ Description ^
| 200 | OK | Success |
| 401 | Unauthorized  | Resource requires the user be logged in. |
| 405 | Method not allowed | Method specified is not supported. |

====== Revision History ======

== 2021-03-25 ==
  * PUT for Rooms now supports JSON format.
  * Added support for setting custominfo, guestinfo, and roominfo. Only supported for rooms using PUT with JSON format.

== 2019-10-27 ==
  * Updated main overview page to include more information.
  * Added get started section with multiple examples.

== 2019-01-07 ==
  * Fully implemented and released as a public API in 6.03.10.

== 2017-10-31 ==
  * Initial limited release in 6.01.7.