REST API Documentation
On this page:
The iSymphony server provides a REST API that allows external applications to query and edit the configuration of the iSymphony server, query live state of the iSymphony Server, and execute actions, all via HTTP requests. The REST API has many uses including, but not limited to, integrating iSymphony configuration into existing configuration systems, auto provisioning of the iSymphony server, and development of custom applications, and iSymphony widgets, that depend on information provided by the iSymphony server. An example use case for this API is the iSymphony FreePBX module, which utilizes the configuration API to synchronize configuration between FreePBX and iSymphony.
Interfaces
The REST API is separated into two distinct interfaces.
- Configuration API (Available in iSymphony 3.1+) - Provides access to the iSymphony configuration.
- Live API (Available in iSymphony 3.2+) - Provides access to the live state of the iSymphony server, and allows execution of actions.
HTTP Methods
The REST API utilizes several HTTP methods to control how the information is queried and modified. See the individual resource documentation pages for which methods are supported for the given resource.
GET | Used to query resource information from the server. |
PUT | Used to update configuration resources on the server. |
POST | Used to add configuration resources to the server, and execute actions. |
DELETE | Used to remove configuration resources from the server. |
HTTP Status Codes
The REST API will return specific HTTP status codes when accessing resources, or executing actions. 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, or the resource you are attempting to access is not available due to licensing restrictions. |
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 well formed, but was missing required information to process the request, or the information provided was invalid. Only used by the Configuration API |
422 - Unprocessable Entity | Returned when the JSON that was provided was well formed, but was missing required information to process the request, or the information provided was invalid. Only used by the Live API |
500 - Internal Server Error | Returned when the iSymphony server encountered an unexpected error while processing the request. |
JSON
All information that is queried from the REST API will be returned in JSON format. All information that is sent to the REST API must be specified in JSON format. Each 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 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.