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]