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


   /<base>/
   |
   |-- <AOR>/
       |
       |-- 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/<AOR>/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
   /<AOR>/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 <resource> 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:

     <?xml version='1.0' encoding='UTF-8' standalone='YES'?>
     <resource>
       <status>enabled</status>
     </resource>

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

   <IANA considerations text>


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:

     <dl class="resource">
       <dt class="key">status</dt>
       <dd class="value">disabled</dd>
     </dl>

   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:

   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
       "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   <html xmlns="http://www.w3.org/1999/xhtml">
   <head>
     <meta http-equiv="content-type" content="text/html;
           charset=utf-8" />
     <title>ACH Settings</title>
   </head>
   <body>
     <dl class="resource">
       <dt class="key">status</dt>
       <dd class="value">disabled</dd>
     </dl>
   </body>
   </html>


   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:

   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
       "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   <html xmlns="http://www.w3.org/1999/xhtml">
   <head>
     <meta http-equiv="content-type" content="text/html;
           charset=utf-8" />
     <title>ACH Settings</title>
     <style type="text/css">
       dt { font-weight: bold; float: left; width: 5em;
            background-color: #ccc; }
          dd { margin: 0 0 0.5em 0; float: left; }
     </style>
   </head>
     <body>

       <dl class="resource">
         <dt class="key">status</dt>
         <dd class="value">disabled</dd>
       </dl>

     </body>
   </html>




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]