Methods for Working with Resources
- esnata (Unlicensed)
For resource management, the API defines standard methods that allow you to add, receive, modify, and delete resources.
https | Name | Path |
|---|---|---|
GET | getting a list of resources | /realm/{realm_id}/resource/ |
POST | adding a resource | /realm/{realm_id}/resource/ |
GET | getting a resource by id | /realm/{realm_id}/resource/{resource_id} |
PUT | changing a resource | /realm/{realm_id}/resource/{resource_id} |
DELETE | deleting a resource by id | /realm/{realm_id}/resource/{resource_id} |
Path parameters
realm
The API section defines the set of available resources and operations on them. Determined by the type of authorized user. It can take the following values:
client (corresponds to a user of the "client" type)
extension_group (corresponds to a user of the type "group of internal numbers")
extension (corresponds to the user of the "internal number" type)
A higher-level user can use lower-level resources
For example, a client-level user can use the GET /extension/{extension_id}/phone resource/
realm_id
ID of the resource that the authorized user is associated with. For user of type "client" (/user/client/) — the resource ID /the client/ user of the "group numbers" (/user/extension_group/) — ID /extension_group/ for user "inner room"(/user/extension/) — ID (/extension/).
If the realm and the authorized user type are the same, then the realm_id value can be "@me"
For example, a user of the type "internal number" can make a request "GET /extension/@me/phone/", and for a user of the type "client" this request will be invalid
For requests for resources in the "internal number" section, you can specify the name of the internal number in the format @extension_name instead of the ID of the internal number:
The name of the internal number in full format with the client prefix: GET /extension/@1844*101/phone/
The name of the internal number in the abbreviated format: GET /extension/@101/phone/
resource
The name of the resource, for example: event or record.
resource_id
Unique resource ID.
Some resources may not contain realm and realm_id in the path. Such resources do not depend on the type of client that uses them. For example, /timezone/ - to get a list of supported time zones.
The set of methods is not always complete and depends on the resource.
Getting a list of resources
Requests to get a list of resources are made by a GET request. The response returns a JSON array containing the resources. If there are no resources or none of the resources match the filtering criteria (see below), an empty array is returned.
HTTP response code for a successful operation: 200.
Many resource list requests have additional request parameters that are specified in the request string after the "?" character. These parameters allow you to filter the list returned by the query by one or more fields. For example, the query below allows a user of type "client" to get a list of internal numbers of numbers of type "phone", which are in the group of internal numbers with the ID 1:
|
Adding a resource
New resources are added by a POST request, the request body is a JSON document containing the resource parameters. Parameters can be required or optional. In the second case, the resource parameter will take the default value. Some parameters allow a 'null' value, which means that the parameter value is missing.
HTTP response code for a successful operation: 201. If the operation is successful, the created resource is returned.
In case of incorrect parameters, the returned response has the code 400, and the response body is a JSON document describing the cause of the error in the message field. If the message field contains the message "Bad Request", then the error is in the formation of a JSON document.
Getting a resource
Getting a specific resource by its ID is performed by a GET request, and the resource ID is contained in the URL. For example, a user of the "client" type can get data about the "extension" resource with the ID " 2":
|
HTTP response code for a successful operation: 200. In this case, the resource is returned in the format of a JSON document. If the resource is not found, the response code will be 404.
Changing a resource
Changing (updating) a resource by its ID is performed by a PUT request, and the resource ID is contained in the URL.
The request body is a JSON document containing the parameters to be changed. Parameters not passed in the request will not change.
HTTP response code for a successful operation: 200. If the operation is successful, the updated resource is returned. If the resource is missing, the response code will be 404.
In case of incorrect parameters, the returned response has the code 400, and the response body is a JSON document describing the cause of the error in the message field.
Deleting a resource
Getting a specific resource by its ID is performed by a request of the DELETE type, and the resource ID is contained in the URL.
HTTP response code for a successful operation: 204. If there is no resource to delete, the response code will be 404.
In order to successfully execute requests, pay attention to the presence of a trailing slash "/" in the URL addresses in POST, PUT, GET requests using data arrays, or its absence in cases where GET, PUT, DELETE requests are sent with a single object