Routing Web Service API Programming Reference Release 6.3 Issue 2 August 2014 Contents Chapter 1: Getting started........................................................................................................ 4 Functional Scope .................................................................................................................... 4 RESTful Based Web Service.................................................................................................... 4 RESTful Best Practice Divergence............................................................................................ 5 Web Service Development Assumptions................................................................................... 6 RESTful Client Development Assumptions................................................................................ 6 Setup a Session Manager for testing......................................................................................... 7 Gaining REST API Familiarity using Browser Tools.................................................................... 8 SSL/TLS Trust Setup............................................................................................................... 9 Java JKS trust certificate store......................................................................................... 10 What is in the SDK zip........................................................................................................... 10 Working with the Java samples.............................................................................................. 11 Chapter 2: Connection Management, HTTP transport, and header control...................... 13 SSL/TLS Connection............................................................................................................. 13 Authentication and Authorization............................................................................................ 13 HTTP method support........................................................................................................... 14 POST/PUT semantic clarification............................................................................................ 14 OPTIONS support................................................................................................................. 15 HTTP Response Status Codes............................................................................................... 16 HTTP Header Properties........................................................................................................ 17 Accept property API version control........................................................................................ 17 Content control through Content-Type, Accept......................................................................... 17 GZIP content compression, Accept-Encoding, Content-Encoding.............................................. 18 Location............................................................................................................................... 18 ETag header in responses..................................................................................................... 19 Chapter 3: URI Resource referencing, format, and mapping............................................. 21 URI Templates...................................................................................................................... 21 Resource Naming and Routing Resource Mapping.................................................................. 22 Resource identification and "least worst" solution of DB surrogate ids........................................ 23 Content format...................................................................................................................... 24 Null value handling................................................................................................................ 26 Collections, Containment, and Referencing............................................................................. 27 Single entity response and query result response.................................................................... 28 Query request and responses................................................................................................ 29 Error content format............................................................................................................... 31 Chapter 4: Resource API Examples...................................................................................... 32 Required Request Headers.................................................................................................... 32 Domains ............................................................................................................................. 32 Locations.............................................................................................................................. 35 2 Routing Web Service API Programming Reference August 2014 Comments? [email protected] Contents Adaptations........................................................................................................................... 40 SIP Entities........................................................................................................................... 47 Entity Links........................................................................................................................... 57 Time Ranges ....................................................................................................................... 62 Routing Policies ................................................................................................................... 65 Dial Patterns......................................................................................................................... 73 Regular Expressions.............................................................................................................. 79 Chapter 5: Resource Java JAX-RS Examples...................................................................... 83 Resource Java Jax-RS Examples........................................................................................... 83 Domains............................................................................................................................... 84 Locations.............................................................................................................................. 85 Adaptations........................................................................................................................... 87 Dial Patterns......................................................................................................................... 89 Chapter 6: Limitations Known Issues................................................................................... 91 Limitations............................................................................................................................ 91 Known Issues....................................................................................................................... 92 August 2014 Routing Web Service API Programming Reference 3 Comments? [email protected] Chapter 1: Getting started Functional Scope This interface is provided as one of the Web Services comprising the System Manager Web Service. The Web Service provides programmatic access to all Routing administration data. It provides access for adding, modifying, and deleting any of the Routing data which can be modified by the GUI. Almost all interactions which can be accomplished via this API can also be accomplished in the System Manager -> Routing GUI. So when in doubt, test out the operation in the GUI. Additionally, this Web Service is subject to the same business logic and validation enforced by the GUI and Import features. Review the Routing export file formats to gain a deeper understanding of the content format described elsewhere in this document. The Web Service aligns with data representation of the Routing import/export format where possible. Most representation divergence is found in URI resource naming conventions. This was done to provide more meaningful URI names that have alignment with the GUI terminology, not the somewhat out of date element conventions found in the Routing XML. Only use this API for provisioning changes. Do not use this API for dynamic, call processing application, or real time modifications. RESTful Based Web Service The Web Service is based entirely on (Representational State Transfer) RESTful practices. This is a programmatic API, NOT a remote bulk import/export API as found in the System Manager Web Service for User Management. Routing already has an optimized bulk interface via the GUI Import/ Export features. This API is very focused on a URI resource driven approach. It is not a hypermedia based approach per HATEOAS school of REST nor is it designed for "live web" sorts of browser driven applications. RESTful Best Practice Alignment • Document by example so users do not have to do mental context shifts from some service description level abstraction to develop their client application. In general, make the API semantically straightforward and reduce complexity wherever possible. • Stateless API • Support for HTTP GET/POST/PUT/DELETE method semantics for create, modify, delete and query operations 4 Routing Web Service API Programming Reference August 2014 Comments? [email protected]