Sessions

httpkom.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/current/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 , 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 , 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 . The / 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 / prefixes).

sessions_who_am_i() async

Get information about the current session.

Returns the session number and, if logged in, the current person.

Request:

GET /<server_id>/sessions/current/who-am-i HTTP/1.1
Httpkom-Connection: <id>

Response:

Logged in:

HTTP/1.1 200 OK

{
  "session_no": 12345,
  "person": {
    "pers_no": 14506,
    "pers_name": "Oskars Testperson"
  }
}

Not logged in:

HTTP/1.1 200 OK

{
  "session_no": 12345,
  "person": null
}

Example:

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

sessions_current_active() async

Tell the LysKOM server that the current user is active.

Request:

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

Response:

HTTP/1.1 204 No Content

Example:

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

sessions_create() async

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 (bug 608735) in combination with certain javascript libraries (AngularJS).

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

sessions_login() async

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"
}

Or

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

{
  "pers_name": "Oskars",
  "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"

sessions_logout() async

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"

sessions_delete(session_no) async

Delete a session (disconnect from the LysKOM server).

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."

Parameters:

Name	Type	Description	Default
session_no	int	Session number.	required

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/12345"

sessions_change_working_conference() async

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"