Acano solution. Acano Server API Reference. Acano. August A

Transcription

1 Acano solution Acano Server API Reference Acano August A

2 Contents Contents Change History 4 1 General Structure 5 2 Object Hierarchy 6 3 Transport and Methods Configuration Settings GET Operations Collections level Individual object level HTTP specifics POST Operations HTTP specifics PUT Operations HTTP specifics DELETE Operations Authentication Example Requests and Responses for Specific Operations Retrieval of Current Active Calls Creating a New Call Leg (SIP dial out to ): cospace and Call Related Methods Retrieval of Currently Configured cospaces Creating a cospace Deleting a cospace Modifying a cospace Retrieving Detailed Information about a Single cospace Retrieving the Members of a cospace Adding a New Member to a cospace Removing a cospace Member Modifying a cospace Member Retrieving Information on a cospace Member Posting to the Message Board of a cospace Calling Out from a cospace Retrieving Information on Active Calls Creating a New Call Retrieving Information on an Active Call Adding a Call Leg to a Call Retrieving Information on Active Call Legs Retrieving Information on a Call Leg Deleting a Call Leg Modifying a Call Leg Retrieval of Currently Configured Users Acano solution: Acano Server API Reference A Page 2

3 Contents 5.22 Retrieving Information on a Configured User Retrieval of a user s cospace associations Retrieving System Status LDAP Server Access Methods Adding a New Configured LDAP Server Retrieving Information on Configured LDAP Servers Modifying a Configured LDAP Server Removing a Configured LDAP Server Adding a New Configured LDAP Mapping Retrieving Information on Configured LDAP Mappings Modifying a Configured LDAP Mapping Removing a Configured LDAP Mapping Adding a New Configured LDAP Source Retrieving Information on Configured LDAP Sources Modifying a Configured LDAP Source Removing a Configured LDAP Source Multi-tenancy Retrieval of Currently Configured Tenants Creating a New Tenant Modifying an Existing Configured Tenant Removing a Configured Tenant Appendix A: Additional Information 27 Call Leg Information Call leg configuration Call leg status Acano solution: Acano Server API Reference A Page 3

4 Change History Change History Version Date Change Summary V1 July 2013 Initial release August 2013 New sections: 3.1 Configuration settings 5.11 Posting to the message board of a cospace 5.17 Retrieving information on active call legs 5.24 Retrieving system status 6 LDAP server access methods 7 Multi-tenancy Acano solution: Acano Server API Reference A Page 4

5 General Structure 1 General Structure Conceptually, the API methods are designed to work on a hierarchical tree of objects. For example, each configured cospace exists as a node in this tree, and all of the users who are members of that cospace exist as nodes beneath the cospace object s node. In order to work within the environs of the Acano Server s high capacity in terms of the potentially large number of active calls and cospaces, it is important that the methods supported do not require the entire collection of active objects of any particular type to be able to be retrieved in a single response. For this reason, rather than returning such an oversized data set in a single response, responses typically return the first N matching entries and a count of the total number of objects of that type. In order to find a specific object for further operations (for example, for the purposes of a deeper dive into an individual object s active status, or to modify or delete it) filters can be applied to the initial retrieval in order to identify the object in question. Acano solution: Acano Server API Reference A Page 5

6 Object Hierarchy 2 Object Hierarchy The hierarchy of objects addressable via the API is: /calllegs /calllegs/<callleg id> /calls /calls/<call id> /calls/<call id>/calllegs /cospaces /cospaces/<cospace id> /cospaces/<cospace id>/cospaceusers /cospaces/<cospace id>/cospaceusers/<cospaceuser id> /cospaces/<cospace id>/messages /ldapmappings /ldapmapping/<ldap mapping id> /ldapservers /ldapservers/<ldap server id> /ldapsources /ldapsources/<ldap source id> /system/status /tenants /tenants/<tenant id> /users /users/<user id> /users/<user id>/usercospaces In each case, the top level plural term sits above potentially many individual object nodes; these individual object nodes are identified by an <id> which is a GUID typically. For example, if there are 100 cospaces configured on an Acano Server, conceptually there would be 100 nodes directly beneath /cospaces in the hierarchy. Acano solution: Acano Server API Reference A Page 6

