Welcome to cucm-http-api documentation!¶
Developer¶
Overview¶
This API keeps as much as possible the same terminology than the one used in the WSDL from CUCM.
Dropwizard¶
This application uses Dropwizard, it is recommended to be familiar with their documentation.
Configuration¶
Configuration is done through a YAML file containing various sections.
An example is available at src/main/resources/configuration.yml.example
.
Section “cucm”¶
This section is about credentials to connect to a CUCM server.
host
is the host nameuser
is the user to log in aspassword
is the password for theuser
Section “apiauth”¶
This section is about credentials to connect to this application using HTTP basic auth.
user
is the name of the user that will have to be use when attempting to do a basic authpassword
is a SHA-256 hash of the password
The hash of the password can be generated with echo -n "password" | shasum -a 256
.
Section “logging” (optional)¶
Configure the logging of the application (by overriding the default configuration), see Dropwizard’s documentation.
Section “http” (optional)¶
Configure the web server (by overriding the default configuration), see Dropwizard’s documentation.
See Security considerations for more recommendations on this section.
Deploying the application¶
The application is built as a single JAR using mvn install
, this JAR embeds a Jetty web-server.
The application can run as java -jar cucm-http-api.jar server path/to/configuration.yml
.
The process can be runned using Supervisor or Circus to be properly managed.
Security considerations¶
This software has been designed to be used as a technical API (used as a middleware) exposed to a limited audience.
The HTTP API exposes a limited set of values from CUCM, some of them are sensitive, in particular the “phone name” (which is the unique identifier of a device on a network).
All methods should be protected by authentication.
Design¶
This software does not store any data and is completly stateless.
Recommendations¶
Although the exposed HTTP API is protected by HTTP Basic Auth, it is recommended to use an appropriate firewall configuration to limit the exposure of data.
If all applications using this software are on the same machine, it should be bind to a local interface (see configuration).
Protecting resources¶
See Dropwizard auth documentation for more details, resources should include a parameter annotated @Auth
as shown in the example below.
@GET
public List<Phone> get(@QueryParam("dirn") IntParam dirn, @Auth User user) {
HTTP API¶
Phone endpoint¶
Endpoint for operations on phones.
All these calls require basic auth.
-
GET
/phone/
¶ Get phones corresponding to a directory number
Example request:
GET /phone/?dirn=123 HTTP/1.1 Host: 127.0.0.1 Accept: application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json [ { "product": "Cisco 7942", "description": "description", "model": "Cisco 7942", "name": "uniquename", "uuid": "{UUID}", "dirns": [ "123" ], "speeddials": [ { "index": "1", "dirn": "11", "label": "office" }, { "index": "2", "dirn": "22", "label": "home" }, ] } ]
Query Parameters: - dirn – directory number to search for
Status Codes: - 200 OK – list of phones matching the directory number (empty list if no phone)
Speeddials endpoint¶
Endpoint for operations on speeddials.
All these calls require basic auth.
-
POST
/speeddials
¶ Update the speeddials for a phone by its name.
Example request:
POST /speeddials?phone=name HTTP/1.1 Host: 127.0.0.1 Accept: application/json Content-Type: application/json [ { "index": "1", "dirn": "11", "label": "office" }, { "index": "2", "dirn": "22", "label": "home" }, ]
Example response:
HTTP/1.1 200 OK Content-Type: plain/text {uniqueid}
Query Parameters: - phone – unique name of the phone to update
Status Codes: - 200 OK – request done
- 400 Bad Request – Bad request (if you don’t pass the parameter)
- 500 Internal Server Error – an exception occured
CUCM calls¶
Overview¶
List of methods used in this application and consequences on CUCM AXL Service.
Method | Action | Uses |
---|---|---|
Get phone info | Read | SQL, AXL |
Update speed dials | Update | AXL |
Get phone info¶
Used in Phone endpoint, it does two read-only operations:
- SQL query to find names of phone matching a directory number
- Get detailed information about every phone, by its phone name (GetPhoneReq)
Update speed dials¶
Used in Speeddials endpoint, it does one update operation:
- Do an UpdatePhoneReq for a given phone name
API¶
Javadoc¶
uk.ac.ox.it.cha¶
CucmHttpApiService¶
-
class
CucmHttpApiService
extends Service<AppConfiguration>¶ Main entry point of the application
Author: martinfilliau
Methods¶
-
public void
initialize
(Bootstrap<AppConfiguration> bootstrap)¶
-
public void
run
(AppConfiguration configuration, Environment environment)¶