This is the remote management protocol for E164.org.
Status: active.
Protocol Version: 1.0
General notes
This protocol allows for remote applications to update the service profiles associated with E164.org verified PSTN numbers. It does not allow registration or modification of the PSTN number itself, nor registration of user accounts.
The protocol uses HTTPS to an API URL. Talk to matthewa on #e164 or #bcwireless on irc.bcwireless.net for the API URL, or if you have any questions about this protocol.
This protocol requires the use of SSL.
Commands TO the API are POST encoded.
Replies FROM the API are NOT POST encoded.
note: \r\n are C escape characters refering to a CR and NL. It is assumed lines end with this pair. In the examples below, \r\n is used to show a blank line or to clarify ambigouity.
Reponse format
Reply format looks like this:
HTTP/1.0 200 Ok ... headers ... \r\n version=1 response=OK|BAD other_things=stuff... \r\n \r\n ... optional data (command specific) ... .\r\n
Response sections are seperated by a CR and LF (\r and \n);
The three response sections are: * HTTP headers - server stuff * Command response variable=value pairs * Optional command specific response. Typically comma delimited values for each row of a record, one per line
End of data is marked with ".\r\n";
Note: All variable and value names are urlencoded in the same vein as the application/x-www-form-urlencoded mime type. See http://php.net/urlencode for quirks.
The following command response variables are always set:
* response : Status of the request, either OK for a succesfull query, or BAD for a failed query * version : The protocol version
Command requests
Command requests look like:
POST /some/uri/that/you/need/to/ask/for HTTP/1.0 Host: www.e164.org Content-Length: length of request User-Agent: name of your client \r\n version=1&command=thecommand&username=yourusername&password=yourpassword&other_data
Each command must include the following:
* command : The command being requested * version : The version of protocol in use * username : The username of the E164.org account being manipulated * password : The password of the E164.org account being manipulated (or use secret below) * secret : the MD5 of the password of the E164.org account being manipulated (or use password above).
secret and password are mutually exclusive of each other. pick one.
Commands
The following commands are supported.
Command |
Description |
ping |
Pings the server. |
list |
Lists PSTN records |
show |
Show a specific PSTN record's ENUM entries |
getnaptr |
Retrieve a specific NAPTR |
delete |
Delete a NAPTR |
deleteall |
Deletes all NAPTR Records |
update |
Update a NAPTR |
new |
Create a new NAPTR |
listservices |
Lists supported NAPTR service types |
ping
Pings the server (NOOP)
Additional Data response:
You never know.
list
Lists numbers associated with a user's account.
Additional Command Response:
numrows=1234
where 1234 is the number of records present.
Additional Data response:
One comma delimited record per line. Fields are:
pstn record id |
country_routing_code |
area_code |
local number |
Note: The area_code may be removed without warning. If this happens, area_code will simply be blank.
show
Show a specific PSTN record (enumerates the ENUM records)
Command Request variables
id=1234
where 1234 is the record id of the number as returned by list
Additional Command Response
numrows=1234
where 1234 is the number of records being returned.
Additional Data response:
One comma delimited record per line. Fields are:
enum record id |
country_routing_code |
area_code |
number |
order |
preference |
servicetype |
hostrecord data |
Example:
52,1,604,9586111,100,10,SIP,9586111@mutual.bcwireless.net 105,1,604,9586111,100,11,IAX,mutual.bcwireless.net
Note: due to policy changes order will always be set to 100 for user records.
delete
Deletes a NAPTR record.
Command Request variables
id=1234 confirm=y
* where 1234 is the record id of the NAPTR record (as returned by list). * confirm must be set to Y to indicate the user really wanted to do it.
Additional Response Data
Nothing.
deleteall
Deletes all NAPTR records for a specific number.
Command Request variables
id=1234 confirm=y
* where 1234 is the record id of the phone record (as returned by list). * confirm must be set to Y to indicate the user really wanted to do it.
Additional Response Data
Nothing.
getnaptr
Retrieve an NAPTR by record id.
Command Request variables:
id=1234
where 1234 is the naptr ID.
Additional Response Data
Returns a comma delimited record:
52,1,604,9586111,100,10,SIP,9586111@mutual.bcwireless.net
enum record id |
country_routing_code |
area_code |
number |
order |
preference |
servicetype |
hostrecord data |
Note: due to policy changes order will always be set to 100 for user records.
update
Update a NAPTR record.
Command request
id=1234
where 1234 is the record id of the NAPTR record being updated.
Additional request variables
Name |
Description |
order |
naptr order # |
preference |
napatr preference |
service |
naptr service type (SIP, H323, MAILTO etc.) |
hostdata |
the host data |
Additional data returned:
nothing.
Note: due to policy changes order will always be set to 100 for user records.
new
Add a NAPTR to a PSTN record.
Command request
id=1234
where 1234 is the record ID of PSTN record this naptr is being added to
Additional request variables
Name |
Description |
order |
naptr order # |
preference |
naptr preference |
service |
naptr service type (SIP, H323, MAILTO etc.) |
hostdata |
the host data |
Additional data returned:
nothing.
Note: due to policy changes order will always be set to 100 for user records.
listservices
Lists supported ENUM services.
Additional data returned
A comma delimited list of supported services
myip
Returns the IP address of the client.