REST API Documentation
On this page:
iSymphony provides a REST API that allows external applications and scripts to query and edit the configuration of the iSymphony server via HTTP requests. The REST API has many uses including, but not limited to, integrating iSymphony configuration into existing configuration systems, or auto provisioning of the iSymphony server. For example the iSymphony FreePBX module utilizes the REST API to synchronize the configuration between FreePBX and the iSymphony server.
HTTP Methods
The REST API utilizes several HTTP methods to control how the configuration is queried and modified. See the configuration resource pages for which methods are supported for the given resource.
GET | Used to query configuration resources from the server. |
PUT | Used to update configuration resources on the server. |
POST | Used to add configuration resources to the server. |
DELETE | Used to remove configuration resources from the server. |
HTTP Status Codes
The REST API will return specific HTTP status codes when accessing resources. Below are some of the more common status codes that the REST API will return. Some of the error status codes will be accompanied by more detail descriptions of issue in the response body.
200 - OK | Returned when a GET was successful. |
204 - No Content | Returned when a POST or PUT was successful. |
403 - Forbidden | Returned when the client does not have access to the REST system due to ACLs or invalid credentials. |
404 - Not Found | Returned when the specified resource that you are attempting to access was not found. |
412 - Precondition Failed | Returned when the JSON that was provided was invalid. |
500 - Internal Server Error | Returned when the iSymphony server encountered an unexpected error while processing the request. |
JSON
All configuration information that is queried from the REST API will be returned in JSON format. All configuration information that is edited or added via the REST API must be specified in JSON format. Each configuration resource documentation page will specify the JSON format to use for the resource.
Security
By default the REST API will be restricted via HTTP Realm Auth and ACLs. The default credentials will be set to manager:manag3rpa55word and the ACLs will be set up to only allow connections from localhost. You can also secure the connection further with SSL encryption. See Security for more information.
Interfacing With The REST API
There are many different ways to interface with the REST API. One of the more common methods is to utilize the curl command line application. Each of the resource configuration pages in this documentation will provide curl command line examples for each HTTP method. PHP also includes curl methods that can be utilized to send HTTP requests directly from within php scripts. There are also many REST client libraries out there for almost every major programming language that can take some of the complexity out of interfacing with the REST API.