Platform
REST API Docs
Using the PHP SDKs
Tutorials
Help
Archived Documents
Last Updated (Friday, 07 August 2009 10:38)
REST API - IntroductionThe Ribbit RESTful API currently defines eight core resource types Users, Devices, Media, Tokens, Calls, Messages, Applications and Domains and Events.
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
Request Formats
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 /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
<< 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 /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 /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
{ "entry" : [
{...first item...},
{...second item...}
...
]
}
{ "entry" :
{...item...}
} Response Codes
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.
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.
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
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/"
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.- 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.
<< GET /rest/1.0/calls/<guid>?startIndex=10&count=5
>> { "startIndex" : 10,
"itemsPerPage" : 5,
"totalResults" : 100,
"entry" : [
{...first item...},
{...second item...}
...
]
}
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).
<< 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
| Name | Value | Notes |
| type | string | The type of event (e.g. CallInitiated). |
| time | time | The time the event occurred. |
| resource | uri | The URI corresponding to this event. |
| params | object | The parameters associated with this resource which have changed as a result of this event. |
<< 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
