Base Principles¶

Protocols¶

Based on HTTP/S over TCP, the messages exchanged are encoded with JSON. It must be noted that in production environment, only HTTPS will be enforced.

URLs¶

The urls must be encoded according to standard url escaping rules.

All urls end points are ending with a /. All requests without it will be rejected.

It must be noted that when the APIO Broadsoft GW is behind the APIO Core (reference architecture):

The authentication mechanisms described here are no more relevant for the final API client, they will be for the mechanism between the Core and the GW.
The APIs exposed by the Core have as prefix “/api/v01/p1/” (where p1 is variable depend on the proxy name) instead of “/api/v1/”.
For more info about this, please refer to the APIO Core documentation.

Authentication¶

All the URLs defined in the API need a user session to be open, and the headers properly set.

The new authentication process extends the current principles to allow a REST compatible dialog on the login. (Read: the API is not stateless) Meaning, the right management is globally managed by the user rights as they are defined in the underlying network element.

For details see Login.

Audit¶

If audit is enabled, all answers will contain the _internal_record_id parameter.

Constraints for API fields based on HTTP methods¶

Some objects are used in different methods and end points with different mandatory/optional/… rules. In that case their description indicate for each supported method their status code.

Code	Method				Description
Code	GET	POST	PUT	DELETE	Description
A	X				The field is Always returned.
N	X				The field is Never returned.
C	X	X	X		The field is Conditional or is Conditionally returned.
F	X	X	X		The field is Forbidden
R	X	X	X	X	The field is Required.
O		X	X	X	The field is Optional.

Authorization levels for and API¶

Each API comes with a default set of rights defined in the product code. Based on the user level (see user_level in Login profile attributes).

These authorization rights can be mostly of the 2 types:

Exact level needed. For example an API that only an End User can trigger
Minimum level needed. For example and API that A Grouyp Adminand all users with an higher level (such a Tenant Admin) can trigger. This is the most common case

Up to some extends theses rights can be modifed in project mode using a dedicated configuration object at end point level.

The API authorization rights will be described in this document. It must bhe noted that it is a new information introduced in the documentation in the course of the development of the release 1.6 so new APIs wil ahve ts informaiton and existing APIs will be updated over the time.