7 Transport and Methods 3 Transport and Methods The API uses HTTP or HTTPS as a transport mechanism. Fundamentally: GET is used for retrieval of existing information POST is used to create new objects in the hierarchy PUT is used to modify an existing object DELETE is used to destroy an object in the tree For the purposes of addressing or creating individual objects, the URL format mirrors the conceptual hierarchy of objects, with some additional preceding tags in order to identify that the request is for the API. By way of example, to retrieve information on API object /calls/dbfca0dddbe1-43bb-b101-beb9a7ef35f4 it would be necessary to issue: GET /api/v1/calls/dbfca0dd-dbe1-43bb-b101-beb9a7ef35f4 HTTP/1.1 Specifically, at the top level, including /api means that the on-board HTTP server process can distinguish this HTTP operation from a normal browser operation, and including v1 means the API handler knows that the request is being made by an object that understands version 1 of the API. If an API operation is successful, it yields a 200 OK response from the Acano Server. In the case of an error, the Acano Server responses with a 4xx or 5xx HTTP status code. For example, a request supplying a <cospace id> which does not correspond to a valid cospace object would yield 404 Not Found. Additionally, for 4xx and 5xx error cases, extended error information may be returned as text/xml body data, for example: <failuredetails> <cospacedoesnotexist /> </failuredetails> More generally, such a response consists of a failuredetails section and a list of errors; in the above case an operation was attempted using a cospace ID that did not correspond to an active cospace. The possible failure reasons are described in section Configuration Settings Currently, to use the API you need to connect to HTTP port or HTTPS port You also need to configure a username and password in the API settings on the Configuration > API Settings page of the Acano Server Management Web Interface., You will be required to provide these credentials in order to use the API. 3.2 GET Operations As mentioned above, GET operations allow retrieval of information about existing API-accessible objects, and these generally come in two flavours: Collections level and Individual object level. Acano solution: Acano Server API Reference A Page 7

8 Transport and Methods Collections level If the GET operation is performed at the collections level (the pluralised noun: calls, cospaces etc.) then some number of matching child nodes will be retrieved. By design this is not guaranteed to be the entire list, though the total number of objects of that type present in the system can be learnt via this mechanism. In order to retrieve just specific items, GET operations allow the use of a filter expression. The idea here is that the interface of a management tool would initially present the API user with the summed count of cospaces (for example), basic details on the first N cospaces (e.g. their names) and a filter box which the human user can use to search for the specific cospace(s) of interest Individual object level If the operation is performed at the individual object level, more extended information about just that object will be returned. For example, after the unique ID of a matching cospace has been learnt via a (potentially filtered) GET of the /cospaces node, a subsequent GET of the /cospaces/<cospace id> node would return expanded information about just that cospace, for example how many members it has, and when it was last activated HTTP specifics GET operations contain the complete node location and any parameters specific to the retrieval being performed in the URI supplied by the API user. For example, to retrieve basic information on the first N cospaces, the URI would be: /api/v1/cospaces whereas to list just those whose name includes sales, the GET would be performed on: /api/v1/cospaces?filter=sales If a GET operation has been successful and yields a 200 OK response, the Acano Server returns the retrieved information as text/xml body data. 3.3 POST Operations POST operations are supported so that API tools can create new objects on the system. For example, a POST operation can be used to create a new call leg and thereby initiate a new outbound SIP call from a cospace HTTP specifics Most POST operations require some parameters to be supplied: for example, creation of a cospace requires the new cospace s name to be specified, and a new call leg can only be created if the remote party s address is known. Such parameters must be supplied by the initiator of the POST operation via the standard HTTP x-www-form-urlencoded format, as used by <form> elements in an HTML document. If a POST operation has been successful in adding a new object to the hierarchy, that object s id, and its position within the hierarchy are returned in the Location field of the response. Acano solution: Acano Server API Reference A Page 8

