INTERNET-DRAFT R. Shekh-Yusef Intended Status: Standards Track Avaya Expires: May 14, 2011 T. Zourzouvillys VoIP.co.uk Nov 10, 2010 ACH RESTful Interface draft-yusef-dispatch-ach-rest-api-01 Abstract This document defines a RESTful interface that allows a RESTful client to directly affect the Automatic Call Handling (ACH) behavior at a domain authoritative for a specific SIP address. Status of this Memo This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/1id-abstracts.html The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html Shekh-Yusef Expires May 14, 2011 [Page 1] INTERNET DRAFT ACH RESTful Interface Nov 10, 2010 Copyright and License Notice Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Shekh-Yusef Expires May 14, 2011 [Page 2] INTERNET DRAFT ACH RESTful Interface Nov 10, 2010 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 4. General HTTP requirements . . . . . . . . . . . . . . . . . . . 5 5. Configuration Scope . . . . . . . . . . . . . . . . . . . . . . 6 6. Base URI Discovery . . . . . . . . . . . . . . . . . . . . . . 6 7. Resource Design . . . . . . . . . . . . . . . . . . . . . . . . 6 7.1. Resources . . . . . . . . . . . . . . . . . . . . . . . . . 6 7.2. Methods . . . . . . . . . . . . . . . . . . . . . . . . . . 8 7.3. Representations . . . . . . . . . . . . . . . . . . . . . . 9 7.3.1. application/xml . . . . . . . . . . . . . . . . . . . 9 7.3.2. application/x-www-form-urlencoded . . . . . . . . . . 9 8. Call Forwarding . . . . . . . . . . . . . . . . . . . . . . . 10 8.1. Classes . . . . . . . . . . . . . . . . . . . . . . . . . 10 8.1.1. all . . . . . . . . . . . . . . . . . . . . . . . . 10 8.1.2. no-answer . . . . . . . . . . . . . . . . . . . . . 10 8.1.3. unreachable . . . . . . . . . . . . . . . . . . . . 10 8.1.4. busy . . . . . . . . . . . . . . . . . . . . . . . . 11 8.2. Resources . . . . . . . . . . . . . . . . . . . . . . . . 11 8.2.1. target . . . . . . . . . . . . . . . . . . . . . . . 11 8.2.2. status . . . . . . . . . . . . . . . . . . . . . . . 11 8.2.3. timeout . . . . . . . . . . . . . . . . . . . . . . 11 9. Call Barring . . . . . . . . . . . . . . . . . . . . . . . . 12 9.1. Classes . . . . . . . . . . . . . . . . . . . . . . . . . 12 9.1.1. Incoming Call Barring . . . . . . . . . . . . . . . 12 9.1.2. Outgoing Call Barring . . . . . . . . . . . . . . . 12 9.2. Resources . . . . . . . . . . . . . . . . . . . . . . . . 12 10. Do Not Disturb (DND) . . . . . . . . . . . . . . . . . . . . 13 10.1. status . . . . . . . . . . . . . . . . . . . . . . . . . 13 10.2. reason . . . . . . . . . . . . . . . . . . . . . . . . . 13 11. Monitoring Changes . . . . . . . . . . . . . . . . . . . . . 13 12. Security Considerations . . . . . . . . . . . . . . . . . . . 13 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 14.1. Normative References . . . . . . . . . . . . . . . . . 14 14.2. Informative References . . . . . . . . . . . . . . . . 14 15. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 14 Author's Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 Appendix A. . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 A.1. Accepted . . . . . . . . . . . . . . . . . . . . . . . . 16 A.2. Served . . . . . . . . . . . . . . . . . . . . . . . . . 16 Shekh-Yusef Expires May 14, 2011 [Page 3] INTERNET DRAFT ACH RESTful Interface Nov 10, 2010 1. Introduction The Session Initiation Protocol (SIP) [RFC3261] is a protocol used for establishing calls for real-time communication between users. Some systems allow for automatic treatment of calls arriving to a specific user. Some of this treatment takes place before the call is presented to the endpoint, while others take place after the endpoint has received the call indication. Some automatic treatment can be set by the system administrator while others can be set by the end user. This automatic treatment of incoming calls is referred to as automatic call handling (ACH). This document is focused on the automatic call handling (ACH) features described in the "An Analysis of Automatic Call Handling (ACH) Implementation Issues in the Session Initiation Protocol (SIP)" draft. This document defines a RESTful interface that allows a RESTful client to directly affect the Automatic Call Handling (ACH) behavior at a domain authoritative for a specific SIP address. 2. Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119]. Shekh-Yusef Expires May 14, 2011 [Page 4] INTERNET DRAFT ACH RESTful Interface Nov 10, 2010 3. Scope This document is limited to a subset of network provided features and does not support more complex operations such as time-of-day routing. The following features will be provided in the first version of this protocol: 1. Call forwarding: a. unconditional (all calls) b. on busy c. no answer d. not reachable 2. Barring a. incoming b. outgoing 3. DND - Do Not Disturb OPEN-ISSUE: Should this document try to address other features? 4. General HTTP requirements The HTTP server that implements this service MUST support HTTP/1.1. Any client accessing this service MUST support HTTP/1.1 [RFC2616], and HTTP Digest authentication [RFC2617]. The service MUST NOT use cookies and MUST NOT rely on cookie support being provided by the HTTP user agent. Shekh-Yusef Expires May 14, 2011 [Page 5] INTERNET DRAFT ACH RESTful Interface Nov 10, 2010 5. Configuration Scope The actions taken under the control of the configuration settings established by these RESTful operations are made at the system authoritative for the domain part of the AOR. This has the implication that any configuration change will apply to all bindings for the AOR. 6. Base URI Discovery This document does not define any mechanism for discovering a base URI for this service. A base URI can be configured on the UA or discovered by other means that are outside the scope of this document. 7. Resource Design This interface exposes a static list of descriptive resources that represent various services. 7.1. Resources The following tree describes a hierarchical structure of the ACH resources exposed by this service: Shekh-Yusef Expires May 14, 2011 [Page 6] INTERNET DRAFT ACH RESTful Interface Nov 10, 2010 // | |-- / | |-- ach/ | |-- barring/ | | | |-- incoming/ | | | | | |-- all | | |-- anonymous | | | |-- outgoing/ | | | |-- all | |-- premium | |-- tollfree | |-- dnd/ | | | |-- status | |-- reason | |-- forwarding/ | |-- all/ | | | |-- status | |-- target | |-- busy/ | | | |-- status | |-- target | |-- noanswer/ | | | |-- status | |-- target | |-- timeout | |-- unreachable/ | |-- status |-- target Shekh-Yusef Expires May 14, 2011 [Page 7] INTERNET DRAFT ACH RESTful Interface Nov 10, 2010 The root URI represents a context that contains all the resources managed by the service. All resources are created by the system and the service does not provide the RESTful client with an interface to create or destroy resources. Every AOR in the system has the above set of resources. A resource URI can be selected by creating a sequence of path segments starting from the root. For example, if the root URI is https://ach.api.example.com, then the path for DND status would be https://ach.api.example.com//ach/dnd/status While a URI can be created from a sequence of path segments starting from the root that does not include a leaf, only the leaves of the above tree expose an actual resource. If a client attempts to access a non-leaf node, the server MUST respond with 404 Not Found. The interface may provide additional resources under each AOR, and an interface may not implement all of the above resources. OPEN ISSUE: Should this service define resources for non-leaf nodes? e.g. should the service expose a resource for the //ach/forwarding URI to allow a client to get the current values of all the resources under forwarding? TODO: HTTP path segments escaping policy 7.2. Methods This service MUST support the methods GET and PUT. If an attempt is made by a client to access a resource with the POST or DELETE methods, the service MUST respond with 504 Method Not Allowed and MUST specify the allowed methods in the Allow header of the response. A client uses the GET method to get the content of a resource and uses the PUT method to update the content of a resource. Shekh-Yusef Expires May 14, 2011 [Page 8] INTERNET DRAFT ACH RESTful Interface Nov 10, 2010 7.3. Representations This section describes the representations accepted and served by the service. The representation defines the data format exchanged between the client and the server. This document presents the following two options: 7.3.1. application/xml The Content-Type accepted and served by this service is application/xml. The XML document MUST have a element as the root element of the document. Any resource MUST be represented by a non-complex child element of the root element. The following document is an example XML document that represent the 'status' resource: enabled 7.3.2. application/x-www-form-urlencoded The Content-Type accepted and served by this service is application/x-www-form-urlencoded. This representation format is a very simple format that represents the data in a key-value pairs. The key is separated from the value by '=' and the pairs are separated from each other by '&'. With this service, the key would be the resource and the value would be the settings of the resource. The following is an example of a PUT request to update the resource ach.api.example.com/AOR/ach/dnd/status to the value "enabled". PUT /AOR/ach/dnd/ HTTP/1.1 Content-Type: application/x-www-form-urlencoded Host: ach.api.example.com Content-Length: 14 status=enabled OPEN-ISSUES: Which one of the above representations should we use? See Appendix A for more on this subject. Shekh-Yusef Expires May 14, 2011 [Page 9] INTERNET DRAFT ACH RESTful Interface Nov 10, 2010 8. Call Forwarding The call forwarding setting requests that the SIP proxy forwards all calls received for the given AOR to the configured target URI. 8.1. Classes This document defines the following classes: 1. all 2. busy 3. no-answer 4. unreachable If, regarding a particular call, more than one class is applicable, then the priority between the classes is as listed above, with "all" as the highest priority and "unreachable" as the lowest one. OPEN ISSUE: a combination between "all" and any other class does not make sense. Do we want to enforce some logic on the user or we just leave it up to the user/client? 8.1.1. all This class applies at all times, and is also commonly known as "unconditional call forwarding". In this case the proxy forwards the call to the forward target URI without attempting to contact the contacts of the AOR. 8.1.2. no-answer This class applies after a given number of seconds passed from the time the INVITE was originally processed. The proxy sends the INVITE to the destination client or forks the INVITE to the registered clients. If there was no answer after a define time, the proxy cancels all the existing dialogs and forwards the INVITE to the call forward target URI. 8.1.3. unreachable This class applies when this AOR is unreachable, which could be either due to no bindings being available, or each of them has returned a final failure response other than the following error codes: 486 (Busy Here), 600 (Busy Everywhere) and 603 (Decline). It also applies when bindings are available but an attempt to reach the client was timed out. Shekh-Yusef Expires May 14, 2011 [Page 10] INTERNET DRAFT ACH RESTful Interface Nov 10, 2010 8.1.4. busy This class applies when bindings are available, but each returns a 486 (Busy Here). It also applies if any of the devices returns 600 (Busy Everywhere) or 603 (Decline). 8.2. Resources All resources exposed by this service MUST be of the type UTF-8 string. This API exposes the following call forwarding resources: 8.2.1. target This resource SHOULD be set to the target SIP URI of the call forwarding class. This is the target that will be used by the proxy to forward the call to, when this class is triggered. This service will not initialize this resource; it is the responsibility of the client to make sure that this resource has a proper value. If a client tries to set this resource to an empty string while the 'status' resource is in the 'enabled' state, the service MUST return the error code 403 Forbidden. 8.2.2. status This resource MUST take one of the values 'enabled' or 'disabled', to set the status of the specific call forwarding class. By default, the resource MUST be set to "disabled". If a client tries to set this resource to "enable" while the value of the target resource is empty, the service MUST return the error code 403 Forbidden. 8.2.3. timeout This resource SHOULD be set with the number of seconds the server must wait for the arrival of a specific response, before forwarding the call to the call forwarding target. By default, the resource MUST be set to 30 seconds. Shekh-Yusef Expires May 14, 2011 [Page 11] INTERNET DRAFT ACH RESTful Interface Nov 10, 2010 9. Call Barring The barring settings request that the SIP proxy prevents incoming calls to a specific AOR. 9.1. Classes This service defines the following classes: 9.1.1. Incoming Call Barring This barring setting request the proxy to prevent incoming calls to a specific AOR. The service can prevent all incoming calls or anonymous calls only. When enabled, the proxy MUST return 403 Forbidden to indicate to the remote client that his call is forbidden. 9.1.2. Outgoing Call Barring This barring setting request the proxy to prevent outgoing calls initiated from a specific AOR. The service can prevent all outgoing calls, premium calls or toll-free calls. When enabled, the proxy MUST return 403 Forbidden to indicate to the local client that his call is forbidden. 9.2. Resources This service exposes the following call barring resources: 1. all 2. anonymous 3. premium 4. tollfree All these resources MUST take one of the values 'enabled' or 'disabled'; by default, the resource MUST be set to 'disabled'. Shekh-Yusef Expires May 14, 2011 [Page 12] INTERNET DRAFT ACH RESTful Interface Nov 10, 2010 10. Do Not Disturb (DND) DND provides a mechanism to automatically reject all calls to an AOR with a status code and reason phrase configured by the user. When enabled, the proxy MUST return 480 Temporarily Unavailable. As described in RFC 3261, the response MAY indicate a better time to call in the Retry-After header field, and the reason phrase SHOULD indicate a more precise cause as to why the callee is unavailable. When the reason resource is not an empty string, the service MUST use it with the 480 response. This service exposes the following resources: 10.1. status This resource sets the status of the DND feature and MUST take one of the values 'enabled' or 'disabled'; by default, the resource MUST be set to 'disabled'. 10.2. reason This resource sets the reason for the activation of the DND feature. By default, the resource MUST be set to an empty string. 11. Monitoring Changes A client can use the method described in draft-roach-sip-http- subscribe to monitor a resource, to allow it to reflect a change to a resource setting made by other clients. TODO: More details to follow. How does the client get a subscription URI? 12. Security Considerations The service MUST use TLS to ensure the confidentiality and integrity of the communication with the clients. The service MUST use HTTP Digest to ensure that only authorized users can access their resources. Shekh-Yusef Expires May 14, 2011 [Page 13] INTERNET DRAFT ACH RESTful Interface Nov 10, 2010 13. IANA Considerations 14. References 14.1. Normative References [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3261] J. Rosenberg, H. Schulzrinne, G. Camarillo, A. Johnston, J. Peterson, R. Sparks, M. Handley, E. Schooler, "SIP: Session Initiation Protocol", June 2002 [RFC2616] R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", June 1999 [RFC2617] J. Franks, P. Hallam-Baker, J. Hostetler, S. Lawrence, P. Leach, A. Luotonen, L. Stewart, "HTTP Authentication: Basic and Digest Access Authentication", June 1999 14.2. Informative References [draft-ietf-bliss-ach-analysis-06] J. Elwell, "An Analysis of Automatic Call Handling (ACH) Implementation Issues in the Session Initiation Protocol (SIP) ", March 2010 [draft-zourzouvillys-bliss-ach-http-api-01] T. Zourzouvillys, "Basic HTTP API interface for ACH", March 2009 15. Acknowledgements This draft is based on the BLISS draft "Basic HTTP API interface for ACH". Special thanks to Scott Lawrence for his guidance, careful review and valuable feedback and to Dale Worley for his detailed review and valuable feedback. The authors would also like to thank Alan Johnston and John Elwell for their review and comments. Shekh-Yusef Expires May 14, 2011 [Page 14] INTERNET DRAFT ACH RESTful Interface Nov 10, 2010 Author's Addresses Rifaat Shekh-Yusef Avaya 250 Sidney Street Belleville, Ontario K8P 5B7 Canada Phone: +1-613-967-5267 Email: rifatyu@avaya.com Theo Zourzouvillys VoIP.co.uk Commerce House Telford Road Bicester, Oxfordshire OX26 4LD UK Phone: +44 1908 764 181 Email: theo@voip.co.uk Shekh-Yusef Expires May 14, 2011 [Page 15] INTERNET DRAFT ACH RESTful Interface Nov 10, 2010 Appendix A. The purpose of this section is to discuss the idea of defining one representation that will be applicable to both a RESTful client and an HTML browser. A.1. Accepted The Content-Type that is accepted from the clients by this service is application/x-www-form-urlencoded. This representation format is a very simple format that represents the data in a key-value pairs. The advantage of this representation is its simplicity and the fact that it is used by the web browsers to submit an HTML form. This means that the same interface can be utilized by both the web browsers and any RESRful client of this service. For backward compatibility with browsers that do not support the PUT action in HTML forms, the service MUST support POST request to update a resource value. A.2. Served The Content-Type served to the clients by this service is application/xhtml+xml. This service will use the following key-value pair structure to represent a resource:
status
disabled
The HTML "dl" element defines a definition list. The "dl" element is used in conjunction with "dt" and "dd" elements, which represent a term and definition pairs. The "dt" element represents the term while the "dd" represents the definition. With the above structure, the "dl" element represents the resource, the "dt" element represent the resource name and the "dd" element represents the value of the resource. Shekh-Yusef Expires May 14, 2011 [Page 16] INTERNET DRAFT ACH RESTful Interface Nov 10, 2010 The following is an example XHTML document served to clients: ACH Settings
status
disabled
Styles can be added to the above document without impacting the semantics of the resource representation. The following document is the same as the above with some styles added to display the parameter and the value in one line with some background added to the parameter: ACH Settings
status
disabled
Shekh-Yusef Expires May 14, 2011 [Page 17] INTERNET DRAFT ACH RESTful Interface Nov 10, 2010 Explanation ----------- The idea of building a structure that represent a resource by utilizing the existing HTML elements built into an XHTML document came from the Microformats idea. (http://microformats.org/wiki/Main_Page). The above XHTML document is a bare minimum document with the body contains only the structure of the served resource. In a real scenario, this document can be a full blown, very rich XHTML document with the resource structure defined by this service embedded into it. This XHTML document can be served to a RESTfull client or an HTML browser. The browser would be able to immediately render it without any further processing or it can include a JavaScript code to manipulate the document, while a RESTfull client would easily be able to extract the needed resource structure. This is by no means an attempt to define a UI in any shape or form. It is only an attempt to allow one representation to be served to two different clients and to allow each one of them to use it as it sees fit. Another option is for the service to serve both a web representation and a non-web representation. But this will require the service provider to maintain two separate representations which defeats the whole purpose of the idea above. Any thoughts? Shekh-Yusef Expires May 14, 2011 [Page 18]