Overview

What's the deal with tac3? Overall themes:

1. role-based security (leverages level1_access and ui_config)
   
2. better semantics thru better messaging (i.e., not a database passthru)
3. better documentation (i.e., recipes)
   
4. lay down a foundation so that we can add things like data validation (both value-space-wise and security-wise)
   
5. 
   
6. 
   

improvements:

1. simplified xml format
2. no need for (annoying) trailing slashes
   

best practice (as a client-side api user):

1. ignore the document root element tag name
1. e.g., <cdrs>, <subscribers>, ignore the document root element tag name (### need better example here ###)
   
2. do not parse the url for key/value pairs; use key/value pairs from the xml document instead
1. 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)
2. said another way: treat paths as opaque
   
3. be sure to percent encode path components!!!
1. e.g.,
4. etc...
   

goal(s) of tac3:

1. move away from CRUD database passthru and move toward 'actions'/'messages'... in other words: *intents*
1. said another way: try to capture the client api user's *intent*, not 'how'
   
2. 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)
   
3. 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.com

setSubscriber

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.com

to 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&parameter=1800GOOG411

control=e means 'enable'; control=d means 'disable'

POST /api/domains/acme.com/subscribers/1212/for
control=d&parameter=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

participants

to 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

Edit this page (if you have permission) | Report abuse

Google Docs -- Web word processing, presentations and spreadsheets.