Skip to Content

Wiki source code of REST API Documentation

Version 13.1 by michaely on 2014/09/17 22:39
Show last authors
1 ==== **//On this page~://** ====
2
3
4
5 {{toc maxLevel="2" indent="1"/}}
6
7 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.
8
9 = HTTP Methods =
10
11 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.
12
13 |(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
14 (((
15 **GET**
16 )))|(((
17 Used to query configuration resources from the server.
18 )))
19 |(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
20 (((
21 **PUT**
22 )))|(((
23 Used to update configuration resources on the server.
24 )))
25 |(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
26 (((
27 **POST**
28 )))|(((
29 Used to add configuration resources to the server.
30 )))
31 |(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
32 (((
33 **DELETE**
34 )))|(((
35 Used to remove configuration resources from the server.
36 )))
37
38 = HTTP Status Codes =
39
40 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.
41
42 |(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
43 (((
44 **200 - OK**
45 )))|(((
46 Returned when a GET was successful.
47 )))
48 |(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
49 (((
50 **204 - No Content**
51 )))|(((
52 Returned when a POST or PUT was successful.
53 )))
54 |(% class="highlight-grey" data-highlight-colour="grey" %)(% class="highlight-grey" data-highlight-colour="grey" %)
55 (((
56 **403 - Forbidden**
57 )))|(((
58 Returned when the client does not have access to the REST system due to ACLs or invalid credentials.
59 )))
60 |(% class="highlight-grey" colspan="1" data-highlight-colour="grey" %)(% class="highlight-grey" colspan="1" data-highlight-colour="grey" %)
61 (((
62 **404 - Not Found**
63 )))|(% colspan="1" %)(% colspan="1" %)
64 (((
65 Returned when the specified resource that you are attempting to access was not found.
66 )))
67 |(% class="highlight-grey" colspan="1" data-highlight-colour="grey" %)(% class="highlight-grey" colspan="1" data-highlight-colour="grey" %)
68 (((
69 4**12 - Precondition Failed**
70 )))|(% colspan="1" %)(% colspan="1" %)
71 (((
72 Returned when the JSON that was provided was invalid.
73 )))
74 |(% class="highlight-grey" colspan="1" data-highlight-colour="grey" %)(% class="highlight-grey" colspan="1" data-highlight-colour="grey" %)
75 (((
76 **500 - Internal Server Error**
77 )))|(% colspan="1" %)(% colspan="1" %)
78 (((
79 Returned when the iSymphony server encountered an unexpected error while processing the request.
80 )))
81
82 = JSON =
83
84 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.
85
86 = Security =
87
88 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.
89
90