API Documentation

API Documentation

Authentication and Security

GeoChat Rest API uses Basic Auth to authenticate users.

Some of the end points works for both authenticated and non-authenticated requests. If the client does not support pre authentication this may be an issue. In this case a ?auth=true could be added to the QueryString to force the basic authentication mechanism. (Since 1.7.1)

All requests can be made over SSL

Pagination

Api calls that support paging use a 1-based page index in the QueryString. The response will contain links to the next and previous page if available using atom links with relationship next and previous respectively.
If the page index is not specified in the QueryString, it will be defaulted to the first page.
Results are limited to 10 items per page.

For example the response of http://geochat.instedd.org/api/foo/bar?page=2 will be:

<?xml version="1.0"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
  <channel>
    <title>...</title>
    <description>...</description>
    <atom:link rel="previous" href="http://geochat.instedd.org/api/foo/bar?page=1" />
    <atom:link rel="next" href="http://geochat.instedd.org/api/foo/bar?page=3" />
    <!-- items -->
  </channel>
</rss>

End Points

	HTTP Method	URI	Since version
Get User Info	GET	/api/users/{login}	1.7
Create User	POST	/api/users/{login}/create	1.7
Update User Profile	POST	/api/users/{login}/update	1.7
List User Groups	GET	/api/users/{login}/groups	1.7
List User Requests	GET	/api/users/{login}/requests	1.8
List User Invites	GET	/api/users/{login}/invites	1.8
Verify User Credentials	GET	/api/users/{login}/verify	1.8
Get Group Info	GET	/api/groups/{alias}	1.7
Create Group	POST	/api/groups/{alias}/create	1.7
Update Group	POST	/api/groups/{alias}/update	1.7
List Groups	GET	/api/groups	1.7
List Group Members	GET	/api/groups/{alias}/members	1.7
Join Group	POST	/api/groups/{alias}/join	1.7
Leave Group	POST	/api/groups/{alias}/leave	1.7
Invite User to Group	POST	/api/groups/{alias}/invite	1.7
Get a Message	GET	/api/messages/{id}	1.7
Send Message	POST	/api/messages	1.7
Send Message to a Group	POST	/api/groups/{alias}/messages	1.7
Get Group Messages	GET	/api/groups/{alias}/messages	1.7
Get User Messages	GET	/api/users/{login}/messages	1.7
Get Public Messages	GET	/api/messages/public	1.7
Group Overall Stats	GET	/api/groups/{alias}/stats/overall	1.9
Group Message History Stats	GET	/api/groups/{alias}/stats/messagehistory	1.9
Group Message History Per Protocol Stats	GET	/api/groups/{alias}/stats/messagehistoryperprotocol	1.9
Group User Channels History Stats	GET	/api/groups/{alias}/stats/userchannelshistory	1.9
Group Pending Invitations Stats	GET	/api/groups/{alias}/stats/pendinginvitations	1.9
System Overall Stats	GET	/api/system/stats/overall	1.9
System Group History Stats	GET	/api/system/stats/grouphistory	1.9
System Message History Stats	GET	/api/system/stats/messagehistory	1.9
System Message History Per Protocol Stats	GET	/api/system/stats/messagehistoryperprotocol	1.9
System User Channels History Stats	GET	/api/system/stats/userchannelshistory	1.9
System Pending Invitations Stats	GET	/api/system/stats/pendinginvitations	1.9
System Users Per Group Count Stats	GET	/api/system/stats/userspergroupcount	1.9
System Users History Stats	GET	/api/system/stats/usershistory	1.9

Methods

User API

Groups API

Messaging API

Group Stats API

System Stats API

Output

API resources can be requested to be in either ATOM or RSS (some methods also allow KML and CSV).

You can specify the output format in the URI of the requested resource. The syntax for this is http://geochat.instedd.org/api/foo/bar.{format}, so for example http://geochat.instedd.org/api/users/johndoe.rss will return a representation of the requested user in RSS, and http://geochat.instedd.org/api/users/johndoe.atom wil return a representation in ATOM.

If no format is specified (e.g. http://geochat.instedd.org/api/users/johndoe) it will be defaulted to RSS.

You can see examples inside the documentation of each API method.

Error Codes

When an error occurs, a meaningful HTTP status code is returned.

404 Not Found: You are requesting a resource that doesn't exist.
403 Forbidden: You are not authorized to access the requested resource.
401 Unauthorized: Similar to 403 Forbidden, but specifically for use when authentication is possible but has failed or not yet been provided.
400 Bad Format: There is a missing parameter or a syntax error in the request.

Samples

PHP

PHP samples can be found in the folder 'Samples/RestApi/PHP' of the GeoChat source code (google code link).

In order to run the samples, you need a web server with PHP (samples were developed in PHP 5.3.0, but other versions may work) and 'php_curl' extension enabled. MagpieRSS is also required, but it's already included in the source code. The base URL for the API service can be configured in 'api.php', just edit the define named 'BASE_API_URL'.

There are three main samples:

Group sample (group_example.php): shows group info, group latest messages and lets the user send a message to the group.
My messages sample (mymessages_example.php): shows user messages.
Control panel sample (controlpanel_example.php): shows 'my groups' (user groups) and lets the user create a new group.

Note: user login doesn't validate credentials.