Wiki source code of REST API Documentation

Last modified by Scott Gagan on 2021/09/10 23:34
Show last authors
1 ==== **//On this page~://** ====
2
3
4
5 {{toc maxLevel="2" indent="1"/}}
6
7 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.
8
9 = Interfaces =
10
11 The REST API is separated into two distinct interfaces.
12
13 * [[doc:iSymphony Developer Documentation.REST API Documentation.Configuration API.WebHome]] (**Available in iSymphony 3.1+**) - Provides access to the iSymphony configuration.
14 * [[doc:iSymphony Developer Documentation.REST API Documentation.Live API.WebHome]]** (Available in iSymphony 3.2+**) - Provides access to the live state of the iSymphony server, and allows execution of actions.
15
16 = HTTP Methods =
17
18 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.
19
20 |(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
21 (((
22 **GET**
23 )))|(((
24 Used to query resource information from the server.
25 )))
26 |(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
27 (((
28 **PUT**
29 )))|(((
30 Used to update configuration resources on the server.
31 )))
32 |(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
33 (((
34 **POST**
35 )))|(((
36 Used to add configuration resources to the server, and execute actions.
37 )))
38 |(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
39 (((
40 **DELETE**
41 )))|(((
42 Used to remove configuration resources from the server.
43 )))
44
45 = HTTP Status Codes =
46
47 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.
48
49 |(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
50 (((
51 **200 - OK**
52 )))|(((
53 Returned when a GET was successful.
54 )))
55 |(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
56 (((
57 **204 - No Content**
58 )))|(((
59 Returned when a POST or PUT was successful.
60 )))
61 |(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
62 (((
63 **403 - Forbidden**
64 )))|(((
65 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.
66 )))
67 |(% class="highlight-grey" colspan="1" data-highlight-colour="grey" %)(% class="highlight-grey" colspan="1" data-highlight-colour="grey" %)
68 (((
69 **404 - Not Found**
70 )))|(% colspan="1" %)(% colspan="1" %)
71 (((
72 Returned when the specified resource that you are attempting to access was not found.
73 )))
74 |(% class="highlight-grey" colspan="1" data-highlight-colour="grey" %)(% class="highlight-grey" colspan="1" data-highlight-colour="grey" %)
75 (((
76 **412 - Precondition Failed**
77 )))|(% colspan="1" %)(% colspan="1" %)
78 (((
79 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**
80 )))
81 |(% class="highlight-grey" colspan="1" %)(% class="highlight-grey" colspan="1" %)
82 (((
83 **422 - (% style="color: rgb(37,37,37);" %)Unprocessable Entity(%%)**
84 )))|(% colspan="1" %)(% colspan="1" %)
85 (((
86 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**
87 )))
88 |(% class="highlight-grey" colspan="1" data-highlight-colour="grey" %)(% class="highlight-grey" colspan="1" data-highlight-colour="grey" %)
89 (((
90 **500 - Internal Server Error**
91 )))|(% colspan="1" %)(% colspan="1" %)
92 (((
93 Returned when the iSymphony server encountered an unexpected error while processing the request.
94 )))
95
96 = JSON =
97
98 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.
99
100 = Security =
101
102 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 [[doc:ISYMDOCS.Security]] for more information.
103
104 {{info}}
105 When securing the rest API with SSL, URLs used to access the rest resources must use** https and port 55050**, instead of http and port 58080.
106 {{/info}}
107
108 = Interfacing With The REST API =
109
110 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.
111
112

Search

Navigation

iSymphony