Example API Usage

The REST API uses JSON as the underlying data serialization mechanism, because JSON is a quick, easy-to-read and fast technology. Parsers and encoders are available for virtually all programming languages and of course it’s the native way to express objects in Javascript, which is the major target of in-browser applications.

The following example includes basic code in Python to show a fully function API session. The code can be literally re-used if Python is the language of choice, or just be taken as a further explanation of how to use the API. For Python, we include the HTTP and JSON libraries:

import httplib
import json

The API follows a session model, which means that for all transactions, you must first create a session with the cospace platform as a context for the following API requests. All session requests must be directed to http://api.cospace.de or https://api.cospace.de, which serves as a “load-balancing” name for individual API servers within the platform.

The GET /api/session call returns the session ID (sid) and the responsible server for this session. Further requests within this session must be addressed to this server only, because only this server has knowledge about the session data. This mechanism ensures a load-distribution between multiple API serving nodes in the cospace system. The sid and server information will also be sent by the server in form of HTTP cookies. Further requests within the session rely on re-transmitting sid to the server via the Authorization: Bearer <sid> header, via sid cookie, or it may be given as a sid URL parameter.

# get session information on api.cospace.de

initialConnection = httplib.HTTPSConnection("api.cospace.de")
initialConnection.request("GET", "/api/session")

# result is JSON encoded

response = json.loads(initialConnection.getresponse().read())

# print response

print "get session response: " + str(response)

# cut https:// prefix (7 characters) from server returned in JSON

apiServer = response["server"][8:]

# remember the session id

sid = response["sid"]

# create the connection for the following API requests

apiConnection = httplib.HTTPSConnection(apiServer)

Just created, the session is not authenticated, which means it is not associated with a system user account. Let’s assume that you already create a user with cospace (using the web interface on http://cospace.de), so we can now authenticate the session with this user using the POST /api/session. Note that this call is directed to the server returned by the GET /api/session call and carries the Authorization header:

# post credentials into session

body = json.dumps({
    "username": "johndoe47",
    "password": "secret12345"
})

headers = {"Authorization": "Bearer " + sid}

apiConnection.request("POST", "/api/session", body, headers=headers)

response = json.loads(apiConnection.getresponse().read())

print "login response: " + str(response)

Now, the session is authenticated and the session ID grants access to the user whose credentials we just logged in with. We might use the following GET /api/user API call to find out more about the user johndoe47 associated with our example session:

apiConnection.request("GET", "/api/user", headers=headers)

response = json.loads(apiConnection.getresponse().read())

print "get user details: " + str(response)

# remember the John's "tag_all" to access his objects later

tagAll = response["user"]["tag_all"]

The GET /api/user call we just made lists the user’s “system tags”, which serve as the fundamental point of managing the user’s objects. Given the UUID of John’s tag_all tag (the tag that references all of his objects), we might get a list of all his data objects with the GET /api/tag/(uuid)/object call:

apiConnection.request("GET", "/api/tag/" + tagAll + "/object", headers=headers)

response = json.loads(apiConnection.getresponse().read())

print "user's objects: " + str(response)

Before we finish the example, one last note about a special API call, GET /api/event. In contrast to all the other API calls, which focus to return as fast as possible after issuing the HTTP request, GET /api/event will “hang” until the requested event (i.e., any event with an id equal or higher to the id that was requested within the call) arrives. The event is then delivered instantly by returning the API call. In this way, push-style notifications are accomplished through client-initiated, blocking requests.

The time until the call returns can be tuned with the timeout parameter. After timeout, the call will return empty, if no event was seen.

apiConnection.request("GET", "/api/event?timeout=10&sid=" + sid)

# this might take up to 10 seconds

response = json.loads(apiConnection.getresponse().read())

print "event response: " + str(response)

After a session is no longer used, consider it a good habit to free the server-side resources of the session by deleting it:

apiConnection.request("DELETE", "/api/session", headers=headers)

response = json.loads(apiConnection.getresponse().read())

print "session delete status: " + str(response["status"])