Request Structure

The request URL consists of several parameters, such as host URL, API version, access token, API endpoint and required parameters. This topic describes the request structure, including request methods and request URL format.

Request example

You MUST include a User-Agent header with every request that you submit to the Cloud One Business Communication Suite API, so that the PBX can identify your application and respond to the request. For example, User-Agent: OpenAPI.

Below is a request example of Edit an Extension.

POST /openapi/v1.0/extension/update?access_token=5SwyByhbSfsNlpI1v4GtHxEDmKsZwzjQ HTTP/1.1 
Host: 192.168.5.150:8088
Content-Type: application/json
User-Agent: OpenAPI
{
    "id": 60,
    "presence_status":"off_work"
}

POST indicates the request method.
openapi/v1.0 is the API path that indicates the API version.
extension/update indicates the target API endpoint of Edit an Extension.
access_token=5SwyByhbSfsNlpI1v4GtHxEDmKsZwzjQ is the access token used for authentication.
HTTP/1.1 is the Hypertext Transfer Protocol.
Host indicates the IP address or the domain name of Cloud One BCS Software Edition.
Content-Type: application/json indicates the format of request content.
id and presence_status are the request parameters of Edit an Extension.

Request methods

Cloud One Business Communication Suite API supports the following request methods:

GET - to query information or execute delete operations.
POST - to add an object or execute specific operations.

Request URL format

The request URL format is as follows:

{base_url}/{api_path}/{endpoint}?access_token={access_token}

Note: No access token is needed in the request URL of Get Access Token and Refresh Access Token.{base_url}

All URLs referenced in the documentation have the following base URL:

https://{pbx_ip}:{https_port}

You can set the API base URL according to the web access settings on your PBX.

If the web access protocol of PBX is HTTP, use the following base URL:
```
http://{pbx_ip}:{http_port}
```
If the web access protocol of PBX is HTTPS, use the following base URL:
```
https://{pbx_ip}:{https_port}
```
If you use the Yeastar FQDN for remote API access, use the following base URL:
```
https://{pbx_fqdn_domain}
```
To remotely access API via Cloud One FQDN, you need to configure API remote access. For more information, see Configure Network for Remote API Access by a Cloud One FQDN.

{api_path}The format of API path is openapi/{version}; the {version} indicates the API version. Unless otherwise specified, URLs referenced in the document use API version v1.0, and the API path is openapi/v1.0.

Call Report interfaces use different API versions depending on the report data source:

openapi/v2.0: For report data generated on version 83.21.0.117 or later.
openapi/v1.0: For report data generated on version 83.21.0.66 or earlier.

{endpoint}

Endpoint indicates the specific address of API request.

Refer to API Interfaces & Events Summary for all available API endpoints on Cloud One Business Communication Suite.

{access_token}

Access token is used to authenticate API requests. The third-party application should Get Access Token before calling APIs. Each subsequent request requires the access token for authentication.

For detailed API authentication, see Authorization Rule.