We currently offer a basic API. In time we want to open up our application more. Currently, the API permits people to change their status message in their personal website. In the future we will add many more calls using different access modes and output formats.
General
The Realmee API’s are REST based (http://en.wikipedia.org/wiki/Representational_State_Transfer).
This means that the API’s are easiy accesible using standard web based communication mechanisms.
API Key
Some API calls need to be authorized because they can change data in a users’ account. This authorization is done using a combination of the username and API key where the API key acts as a password. The API key is generated as part of a persons personal website. A user can find his/her API key in the edit mode of the personal website in the 'advanced' section.
Authentication
The mechanism used for user verification is basic authentication. This method is described here:(http://en.wikipedia.org/wiki/Basic_authentication_scheme ).
Basic authentication will be deployed over a secure connection (HTTPS) so a username and API key cannot be intercepted. Basic authentication needs to be included in every call that is made to the API.
API calls are restricted to one call per minute per IP address.
API calls
Update status
The status is a Twitter-like message showing the What, Where and When of a particular user. The API call ‘status/update’ will change
the current status and with a new status and will move to current status to a history list.
Method
The call to the API method should have the path:
https://www.realmee.com/api/rest/xml/profile/status/update.aspx?what=&where=&when=
Parameters
• what: The text of the new status message. This is a required field
• where: The text of the location for the status. This is a required field
• when: The date for the status. This is optional. If omited a timestamp will be generated
for you
Remarks
You can enter your own timestamp. Be aware that items that are added later, but that have an earlier timestamp will not show up.
Plain HTTP calls to this path will fail with a 401 error.
Output
You can change the output of a method by varying parts of the URL. The part to specify is the part right after /rest/. Options are:
- xml: this will output XML
- Json: this will output to json format
- text: this will output text format
The XML output of this method is:
200
ok
In case of an error display the common HTTP with its description.
Authentication failure
401
Unauthorised
The text output of this method:
200 ok
Or in case of an error the common HTTP errorcode is displayed with its description.
For example:
500 Internal server error
|