Introduction to REST

The RESTful API allows developers to build applications using Ribbit's core communication services in a platform-agnostic format, using simple and secure HTTP calls. The RESTful API can be accessed directly, or via familiar programming languages such as Flash, PHP, Java, JavaScript, .NET, and others.

The Ribbit RESTful API currently defines eight core resources: Users, Devices, Media, Tokens, Calls, Messages, Applications, and Domains. Each resource represents an entity involved in a communications interaction, and can be referenced using a specific URI. REST uses URIs to identify resources involved in a particular interaction. For example, http:/ribbit.com/rest/1.0/users is a URI that might return a list of users. The URI is the identifier and the resulting list of users is the resource.

Resources can be updated, added, or deleted by sending representations from the client to the server. Access to resources occurs through the HTTP interface. HTTP provides four basic methods for the following operations:

Retrieve information about a resource: HTTP GET
Create a new resource: HTTP POST
Modify an existing resource: HTTP PUT
Delete an existing resource: HTTP DELETE

Getting Started Using Kermit

This tutorial will walk you through the steps for making your first call application using Ribbit's tool, Kermit, a sample JavaScript REST test harness that shows off what the REST API can do.

Prerequisites
1. Sign Up as a Ribbit Developer
2. Start an Application in a private Domain so that you can create Users for your Application.

3. Download Kermit

Step 1: Open the Kermit REST Test Harness

Once you have downloaded Kermit, unzip the file and click index.html to open the REST test harness in your default browser. If your browser asks for permission to run the Kermit REST test harness, you will need to grant it. The opening screen should look like this:

Step 2: Add Your Project Information to Kermit

The project you created in Step 1 has an Consumer Key and a Secret Key. Cut and paste those two numbers into Kermit.

Step 3: Create a User

For an application to do something useful, a user first must be created. To do this, click Resource and select Users from the drop down menu. Then click createUser. It should look like:

Complete the form creating a login ID and password. You may want to assign the user a first and last name, but this is optional. When you are finished, click Post. You should see the JSON request and response.

Step 4: Authenticate the User

Next, you need to login as the user you created. Do this by clicking the Authentication button. You can now add the user you created in Step 4 and login.

Step 5: Add the New User to the Billing Account

To utilize much of Ribbit's functionality, users need to be set up for billing. To do this, login to your Ribbit developer account and select your application from MyApps. You will see a Configuration menu to the left of your account information. Click Users to return a list of users. From this list click Add to add the user to the billing account.

Step 6: Add a Purpose Number to the User

A purpose number is an inbound number and a Device resource type. We will create a purpose number so that we have a phone number where we can call and leave a voicemail. In Kermit, click Resource and select the Device resource from the drop down menu. Just as we created a User, we will now create a Device. In the ID box, enter @purpose/USA or @purpose/GBR (as appropriate for your country), give your device a name, and click commit. You'll see the response HTTP Status - 201 if it was successful. Below that, under the Result heading, you'll see ribbit:<phone_number>. The phone number is the purpose number you'll use in the next step.

Step 7: Add an Email Address to the User

Now that we have a phone number we can call and leave a voicemail, we need an email address where we can send notifications of new messages. We will again create a Device resource. This time, instead of creating a purpose number with the @purpose/USA or @purpose/GBR (as appropriate for your country) in Step 7, we will create a email destination with the "mailto:" directive. Add an email address in the ID box. An email should be sent to your account. You'll need to verify that email address.

Step 8: Try it Out

Click Resource, select Devices, and click GET. You'll see the email address you just created as well as the purpose number. There is also a default Device that was created when you created a User. Call the purpose number and leave a message. When you check your email, you should see a new message. That message has some information about the phone from which you just called, and (more importantly) an attached MP3 file of the call itself. You've just created your first application.

REST API Introduction - Request Formats

DRAFT

All requests must also supply the appropriate security and authentication headers according to the OAuth specification described below. In this release POST and PUT parameters should be submitted as JSON. All responses are similarly formatted as JSON objects. The base URI for all Ribbit RESTful requests is:

https://rest.ribbit.com/rest/1.0

The REST protocol operates primarily in terms of resources and operations and is defined using the following standard HTTP methods to retrieve and change server state.

Anatomy of a request

Method
Resource Type:
CollectionID : resource dependant
args:

GET

The GET method means retrieve whatever information is identified by the Request URI.