9 Transport and Methods 3.4 PUT Operations PUT operations modify existing objects; for example, muting a specific call leg or changing the layout HTTP specifics In common with POST operations, required parameters must be supplied within the content of the request in x-www-form-urlencoded format. 3.5 DELETE Operations DELETE operations remove objects from the hierarchy; for example, dropping a call leg or disassociating a user from a cospace so that the user is no longer a member. 3.6 Authentication In order to reduce state requirements on both sides, HTTP Basic authentication is used, with the user of the API supplying a shared secret username and password to the Acano Server configured with the same username and password. The username and password are set on the Acano Server Management Web Interface by going to Configuration > API Settings. HTTPS can be used to avoid any security issues with Basic authentication; while the authentication credentials are sent in essentially plain text within the HTTP traffic, the traffic itself cannot be able to be read by an external party. 3.7 Failure Reasons The following "failuredetails" codes can be returned by the API: Reason code cospacedoesnotexist cospaceuserdoesnotexist duplicatecospaceuri duplicatecospaceid ldapserverdoesnotexist ldapmappingdoesnotexist ldapsourcedoesnotexist Description You tried to modify or remove a cospace using an ID that did not correspond to a valid cpspace on the system You tried to modify or remove a cospace user using an ID that did not correspond to a valid cospace user. You tried to create or modify a cospace to use a URI that clashed with one that corresponds to another cospace. (Two cospaces can't share the same URI, because the Acano Server must be able to uniquely resolve an incoming call to a cospace URI). You tried to create or modify a cospace ID to use an ID that clashed with one that corresponds to another cospace. You tried to modify or remove an LDAP server using an ID that did not correspond to a valid LDAP server. You tried to modify or remove an LDAP mapping using an ID that did not correspond to a valid LDAP mapping. You tried to modify or remove an LDAP source using an ID that did not correspond to a valid LDAP source. Acano solution: Acano Server API Reference A Page 9

10 Transport and Methods partnerdoesnotexist tenantdoesnotexist userdoesnotexist: You tried to modify or remove a partner using an ID that did not correspond to a valid partner. You tried to modify or remove a tenant using an ID that did not correspond to a valid tenant. You tried to modify or remove a user using an ID that did not correspond to a valid user. Acano solution: Acano Server API Reference A Page 10

11 Example Requests and Responses for Specific Operations 4 Example Requests and Responses for Specific Operations 4.1 Retrieval of Current Active Calls As described above, retrieval operations using GET involve no body content posted by the retriever, and, if the request is valid, XML response data from the Acano Server. Request: GET /api/v1/calls HTTP/1.1\r\n Host: test.acano.com\r\n User-Agent: API console\r\n Connection: keep-alive\r\n Authorization: Basic Ym9iOmJ1aWxkZXI=\r\n \r\n Response: HTTP/ OK Content-Type: text/xml Content-Length: 187 Connection: close \r\n <?xml version="1.0"?> <calls total="1"> <call id="527089d c05c9e274"> <name>sales cospace</name> <cospace>2dcf2b7a b d469</cospace> </call> </calls> 4.2 Creating a New Call Leg (SIP dial out to ): As described above, any parameters needed for the creation operation (in this case, the address of the remote party), need to be supplied by the issuer as form data. If the request is successful, details about the new object are returned by the Acano Server in the Location header field. Request: POST /api/v1/calls/527089d c05c9e274/calllegs HTTP/1.1\r\n Host: test.acano.com\r\n User-Agent: API console\r\n Connection: keep-alive\r\n Authorization: Basic Ym9iOmJ1aWxkZXI=\r\n Content-Type: application/x-www-form-urlencoded\r\n Content-Length: 24\r\n Acano solution: Acano Server API Reference A Page 11

12 Example Requests and Responses for Specific Operations \r\n remoteparty= Response: HTTP/ OK\r\n Location: /api/v1/calllegs/5a3b907a fb-ae8c-b3424a3e923f\r\n Connection: close\r\n \r\n Acano solution: Acano Server API Reference A Page 12

13 cospace and Call Related Methods 5 cospace and Call Related Methods This section details the API methods related to management of cospaces and call legs, both in terms of live and configured elements. 5.1 Retrieval of Currently Configured cospaces GET operation performed on the /cospaces node Additionally supply filter=<text> in the URI to return just those cospaces that match the filter Response includes the total count of the number of cospaces present on the system which match the filter, irrespective of the number returned in the response (with no filter, this value is the total number of cospaces configured on the system) Response is structured as a top-level <cospaces total= N > tag with potentially multiple <cospace> elements within it <cospace> elements returned follow the general form: <cospace id="d64e1f42-b41e-45a fe9656aa5ef"> <name>test cospace name</name> <uri>test.cospace999</uri> <callid> </callid> </cospace> The id value as returned in the opening tag is a unique identifier for the cospace, and can be used for future modify / delete / query operations on that cospace 5.2 Creating a cospace POST operation to the /cospaces node Parameters that can be supplied in the request: name : the human-readable name that will be shown on clients UI for this cospace uri (optional): the URI that a SIP system would use to dial in to this cospace (optional) callid (optional): the numeric ID that a user would enter at the IVR (or via a web client) to connect to this cospace passcode (optional): the security code for this cospace defaultlayout (optional): the default layout to be used for new call legs in this cospace ( allequal, speakeronly, telepresence or stacked ) If the cospace was successfully created, a 200 OK response is received, and the Location header in the response contains the ID for the new cospace Acano solution: Acano Server API Reference A Page 13

14 cospace and Call Related Methods 5.3 Deleting a cospace DELETE operation performed on a /cospaces/<cospace ID> node <cospace ID> is known by the caller either from a previous retrieval operation (see above) or from the Location field in the response to a previous creation operation If successful, the cospace is removed and the Acano Server sends a 200 OK response; if unsuccessful (for instance because the cospace to be deleted did not exist), a failure status code will be sent." 5.4 Modifying a cospace PUT operation performed on a /cospaces/<cospace ID> node <cospace ID> is known by the caller either from a previous retrieval operation (see above) or from the Location field in the response to a previous creation operation Fields allowed to be modified are those in the Creating a cospace description above If the cospace was found and has been successfully modified, a 200 OK response is received 5.5 Retrieving Detailed Information about a Single cospace GET operation performed on a /cospaces/<cospace ID> node <cospace ID> is known by the caller either from a previous retrieval operation (see above) or from the Location field in the response to a previous creation operation If the cospace ID supplied is valid, a 200 OK response is received, with XML content: <cospace id= d64e1f42-b41e-45a fe9656aa5ef"> <name>test cospace name</name> <uri>test.cospace</uri> <callid> </callid> <passcode>0000</passcode> <defaultlayout>allequal</defaultlayout>" </cospace> 5.6 Retrieving the Members of a cospace GET operation performed on a /cospaces/<cospace ID>/coSpaceUsers node <cospace ID> is known by the caller either from a previous retrieval operation (see above) or from the Location field in the response to a previous creation operation Requestor can optionally supply filter=<text> in the URI to return just those cospace users whose names match the filter Response includes the total count of cospace users configured for the cospace in question which match the filter, irrespective of the number returned in the response (with no filter, this value is the total number of users associated with the cospace) Acano solution: Acano Server API Reference A Page 14

15 cospace and Call Related Methods Response is structured as a top-level <cospaceusers total= N > tag with potentially multiple <cospaceuser> elements within it <cospaceuser> elements returned follow the general form: <cospaceuser id="d64e1f a fe9656aa5ef"> <userid>d64e1f a fe9656aa5ef</userid> </cospaceuser> <cospaceuser> elements have their own ID and also contain an ID for the user. This latter value identifies the user with no relationship to any cospace association, and may or may not be the same as the ID of the cospaceuser object 5.7 Adding a New Member to a cospace POST operation to a /cospaces/<cospace ID>/coSpaceUsers node Parameters to be supplied in the request: userjid : JID of the user to be added as a member candestroy (optional): whether this user is allowed to destroy the cospace ( true or false ) canaddremovemember (optional): whether this user is allowed to add or remove other members of the cospace ( true or false ) If the member was successfully added, a 200 OK response is received, and the Location header in the response contains the new user ID 5.8 Removing a cospace Member DELETE operation performed on a /cospaces/<cospace ID>/coSpaceUsers/<coSpaceUser ID> node If successful, the cospace member is removed and the Acano Server sends a 200 OK response; if unsuccessful (for instance because the cospace member to be deleted did not exist), a failure status code will be sent." 5.9 Modifying a cospace Member PUT operation performed on a /cospaces/<cospace ID>/coSpaceUsers/<coSpaceUser ID> node Fields that can be modified are those than can be specified when adding a cospace member, with the exception of userjid 5.10 Retrieving Information on a cospace Member GET operation performed on a /cospaces/<cospace ID>/coSpaceUsers/<coSpaceUser ID> node Acano solution: Acano Server API Reference A Page 15

16 cospace and Call Related Methods <cospace ID> and <cospaceuser ID> are known by the caller from a previous retrieval operation (see above) or from the Location field in the response to a previous creation operation If the retrieval is valid, a 200 OK response is received, with XML content of the form: <cospaceuser id="d64e1f a fe9656aa5ef"> <userid>d64e1f a fe9656aa5ef</userid> <userjid>first.last@company.com</userjid> <candestroy>true</candestroy> <canaddremovemember>true</canaddremovemember> </cospaceuser> 5.11 Posting to the Message Board of a cospace POST operation performed on the /cospaces/<cospace id>/messages node Initiator should supply a message value in its form data for the message text to be posted to the message board Optionally, the initiator can supply a from value to be shown to message board viewers as the originator of the message If successful, the message is posted to the message board and an ID for the message is returned in the Location field of the response header 5.12 Calling Out from a cospace Adding a remote party to a cospace first requires that the cospace in question has an active call from which connections can be made. Essentially this makes an initial call out from a cospace a combination of two other API operations: 1. Creation of a new call. 2. Adding a new outgoing call leg to a call. These operations are described in the call and call leg sections below Retrieving Information on Active Calls GET operation performed on the /calls node Initiator can optionally supply filter=<text> in the URI to return just those calls that match the filter Response is structured as a top-level <calls total= N > tag with potentially multiple <call> elements within it <call> elements returned follow the general form: <call id="d64e1f a fe9656aa5ef"> <name>quarterly results call</name> <cospace>d64e1f42-b41e-45a fe9656aa5ef</cospace> </call> Acano solution: Acano Server API Reference A Page 16

17 cospace and Call Related Methods 5.14 Creating a New Call POST operation performed on the /calls node Initiator must supply a cospace value in its form data to specify the cospace for which the call is being instantiated If successful, a call is instantiated for the cospace, and that call s details are returned in the Location field of the response header 5.15 Retrieving Information on an Active Call GET operation performed on a /calls/<call ID> node <call ID> is known by the caller either from a previous retrieval operation (see above) or from the Location field in the response to a previous creation operation If the call ID supplied is valid, a 200 OK response is received, with XML content of the form: <call id= ab-927b-4624-a77d c92ac"> <durationseconds>1234</durationseconds> <numcalllegs>5</numcalllegs> <maxcalllegs>8</maxcalllegs> </call> Values returned include the duration of the call, as a number of seconds since the call started, and the current and maximum number of call legs present in that call 5.16 Adding a Call Leg to a Call POST operation performed on a /calls/<call ID>/callLegs node call ID is learnt from a GET on /calls or from a newly created call (see Creating a new call above) Initiator should supply a remoteparty value in its form data to specify the call leg s address; this could be a SIP URI, a phone number, or a user JID to invite that user to the call 5.17 Retrieving Information on Active Call Legs GET operation performed on the /calllegs node (to retrieve information on all active call legs within the system) Alternatively, a GET operation performed on the /calls/<call id>/calllegs node (to retrieve information on active call legs for a specific call) Requestor can optionally supply filter=<text> in the URI to return just those call legs that match the filter Requestor can optionally supply alarms=<alarm names> in the URI to return just those call legs for which the specified alarm conditions are currently active. At present, the only available value is all, which covers packet loss and jitter conditions. Acano solution: Acano Server API Reference A Page 17

18 cospace and Call Related Methods Response is structured as a top-level <calllegs total= N > tag with potentially multiple <callleg> elements within it <callleg> elements returned follow the general form: <call id="d64e1f a fe9656aa5ef"> <name>quarterly results call</name> <cospace>d64e1f42-b41e-45a fe9656aa5ef</cospace> </call> 5.18 Retrieving Information on a Call Leg GET operation performed on a /calllegs/<callleg ID> node <callleg ID> is known by the caller either from a previous retrieval operation (see above) or from the Location field in the response to a previous creation operation If the call leg id supplied is valid, a 200 OK response is received, with XML content: <callleg id= ab-927b-4624-a77d c92ac"> <configuration> call leg configuration (see Appendix A) </configuration> <status> call leg status (see Appendix A) </status> </callleg> 5.19 Deleting a Call Leg DELETE operation performed on a /calllegs/<callleg ID> node Causes disconnection of SIP / Lync connection, or a client to be dropped from the call or cospace it is currently connected to Note that <callleg ID> values are always accessed via the top-level /calllegs node, even if those call legs have been created via POSTs to /calls/<call ID>/callLegs 5.20 Modifying a Call Leg PUT operation performed on a /calllegs/<callleg ID> node Makes live, dynamic changes to an in-progress connection to a remote party Mechanisms by which layout changes, mute changes can be effected are: Supplying a layout value as one of allequal, speakeronly, telepresence or stacked will change the call leg to use that layout Supplying rxaudiomute, txaudiomute, rxvideomute or txvideomute as true or false will change the mute status for that stream Acano solution: Acano Server API Reference A Page 18

19 cospace and Call Related Methods 5.21 Retrieval of Currently Configured Users GET operation performed on the /users node Initiator can optionally supply filter=<text> in the URI to return just those users that match the filter Response is structured as a top-level <users total= N > tag with potentially multiple <user> elements within it <user> elements returned follow the general form: <user id="d64e1f a fe9656aa5ef"> <userjid>first.last@company.com</userjid> </user> 5.22 Retrieving Information on a Configured User GET operation performed on a /users/<user ID> node <user ID> is known by the caller from a previous retrieval operation (see above) If the user id supplied is valid, a 200 OK response is received, with XML content of the form: <user id= ab-927b-4624-a77d c92ac"> <userjid>first.last@company.com</userjid> < >first.last@mail.company.com</ > </user> 5.23 Retrieval of a user s cospace associations GET operation performed on a /users/<user ID>/usercoSpaces node <user ID> is known by the caller from a previous retrieval operation (see above) Response is structured as a top-level <usercospaces total= N > tag with potentially multiple <usercospace> elements within it, each of which lists <usercospace> elements returned follow the general form: <usercospace id="d64e1f a fe9656aa5ef"> <cospace>d64e1f42-b41e-45a fe9656aa5ef</cospace> </usercospace> 5.24 Retrieving System Status GET operation performed on the /system/status node If successful, returns within a <status> element: uptimeseconds the length of time that the unit has been running calllegsactive the number of active call legs at the time of the request Acano solution: Acano Server API Reference A Page 19

20 cospace and Call Related Methods calllegsmaxactive - the highest number of call legs simultaneously active on this Acano Server calllegscompleted the total number of call legs that have been active but are no longer connected / present Acano solution: Acano Server API Reference A Page 20

21 LDAP Server Access Methods 6 LDAP Server Access Methods Objects in the hierarchy that reside in the /ldapmappings, /ldapservers and /ldapsources nodes in the object tree relate to the Acano Server s interaction with one or more LDAP servers (for instance, Active Directory) which are used to import user accounts to the Acano Server. One or more LDAP servers should be configured, with each one having associated username and password information for the Acano Server to use to connect to it for the purpose of retrieving user account information from it One or more LDAP mappings are also required, which define the form of the user account names which will be added to the system when users are imported from configured LDAP servers A set of LDAP sources then need to be configured, which tie together configured LDAP servers and LDAP mappings, along with parameters of its own, which correspond to the actual import of a set of users. An LDAP source takes an LDAP server / LDAP mapping combination and imports a filtered set of users from that LDAP server. This filter is determined by the LDAP source's "basedn" (the node of the LDAP server's tree under which the users can be found) and a filter to ensure that user accounts are only created for LDAP objects that match a specific pattern. The API LDAP methods allow multiple additional sets of Active Directory Configuration as per the Management Web Interface Configuration > Active Directory page. On this page, the Active Directory Server Settings section corresponds to an API-configured LDAP server, the Import Settings to an LDAP source, and the Field Mapping Expressions to an LDAP mapping. 6.1 Adding a New Configured LDAP Server POST operation performed on the /ldapservers node Initiator must supply the following parameters: address the address of the LDAP server to connect to portnumber the TCP or TLS port number to connect to on the remote LDAP server username the username to use when retrieving information from the LDAP server password the password of the account associated with username secure whether to make a secure connection to the LDAP server. If true then TLS will be used; if false, TCP will be used If successful, the LDAP server is configured on the system and its ID is returned in the Location field of the response header 6.2 Retrieving Information on Configured LDAP Servers GET operation performed on the /ldapservers node Response is structured as a top-level <ldapservers total= N > tag with potentially multiple <ldapserver> elements within it Acano solution: Acano Server API Reference A Page 21

