KeyMeeting REST API v1

API Documentation For KeyMeeting

Quickstart

The KeyMeeting API is a RESTful Web Service.

It accepts requests using standard HTTP methods, such as GET, PUT, POST and DELETE. Currently, “Basic HTTP Authentication” is the only available method of authenticating. We are working to additionally provide “Digest HTTP Authentication”.

Examples given here are provided for the PHP programming language and uses cURL to make the HTTP requests.

Important points:

• According to the HTTP specification, when making GET requests, all parameters must be passed as URL/querystring parameters.
• When making PUT, POST or DELETE requests, all parameters must be passed in the request body; URL/querystring parameters in such requests will be ignored, except for the format variable.
• The data format of the request body must either:
  a. contain name/value pairs such as id=1&var2=val2 or,
  
  b. contain an input_type and rest_data variable, the former must be set to “json” and the latter must be a valid JSON array, such as
  input_type=json&rest_data={"id":"1","var2":"val2"}
  Most developers will find the JSON approach more robust as it allows the passing of objects and arrays whilst also being simpler to implement (simply json_encode() your data array before sending it). We provide PHP code examples for how requests are made with each API method below.
  We are working to allow for additional input_type (such as XML), but for the time being you must always set this to “json”.
  There is more choice available for return formats - take a look at the section called “Return Formatting” below.
• All special characters (+, $, <, >, ect) in rest_data array should be urlencoded. You can use urlencode PHP function, or similar.

How to use HTTP Basic Auth while developing and debugging

To access the KeyMeeting API methods you must pass the Authorization header as part of each request, set it to basic and pass the required encrypted string. For example:

Authorization: Basic bWF0dGhpYXM6YWWtaW4=

The encrypted string must be a base64 encoded combination of username and password in the following format:

myUsername:myPassword

In Fiddler you can create this string by opening the Encoder tab, selecting base64 and entering your credentials.

Note when using non-latin usernames: you can use a normal browser to test GET methods. You will be asked to provide username/password in a popup, which is passed to the server as HTTP Basic Auth. Note that not all browsers support non-latin characters during this authentication. Chrome works, Firefox and others do not support it. This is only an issue when testing with a browser. cURL has no such issues.

Essential Tools:

Fiddler2 - HTTP Web Debugger. Allows you to send GET, PUT, POST, DELETE and other HTTP requests, modify headers and request body, and capture the return values. Essential for testing and debugging your API integration.

Essential Reading:

“RESTful Web Services” by Leonard Richardson & Sam Ruby (O’Reilly) - some formulations in this document have been borrowed from this excellent book, in particular for the section on HTTP Error Codes.

General Definitions

[ver] - The version of the API endpoint, must be defined in each request URL. The current version is 2.
Example: GET http://domain.com/api/2/[username]/authverify

[username] - The username of the account which is making the API requests.
Example: GET http://domain.com/api/[ver]/johndoe/authverify

HTTP Error Codes

400 “Bad Request”

Returned when providing input during a PUT operation which would leave the resource in an incomplete or inconsistent state. The provided input is nonsensical or corrupt.

Example: Providing an alphabetic value of “abcd” for an integer parameter, such as “offset”.

401 “Unauthorized”

Returned when trying to operate on a protected resource without providing the proper authentication credentials (either wrong or none at all). The response header WWW-Authenticate describes what kind of authentication the server will accept.

404 “Not Found”

Returned when trying to access a URI that does not correspond to any existing resource. The only possible exception is when a client is trying to PUT a new resource to that URI, see 201.

Example: Trying to retrieve a non-existing user.

405 “Method Not Allowed”

Returned when the client tries to use an HTTP method which this particular resource doesn’t support.

Example: Trying to PUT or DELETE a read-only resource.

409 “Conflict”

Returned when providing input during a PUT operation which would cause the resource state to conflict with some other resource.

Example: Trying to change your username to a name that’s already taken. Trying to delete a folder that is not empty.

410 “Gone”

Returned when the server knows there used to be a resource there, but there isn’t anymore. Also see 404, when the server has no idea about the resource at all.

500 “Internal Server Error”

There is a problem on the server side.

HTTP Success Codes

200 “OK”

Returned when a GET operation is successful, a POST operation to append to an existing resource is successful, and when a DELETE operation is successful.

201 “Created”

When a successful PUT or POST (when creating new) operation is carried out a 201 is returned, along with the new URI in the Location header. See 400 and 409 for related error codes.

301 “Moved Permanently”

Sometimes a PUT operation will change the URI of the resource just modified. In such cases, a 301 is returned, along with the new URI in the Location header. Future requests to the old URI will result in a 301, 404 or 410 return.

Return Formatting

The KeyMeeting API supports a number of different return formats.

By appending /format/[value]/ to the URLs of the API method calls, or by passing the correct MIME-type, you can choose the format of the returned data. These may differ for each call, so, for example you may wish to obtain a list of users in XML format, but get a list of invitees returned in JSON.

Available formats and how to request them: