Overview
What's the deal with tac3? Overall themes:
- role-based security (leverages level1_access and ui_config)
- better semantics thru better messaging (i.e., not a database passthru)
- better documentation (i.e., recipes)
- lay down a foundation so that we can add things like data validation (both value-space-wise and security-wise)
improvements:
- simplified xml format
- no need for (annoying) trailing slashes
best practice (as a client-side api user):
- ignore the document root element tag name
- e.g., <cdrs>, <subscribers>, ignore the document root element tag name (### need better example here ###)
- do not parse the url for key/value pairs; use key/value pairs from the xml document instead
- that
is, given the path "/domains/acme.com/subscribers/1029", do not attempt
to parse the path for acme.com and 1029; instead, use the xml
document's aor_user and aor_host (less brittle)
- said another way: treat paths as opaque
- be sure to percent encode path components!!!
- e.g.,
- etc...
goal(s) of tac3:
- move away from CRUD database passthru and move toward 'actions'/'messages'... in other words: *intents*
- said another way: try to capture the client api user's *intent*, not 'how'
- encourage
best practices learned from tac1/tac2 (e.g., use dumbed down xml vs
html (avoid <div> tag trip ups), refrain from parsing path
segments)
- add security, i.e., access control mechanisms...
lay down a code-base foundation that is conducive toward adding security
+ new actions/messages (tac2 is not that framework, neither interface
nor implementation)
Getting Started
As
the user of the tac3 api you need to first get (a) the network address
of a netsapiens platform and (b) login/password credentials; I'll wait
while you go get the credentials... You're back? Great:
tac3 uses http basic auth (therefore you probably wanna use tac3 over ssl)
Let's assume that the network address of the netsapiens platform is 2.3.4.5.
% curl http://2.3.4.5/api/cdr
probably didn't work; not enough information? use -v
curl -v http://2.3.4.5/api/cdr
probably didn't work; need to use ssl?
curl -k https://2.3.4.5/api/cdr
probably didn't work; certificate error? use -k
curl -kv https://2.3.4.5/api/cdr
probably didn't work; 401 unauthorized? use -u
% curl -kv -u"mylogin:mypassword" https://2.3.4.5/api/cdr
should return a list of the latest cdrs; phew!getDomains
/cdr
To get the .wav file for a cdr append ?wav, e.g.,
GET /api/cdr/20091231235959102938,1pq02ow93ie84ur75yt6%40local?wav
200 OK
Content-Type: audio/wav
/calls
to get the calls:
GET /api/calls
to get the call count:GET /api/calls?count
200 OK
Content-Type: text/plain
123
to make a call:curl http://localhost/api/calls -dto=1800GOOG411
curl http://localhost/api/calls -dto=1800GOOG411 -dfrom=2125551212
curl http://localhost/api/calls -dto=1800GOOG411 -dfrom=http://www.myserver.com/welcome.wav
200 OK
Location: http://localhost/api/calls?callid=20091231235959@acme.com
to cancel a call:curl http://localhost/api/calls?callid=20091231235959@acme.com -dcancel
curl http://localhost/api/calls/{orig_callid},{term_callid} -dcancel
where orig_callid and/or term_callid is from a prevous GET or POST
to transfer a call:
% curl http://localhost/api/calls/{orig_callid},{term_callid} -dtransfer=2125551212
createDomain
POST /api/domains/mydomain.com
POST /api/resellers/TheReseller/domains/mydomain.com
deleteDomain
getSubscribers
GET /api/domains/mydomain.com/subscribers
createSubscriber
* automatically create nps account? (DWang : can be a parameter in the
Request to create the corresponding NAS Account, or a knobs in the
system to designate whether the NAS account should be auto created. A
NAS accoutn will require more paramter, e.g. initial balance)
Example: from reseller's perspective: create subscriber 1212
POST /api/domains/acme.com/subscribers
aor_user=1212
302
Location: /api/domains/acme.com/subscribers/1212
Note- automatically sets subscriber_login=
1212@mydomain.comsetSubscriber
Example: from reseller's perspective: create subscriber 1212
POST /api/domains/mydomain.com/subscribers/1212
firstname=Homer
lastname=Simpson
subscriber_pin=1234
302
Location: /api/domains/mydomain.com/subscribers/1212
Note- automatically sets subscriber_login=
1212@mydomain.comto enable 'do not disturb':
% curl .../subscribers/1212 -ddnd_control=e
to administratively enable 'do not disturb':
% curl .../subscribers/1212 -ddo_not_disturb=yes
to set a simultaneous ring number:
% curl .../subscribers/1212 -dsim_parameter=2125551212
to set two simultaneous ring numbers:
% curl .../subscribers/1212 -dsim_parameter=2125551212\ 8585551212
createDevice
POST /api/domains/mydomain.com/subscribers/1212/devices
termination_match=sip:3434@mydomain.com
setDevice
updates the parameters of existing device:
POST /api/domains/mydomain.com/subscribers/1212/devices/sip:3434@mydomain.com
nat_wan=automatic
deleteDevice
DELETE /api/domains/mydomain.com/subscribers/1212/devices/sip:3434@mydomain.com
getMacs
GET /api/mac
Gets the list of provisioned mac address.
provisionMac
POST /api/mac
mac=001212001212&brand=zzz&domain=mydomain.com&server=zzz.com
brand is one of:
if (tac login) then territory is the territory to provision the device to
if (tac or territory login) then domain is the domain to provision the device to, e.g., "acme.com"
server is a valid sipbx server (should be provided to reseller)
###internal note: use phones_config.territory ###
setMac
POST /api/mac/001212001212
device1=sip:1212@mydomain.com&device1_enable=yes
where:
deviceX is a valid termination_match from /api/.../devices (X is 1-12)
deviceX_enable=yes or no (X is 1-12)
deprovisionMac
DELETE /api/mac/001212001212
200 OK
getAvailDids
this message relies on a convention:
convention:
assuming that there is a dialplan called "thereseller-avail" that is
used to park available dids for the reseller; that is, the platform
provider would have, before hand, created the "thereseller-avail"
dialplan and populate it with dids, through some other means.
The reseller would have to be told this information out-of-band.
GET /api/domains/mydomain.com/dialplans/thereseller-avail-dids
assignDid(Did availDid, SubscriberId to)
kinda like a 'move' ?!?
assume a convention whereby the reseller parks available dids in a dialplan called "thereseller-avail"
/api/domains/{domain}/dialplans/{dialplan}/dialrules/{termination_match}
POST /api/domains/acme.com/dialplans/thereseller-avail/dialrules/sip:2125551212@*
dialplan=mydomain.com
from_name=[*]
from_scheme=sip:
from_user=[*]
from_host=[*]
to_scheme=sip:
to_user=1212
to_host=mydomain.com
responder=sip:start@to-user
plan_description=2125551212
POST /api/domains/acme.com/dialplans/thereseller-avail/dialrules/sip:2125551212@*
dialplan=Default%20dialplan%20for%20mydomain.com
this effectively saying: please rename the dialplan from
"thereseller-avail" to "Default dialplan for mydomain.com" (the old
dialplan is encoded in the {dialplan} path component, the new diaplan is
encoded int the X_WWW_URL_FORM_ENCODED dialplan key/value pair)
idea:
instead of having user say "sip:2125551212@*" how about letting 'em
specify just the user part, 2125551212 and then we'll default to
scheme=sip: and host=* for sip:2125551212@*
unassignDid(Did did)
POST /api/domains/acme.com/dialplans/Default%20dialplan%20for%20mydomain.com/dialrules/sip:2125551212@*
dialplan=thereseller-avail
dialplans
to get the dial plans for the domain "acme.com":
GET /api/domains/acme.com/dialplans
dialrules
to get the dial rules for the dial plan "foo":
GET /api/domains/acme.com/dialplans/foo/dialrules
to update the dial rule "bar" under the dial plan "foo":
POST /api/domains/acme.com/dialplans/foo/dialrules/bar
responder=to-user&to_user=1212&to_host=acme.com
the following parameters may be updated:
to_scheme e.g., "sip:"
to_user e.g., "1212"
to_host e.g., "acme.com"
responder e.g., "to-user"
rule_description e.g., "maps from did 2125551212 to user 1212"
subscriber features (e.g., vmail, call forwarding, etc...)
Voicemail
admin
vs
subscriber
POST /api/domains/acme.com/subscribers/1212
vmail_admin=yes
enable voicemail from the user's perspective:
POST /api/domains/acme.com/subscribers/1212
vmail=e
Forward Always
to administratively enable call forwarding:
POST /api/domains/acme.com/subscribers/1212
forward=yes
to configure call forwarding:
POST /api/domains/acme.com/subscribers/1212
for_control=e¶meter=1800GOOG411
control=e means 'enable'; control=d means 'disable'
POST /api/domains/acme.com/subscribers/1212/for
control=d¶meter=1800GOOG411
Forward Busy
POST /api/domains/acme.com/subscribers/1212
fbu=e
Forward No Answer
allow the user to enable 'forward no answer'
POST /api/domains/acme.com/subscribers/1212
fna=e
Forward Busy (admin)
allow the user to enable 'forward busy'
POST /api/domains/acme.com/subscribers/1212
fbu=e
Do Not Disturb
admin
POST /api/domains/acme.com/subscribers/1212
do_not_disturb=yes
subscriber:
POST /api/domains/acme.com/subscribers/1212
do_not_disturb=yes
to add a sim ring:
POST /api/domains/acme.com/subscribers/1212/sim_parameters -d2125551212
to remove a sim ring:
POST /api/domains/acme.com/subscribers/1212/sim_parameters/2125551212 -dremove
adjustBalance
from reseller's perspective:
Example: add $5.00 to mydomain.com
POST /domains/mydomain.com ?!? HUH ?!? THIS DOES NOT MAKE SENSE RIGHT NOW ### TODO ###
balance=+5
sideeffects: subtracts $5.00 from the domain's reseller, e.g., "thereseller"
errors: if insufficient funds: 400 bad request
Example: add $5.00 to user 1212
POST /domains/mydomain.com/account/1212
balance=+5
sideeffects: subtracts $5.00 from "mydomain.com" domain
errors: if insufficient funds: 400 bad request
bridges
to get all available bridges:
GET /api/domains/acme.com/subscribers/1029/bridges
participantsto add a participant to a bridge:
POST /api/domains/acme.com/subscribers/1029/bridges/mybridge/participants -dnumber=2125551212
200 OK
Location: /api/domains/acme.com/subscribers/1029/bridges/mybridge/participants/2125551212
to connect a participant:
POST /api/domains/acme.com/subscribers/1029/bridges/mybridge/participants/2125551212 -dconnect
to disconnect a participant:
POST /api/domains/acme.com/subscribers/1029/bridges/mybridge/participants/2125551212 -ddisconnect
to mute a participant:
POST /api/domains/acme.com/subscribers/1029/bridges/mybridge/participants/2125551212 -dmute
to unmute a participant:
POST /api/domains/acme.com/subscribers/1029/bridges/mybridge/participants/2125551212 -dunmute
to remove a participant from a bridge:
POST /api/domains/acme.com/subscribers/1029/bridges/mybridge/participants/2125551212 -dremove