Sessions

The httpkom connection id is the unique identifier that a httpkom client uses to identify which LysKOM connection that it owns. Since httpkom can be configured to allow connections to several different LysKOM servers, the connection id refers to a specific session on a specific LysKOM server.

The session number is what the LysKOM server uses to identify an open connection.

There is a 1-to-1 relation between httpkom connection ids and LysKOM session numbers. The important difference between the session number and the connection id, is that the session number is not secret. Httpkom uses a separate connection identifier, the httpkom connection id (a random UUID), to make it close to impossible to intentionally take over another httpkom client’s LysKOM connection.

The httpkom connection id is specified as a HTTP header:

Httpkom-Connection: <uuid>

To open a new connection, make a request like this:

POST /<server_id>/sessions/
Content-Type: application/json

{ "client": { "name": "jskom", "version": "0.6" } }

The response will look like this:

HTTP/1.0 201 Created
Content-Type: application/json
Httpkom-Connection: <uuid>

{ "session_no": 123456 }

This is the only response that will contain the Httpkom-Connection. The request must not contain any Httpkom-Connnection header. If the request contains a Httpkom-Connection header, the request will fail and the response will be:

HTTP/1.0 409 Conflict

Subsequent request to that server should contain the returned Httpkom-Connection header. For example, a login request will look like this:

POST /<server_id>/sessions/login
Content-Type: application/json
Httpkom-Connection: <uuid>

{ "pers_no": 14506, "passwd": "test123" }

and the response:

HTTP/1.0 201 Created
Content-Type: application/json

{ "pers_no": 14506, "pers_name": "Oskars Testperson" }

If a resource requires a logged in session and the request contains a valid Httpkom-Connection header which is not logged in, the response will be:

HTTP/1.0 401 Unauthorized

If the Httpkom-Connection is missing, or if the connection id specified by the Httpkom-Connection header is invalid (for example if the connection was to another server than <server_id>, or if there is no connection with that id), the response will be:

HTTP/1.0 403 Forbidden

When you get a 403 response, the used Httpkom-Connection should be considered invalid and should not be used again. If the Httpkom-Connection specifies a working connection, but to another server than <server_id>, httpkom might close the connection before returning 403.

It is up to the client to keep track of opened connection and to use them with the correct <server_id>. The /<server_id> prefix to all resources could be seen as redundant, since the Httpkom-Connection also specifies the server, but it makes the API resources consistent. Also, the resources on different LysKOM servers has nothing to do with each other, so it is a good idea from “REST” perspective to have them different resources (i.e. different /<server_id> prefixes).

httpkom.sessions.requires_login(f)

View function decorator. Check if the request points out a logged in LysKOM session. If the session is not logged in, return status code 401.

httpkom.sessions.requires_session(f)

View function decorator. Check if the request has a Httpkom-Connection header that points out a valid LysKOM session. If the header is missing, or if there is no session for the id, return an empty response with status code 403.

httpkom.sessions.sessions_change_working_conference()

Change current working conference of the current session.

Request

POST /<server_id>/sessions/current/working-conference HTTP/1.1
Httpkom-Connection: <id>

{
  "conf_no": 14506,
}

Responses

HTTP/1.1 204 No Content

Example

curl -v -H "Httpkom-Connection: 033556ee-3e52-423f-9c9a-d85aed7688a1" \
     -X POST -H "Content-Type: application/json" \
     -d '{ "conf_no": 14506 }' \
     "http://localhost:5001/lyskom/sessions/current/working-conference"

httpkom.sessions.sessions_create()

Create a new session (a connection to the LysKOM server).

Note: The response body also contains the connection_id (in addition to the response header) to around problems with buggy CORS implementations[1] in combination with certain javascript libraries (AngularJS).

[1] https://bugzilla.mozilla.org/show_bug.cgi?id=608735

Request

POST /<server_id>/sessions/ HTTP/1.1

{
  "client": { "name": "jskom", "version": "0.2" }
}

Responses

Successful connect:

HTTP/1.0 201 Created
Httpkom-Connection: 033556ee-3e52-423f-9c9a-d85aed7688a1

{
  "session_no": 12345,
  "connection_id": "033556ee-3e52-423f-9c9a-d85aed7688a1"
}

If the request contains a Httpkom-Connection header:

HTTP/1.0 409 CONFLICT

httpkom.sessions.sessions_current_active()

Tell the LysKOM server that the current user is active.

POST /<server_id>/sessions/current/active HTTP/1.1

httpkom.sessions.sessions_delete(session_no)

Delete a session (disconnect from the LysKOM server).

Parameters

session_no (int) – Session number

If the request disconnects the current session, the used Httpkom-Connection id is no longer valid.

Note (from the protocol A spec): “Session number zero is always interpreted as the session making the call, so the easiest way to disconnect the current session is to disconnect session zero.”

Request

DELETE /<server_id>/sessions/12345 HTTP/1.1
Httpkom-Connection: <id>

Responses

Success:

HTTP/1.1 204 No Content

Session does not exist:

HTTP/1.1 404 Not Found

Example

curl -v -H "Httpkom-Connection: 033556ee-3e52-423f-9c9a-d85aed7688a1" \
     -X DELETE "http://localhost:5001/lyskom/sessions/abc123"

httpkom.sessions.sessions_login()

Log in using the current session.

Note: If the login is successful, the matched full name will be returned in the response.

Request

POST /<server_id>/sessions/current/login HTTP/1.1
Httpkom-Connection: <id>

{
  "pers_no": 14506,
  "passwd": "test123"
}

Responses

Successful login:

HTTP/1.0 201 Created

{
  "pers_no": 14506,
  "pers_name": "Oskars testperson"
}

Failed login:

HTTP/1.1 401 Unauthorized

Example

curl -v -X POST -H "Content-Type: application/json" \
     -H "Httpkom-Connection: 033556ee-3e52-423f-9c9a-d85aed7688a1" \
     -d '{ "pers_no": 14506, "passwd": "test123" }' \
      "http://localhost:5001/lyskom/sessions/current/login"

httpkom.sessions.sessions_logout()

Log out in the current session.

Request

POST /<server_id>/sessions/current/logout HTTP/1.1
Httpkom-Connection: <id>

Responses

Successful logout:

HTTP/1.0 204 NO CONTENT

Example

curl -v -H "Httpkom-Connection: 033556ee-3e52-423f-9c9a-d85aed7688a1" \
     -X POST "http://localhost:5001/lyskom/sessions/current/logout"

httpkom.sessions.sessions_who_am_i()

TODO

httpkom.sessions.with_connection_id(f)

View function decorator. Get the connection id from the request and assign it to ‘g.connection_id’.