A GET request may be accompanied by additonal query parameters for filters, pagination, authentication, and response content format.

In the following example a GET request is made to retrieve a user's device collection. A 200 OK response is returned with a list of all devices configured for the user.

<< GET /rest/1.0/devices/9764e31d-65bf-4b2a-a3f1-8b0cdad6e8d6
>> 200 OK
   { entry : [
     {"id": "skype:foobar", "label":"skype", "carrier":"Skype" },
     {"id": "tel:16504568790", "label":"home phone", "carrier":"ATT", "ccfCheck":"passed"},
   ] }

PUT

The PUT method requests that the enclosed entity be stored under the supplied Request URI as a modified version.

In the following example a request is made using a PUT to change the URL used for event callbacks. A 200 OK response is returned, together with details of the newly modified resource.

<< PUT /apps/mydomain:myapp/          
   { "notificationUrl" : "http://myapp.com/"}

>> 200 OK
   {"id":"mydomain:myapp","domain":"mydomain","name":"myapp",
     "createdWith":"develperportal","createdBy":"9de95885-09c7-4551-9ce6-dcd5f66f20c8", ..
   }

POST

The POST method is used to create a new resource. In the following example a request is made using a POST to start a new call. Both the source and destination numbers are included in the request. A 201 CREATED response is returned once the call is successfully connected.

<< POST /rest/1.0/calls/abeb8b3-bedd-4afa-91c6-7054c3442038V131554051
   { "legs":["tel:14156789876","tel:14082578790","mode":talk","callerID":"14083450003]}

>> 201 CREATED
   LOCATION: http://myhost.com/rest/1.0/calls/abeb8b3-bedd-4afa-91c6-7054c3442038v131554051/1231111

DELETE

The DELETE method requests that the server delete the resource identified by the Request URI. In the example below a users phone number is being deleted. A 200 OK response is returned with the information about the deleted phone number.

<< DELETE /rest/1.0/devices/976e31d-6bf-4b2f-a3f1-8bcda6e8d6/tel:15108768904

>> 200 OK 
   REMOVED: /rest/1.0/devices/976e31d-6bf-4b2f-a3f1-8bcda6e8d6/tel:1510876890

REST API Introduction - Response Formats

The root element response is the root object returned (for example: in JSON, the response returned is the object value of the response node). Any malformed or otherwise incorrect request may result in an HTTP error code.

Responses to POST requests will be an HTTP 201 status code and a location header.
Responses to PUT requests will be either the JSON representation of the updated resource, as for a GET, or an HTTP 204.
Responses to DELETE requests will either be a 202 or a 204.
Responses to GET requests are always returned as an object containing an "entry" slot, which in turn contains a list of JSON objects.

For a collection of items:

{  "entry" : [
      {...first item...},
      {...second item...}
      ...
   ]
}

For a single item:

{  "entry" : 
   {...item...}
}

REST API Introduction - Pagination

Most resources support pagination to help navigate large collections. Note that even if pagination is not requested, certain SDKs will still return some of the paging values in responses provided for collection. For paginated collections the response will contain the following additional parameters based on OpenSearch:

startIndex — The index of the first result returned in this response, relative to the starting index of all results that would be returned if no startIndex had been requested. In general, this will be equal to the value requested by the startIndex, or 0 if no specific startIndex was requested.
itemsPerPage — The number of results returned per page in this response. In general, this will be equal to the count query parameter, but may be less if the service provider is unwilling to return as many results per page as requested, or if there are less than the requested number of results left to return when starting at the current startIndex. This field MUST be present if and only if a value for count is specified in the request.
totalResults — The total number of items that would be returned if there were no startIndex or count specified. This value tells the user how many total results to expect, regardless of the pagination in use, but taking into account the current filtering options in the request.
entry — An array of objects, one for each item matching the request. For parsing consistency, if the request could return multiple items this value MUST always be an array of results, even if there happens to be 0 or 1 matching results. If the result is specifically for a single item then the entry MUST be an object containing the single item returned. To get specific pages of a collection response, startIndex and count may be specified as part of the request query string.

<< GET /rest/1.0/calls/<guid>?startIndex=10&count=5

>> { "startIndex" : 10,
     "itemsPerPage" : 5, 
     "totalResults" : 100,
     "entry" : [
      {...first item...},
      {...second item...}
      ...
   ]
}