22 LDAP Server Access Methods <ldapserver> elements returned follow the general form: <ldapserver id="d64e1f a fe9656aa5ef"> <address>ldap.company.com</address> <portnumber>636</portnumber> <username>directoryuser</username> <password>directorypassword</password> <secure>true</secure> </ldapserver> 6.3 Modifying a Configured LDAP Server PUT operation performed on a /ldapservers/<ldapserver id> node Fields that can be modified are those that can be specified when first configuring an LDAP server. See above. 6.4 Removing a Configured LDAP Server DELETE operation performed on a /ldapservers/<ldapserver id> node If successful, the LDAP server is removed and the Acano Server sends a 200 OK response; if unsuccessful (for instance because the LDAP server to be deleted did not exist), a failure status code will be sent 6.5 Adding a New Configured LDAP Mapping POST operation performed on the /ldapmappings node Initiator must supply the following parameters: jidmapping the template for generating user JIDs from the associated LDAP server s entries, for instance $samaccountname$@companyname.com namemapping the template for generating user names from the associated LDAP server s entries; for instance $cn$ to use the common name If successful, the LDAP mapping is configured on the system and its ID is returned in the Location field of the response header 6.6 Retrieving Information on Configured LDAP Mappings GET operation performed on the /ldapmappings node Response is structured as a top-level <ldapmappings total= N > tag with potentially multiple <ldapmapping> elements within it <ldapmapping> elements returned follow the general form: <ldapmapping id="d64e1f a fe9656aa5ef"> <jidmapping>$samaccountname$@companyname.com</jidmapping> <namemapping>$cn$</namemapping> Acano solution: Acano Server API Reference A Page 22

