REST API - Introduction


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 used with any programming language, such as PHP, Javascript, Java and many more.

The Ribbit RESTful API currently defines eight core resource types Users, Devices, Media, Tokens, Calls, Messages, Applications and Domains and Events.
 

Resources 

Resources are an important concept in REST and are sources of specific information, which are referenced by a Uniform Resource Identifier (URI).  It is important to note that a resource is not a "storage object" but is a conceptual mapping to a set of entities.

REST uses the URI to identify a particular resource involved in an interaction between components. This URI can be used to request an instance of the resource. 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 (or added) by sending representations from the client to the server. Access to resources occurs through HTTPs uniform 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
For more information about these methods refer to Request Formats
 

Request Formats

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 on them and is defined using the following standard HTTP methods to retrieve and change server state.

 

GET
The GET method means retrieve whatever information is identified by the Request-URI. In the following example a request is made using a GET 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"},
{"id": "xmpp:foo@bar.com", "label":"gtalk", "carrier":"Google"},
{"id": "mailto:foo@bar.com", "label":"email", "mailCheck":"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.
<< PUT /apps/mydomain:myapp/          
{ "notificationUrl" : "http://myapp.com/"}

>> 200 OK
{"entry":[
{"id":"mydomain:myapp","domain":"mydomain","name":"myapp",
"createdWith":"develperportal","createdBy":"9de95885-09c7-4551-9ce6-dcd5f66f20c8",
"created":"2009-03-31T15:38:01Z","visible":false,"suspended":false,
"template":[ {"type":"mailto","required":true,"alias":"","verifier":"auto"},
{"type":"tel","required":true,"alias":"","verifier":"auto"}]
 
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
 

Response Formats

The structure of the response object returned from a successful request is as follows. The root element response is the root object returned (e.g. in JSON, the response returned is the object value of the response node).
 
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...}
}
 

Response Codes

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.
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, http://oauth.googlecode.com/svn/spec/ext/consumer_request/1.0/drafts/1/spec.html
  • 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 for those credentials. 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
Internal error. This is the default code that is used for all unrecognized errors.
 

Collection Pagination

Some resources support pagination to help navigate large collections. Resource pagination is available on both Call and Messages resources. 
 
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 Consumer how many total results to expect, regardless of the current pagination being used, but taking into account the current filtering options in the request.
  • entry — an array of objects, one for each item matching the request. For consistency of parsing, if the request could possibly 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...}
...
]
}
 

Security

Authentication and security for the Restfull API is provided by the OAuth protocol. Ribbit acts as an OAuth provider and all Ribbit Applications act as corresponding OAuth consumers. To reduce risk of phishing-based attacks, Users are never required to enter Ribbit credentials directly via an Application; instead they are directed to a page served by Ribbit from which an OAuth_token can be obtained for future use by the Application. All communication with Ribbit as an OAuth provider is via SSL, as OAuth does not provide for encryption of Tokens.

Ribbit bases its security decisions on the type of client in use. A generally available desktop client, for example, cannot effectively protect a Secret Key that is installed with each client. The security of communications with a partner service, on the other hand, is dependent on the effectiveness of that service's security procedures. Ribbit may wish to rate-limit requests from unknown clients or require registration to mitigate risk.

Ribbit scopes OAuth_tokens as narrowly as possible (e.g. allows reading but not writing if a client only performs reads).

Each RESTful operation has a request context which includes authentication and authorization information including the requestor ID (the User initiating the request) and application ID (the Application, or whatever is acting as the User's agent).

In order to obtain an OAuth token it is necessary the relevant OAuth headers includes the username and password of the requesting user to a login resource, which will return the OAuth token and token secret in the response headers. For code example of how to implement this please refer to the PHP libraries or the Kermit reference application in Javascript. More details on how OAuth works can be found on the OAuth website. 
 
For example:
<< POST /rest/1.0/login
oauth_consumer_key=<appKey>,
x_auth_username=<login>,
x_auth_password=<password>,
oauth_nonce="nonce",
oauth_signature_method="HMAC-SHA1",
oauth_timestamp=<timestamp>,
oauth_signature=<request signed with appSecret>

>> oauth_token=<token>&oauth_token_secret=<secret>  
 

Event Notifications

The Platform will generate many kinds of events which may be POSTed to Notification URLs which may be configured for each Application they create. At present events are generated for Message and Call resources, including but not limited to:
  • New Calls
  • Active Call Status Changes (moved, on hold etc..)
  • Low / No Credit Warnings
  • New Voicemail Messages
  • New Voicemail Transcriptions
  • New SMS Messages
  • Message Deleted
Each Event will contain the following parameters encoded as a JSON string:
 
Name ValueNotes
type
string
The type of event (e.g. CallInitiated).
time
time
The time the event occurred.
resource
uriThe URI corresponding to this event.
params
object
The parameters associated with this resource which have changed as a result of this event.
 
For 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
For more details please refer to  Event Notifications.