REST API Introduction - Filters

Some collections may be filtered to return only entries that match particular conditions. These conditions are specified using filters in the request URI. The following filters are supported, following OpenSearch conventions:


filterBy	<property>	The name of the property to filter against.
filterValue	<value>	The string to match against the <property> value.
filterOp	contains	Returns all entries where <property> contains <value>.
	startsWith	Returns all entries where <property> value begins with <value>.
	present	Returns all entries where <property> is defined (<value> is ignored).
	equals	Returns all entries where <property> is exactly <value>.

REST API Introduction - Event Notifications

The Ribbit Platform will generate many different kinds of events. These events may be received via HTTP POSTs to URLs that can be configured for each application in a domain. At present, events are generated for Message and Call resources. These events include but are not limited to:

New Call Received
Active Call Status Change (on hold, etc.)
Low/No Credit Warning
New Voicemail Message
New Voicemail Transcription
New SMS Message
Message Deleted

Each event will contain the following parameters encoded as a JSON string:

Name	Value	Notes
type	string	Type of event (CallInitiated, for example).
time	time	Time the event occurred.
resource	uri	The URI corresponding to this event.
params	object	Parameters associated with this resource that may have changed as a result of this event.

Example:

<< POST <notificationUrl>          
   Json={ "type":"cc_call_vmpickup","time":"2009-03-24T19:24:24Z", 
          "resource":"http://rest.ribbit.com/rest/1.0/calls/67be2a0c-6c65-102c-a24a-00188b741119/1234",
          "params":{ "callid":2608143,
                     "guid":"cce3cd2d-190c-454a-a4a5-42f2ea3e28ab",
                     "source":"sip:restQA031009-001@mailinator.com",  
                     "dest":"tel:16503355954"}
        } }
>> 200 OK

REST API Introduction - Response Codes

One of the nice things about REST is that it uses standard HTTP calls. Below is a list of response codes commonly used. For a more complete list, see those posted on Wikipedia and the W3C.

200 OK
The request was received without error.

201 CREATED
The request was received and a new item of the type requested should have been successfully created.This response is always given in response to a successfull POST request, and is typically accompanied by a LOCATION header specifying the URI of the newly created resource.

202 ACCEPTED
The request was received without error, but has not been acted upon yet.

204 NO CONTENT
The server has fulfilled the request. The response may include new or updated meta-information in the form of entity headers, which if present should be associated with the requested variant.

400 BAD REQUEST
Ribbit application servers MUST return 400 BAD REQUEST under any one or more of the following conditions:
   •   Invalid request URI
   •   Invalid HTTP header
   •   Receiving an unsupported, nonstandard parameter
   •   Receiving an invalid HTTP message body

401 UNAUTHORIZED
Ribbit container servers must return 401 UNAUTHORIZED when receiving a request for a protected resource and the request is either:
• Missing OAuth authorization credentials as described in OAuth Consumer Request 1.0
• OAuth authorization credentials are present, but the User identity is not authorized to access the protected resource. If the request already included authorization credentials, the 401 response indicates that the request has been refused. A 401 response must include a WWW-Authenticate header field indicating the request, and may present an OAuth Token for the container server's realm.

Example: WWW-Authenticate: OAuth realm="http://sp.example.com/"

403 FORBIDDEN
The server understood the request but is refusing to fulfill it. Authorization will not help. The current authorization context does not allow the request.  

404 NOT FOUND
The server has not found a resource (such as a feed or entry) that matches the request URI.  

405 METHOD NOT ALLOWED
The method specified in the request line is not allowed for the resource identified by the Request URI. The response must include an Allow header containing a list of valid methods for the requested resource.  

409 CONFLICT
The request could not be completed due to a conflict with the current state of the resource. This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request. The response body includes enough information for the user to recognize the source of the conflict.

Ideally, the response entity would include enough information for the user or user agent to fix the problem; however, that might not be possible and is not required. Conflicts are most likely to occur in response to a PUT request. For example, this code can be used for a "limit exceeded" error as well as conflicting updates. See the error message for more information.  

500 INTERNAL SERVER ERROR
This is the default code that is used for all unrecognized errors.

502 BAD GATEWAY
The server acting as a gateway or proxy received an invalid response.

503 SERVICE UNAVAILABLE
The server is unavailable due to maintenance or traffic overload.