23 LDAP Server Access Methods </ldapmapping> 6.7 Modifying a Configured LDAP Mapping PUT operation performed on a /ldapmappings/<ldapmapping id> node Fields that can be modified are those that can be specified when first configuring an LDAP mapping. See above. 6.8 Removing a Configured LDAP Mapping DELETE operation performed on a /ldapmappings/<ldapmapping id> node If successful, the LDAP mapping is removed and the Acano Server sends a 200 OK response; if unsuccessful (for instance because the LDAP mapping to be deleted did not exist), a failure status code will be sent 6.9 Adding a New Configured LDAP Source POST operation performed on the /ldapsources node Initiator must supply the following parameters: server the ID of a previously-configured LDAP server (see above) mapping the ID of a previously-configured LDAP mapping (see above) basedn the distinguished name of the node in the LDAP server s tree from which users should be imported, for instance cn=users,dc=companyname,dc=com filter an LDAP filter string that records must satisfy in order to be imported as users, for instance (objectclass=person) If successful, the LDAP source is configured on the system and its ID is returned in the Location field of the response header 6.10 Retrieving Information on Configured LDAP Sources GET operation performed on the /ldapsources node Response is structured as a top-level <ldapsources total= N > tag with potentially multiple <ldapsource> elements within it <ldapsource> elements returned follow the general form: <ldapsource id="d64e1f a fe9656aa5ef"> <server>, <mapping>, <basedn> and <filter> elements as per LDAP source creation described above </ldapsource> 6.11 Modifying a Configured LDAP Source PUT operation performed on a /ldapsources/<ldapsource id> node Acano solution: Acano Server API Reference A Page 23

