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"])