24 LDAP Server Access Methods Fields that can be modified are those that can be specified when first configuring an LDAP source. See above Removing a Configured LDAP Source DELETE operation performed on a /ldapsources/<ldapsource id> node If successful, the LDAP source is removed and the Acano Server sends a 200 OK response; if unsuccessful (for instance because the LDAP source to be deleted did not exist), a failure status code will be sent Acano solution: Acano Server API Reference A Page 24

25 Multi-tenancy 7 Multi-tenancy The Acano Server supports multi-tenancy; this refers to sub-dividing its capacity into a set of islands where each island has all of the functionality of the unit as a whole, but has no access to the resources (for instance users, cospaces, or active calls) of other tenants. There are two main implications of multi-tenancy on the API: The API allows tenants to be created, modified and removed, and is the primary means by which tenants are managed The API can return results to a specific tenant. In multi-tenancy mode, typically each cospace, call and user is keyed to ( owned by ) a tenant; when retrieving information on a specific user, cospace or call object, the API includes which tenant owns that object, and enumeration-based retrievals include the tenant information for each object in the returned list. The majority of the API methods detailed above work in multi-tenancy mode. In most cases, this equates to supplying a tenant ID in creation (POST) operations via the form parameters, such that the system knows which tenant a new object is to be associated with. For instance, creating a cospace when not in multi-tenant mode would involve a POST operation to /api/v1/cospaces with parameters such as name as form parameters. To create a cospace for a specific tenant, the POST would again be to /api/v1/cospaces, but additionally include a tenant=<tenant id> in the form parameters, where <tenant id> would have been learnt either as the result of a previous tenant creation or via an earlier enumeration. Then in subsequent PUTs to that cospace object, the tenant parameter would either be omitted (to leave its value unchanged), changed to a new value (in order to reassign that object to a new tenant), or be supplied an empty tenant value (to remove its association with any tenant). In any initial POST operation, an absent tenant parameter or a zero-length value are treated as equivalent. The effect is that there is that the object is not associated with any tenant. According to the rules above, <tenant id> values are valid in creation and modification (POST and PUT) operations for the following objects: cospaces ( /cospaces or /cospaces/<cospace ID> ) LDAP sources ( /ldapsources or /ldapsources/<ldap source id> ) <tenant id> values are returned by the Acano Server in retrieval (GET) operations for the following objects: cospaces ( /cospaces or /cospaces/<cospace ID> ) users ( /users or /users/<user ID> ) calllegs ( /calllegs, /calllegs/<call leg id>, or /calls/<call id>/calllegs LDAP sources ( /ldapsources or /ldapsources/<ldap source id> ) For enumerations of all of these objects it is valid to supply a tenantfilter value in the requested URI in order to retrieve only those objects associated with the specified tenant. Acano solution: Acano Server API Reference A Page 25

26 Multi-tenancy 7.1 Retrieval of Currently Configured Tenants GET operation performed on a /tenants node Initiator can optionally supply filter=<text> in the URI to return just those tenants that match the filter Response is structured as a top-level <tenants total= N > tag with potentially multiple <tenant> elements within it <tenant> elements returned follow the general form: <tenant id="d64e1f a fe9656aa5ef"> <name>company name</name> </tenant> 7.2 Creating a New Tenant POST operation performed on the /tenants node No parameters are required if desired the initiator can supply a name value as a label for the tenant If successful, the tenant is created and an ID for the new tenant is returned in the Location field of the response header 7.3 Modifying an Existing Configured Tenant PUT operation performed on a /tenants/<tenant id> node Fields that can be modified are those that can be specified when adding a new tenant. See the previous section. 7.4 Removing a Configured Tenant DELETE operation performed on a /tenants/<tenant id> node If successful, the tenant is removed and a 200 OK response is received Acano solution: Acano Server API Reference A Page 26

27 Additional Information Appendix A: Additional Information Call Leg Information When information is retrieved on an specific individual call leg, its structure follows the form: <callleg id= ab-927b-4624-a77d c92ac"> <configuration> call leg configuration </configuration> <status> call leg status </status> </callleg> Call leg configuration The configuration section returned includes the same values as those that can be modified in a PUT operation on that call leg. An example configuration section is shown below: <configuration> <rxaudiomute>false</rxaudiomute> <txaudiomute>false</txaudiomute> <rxvideomute>false</rxvideomute> <txvideomute>false</txvideomute> <layout>speakeronly</layout> </configuration> Call leg status The status information returned contains live values relating to the call leg s active state. Media information is contained within one or more rxaudio, txaudio, rxvideo and txvideo sub-sections; multiple video or audio streams may be identified and distinguished via their role attribute, which may be either main or presentation. Each media section includes packet loss percentage and jitter. An example set of status data is shown below: <status> <state>connected</state> <durationseconds>13</durationseconds> <encryptedmedia>true</encryptedmedia> <unencryptedmedia>false</unencryptedmedia> <rxaudio> Acano solution: Acano Server API Reference A Page 27

28 Additional Information <codec>g.722</codec> <packetlosspercentage>0.0</packetlosspercentage> <jitter>0</jitter> </rxaudio> <txaudio> <codec>g.722</codec> <packetlosspercentage>0.0</packetlosspercentage> <jitter>2</jitter> </txaudio> <rxvideo role="main"> <codec>h.264</codec> <width>352</width> <height>288</height> <framerate>25.0</framerate> <bitrate>300643</bitrate> <packetlosspercentage>0.0</packetlosspercentage> <jitter>0</jitter> </rxvideo> <txvideo role="main"> <codec>h.264</codec> <width>512</width> <height>288</height> <framerate>24.5</framerate> <bitrate>516358</bitrate> <packetlosspercentage>0.0</packetlosspercentage> <jitter>2254</jitter> </txvideo> </status> Acano solution: Acano Server API Reference A Page 28

29 2013 Acano. All rights reserved. Acano solution: Acano Server API Reference A Page 29