def texts_get(text_no):
"""Get a text.
Note: The body will only be included in the response if the content type is text.
.. rubric:: Request
::
GET /texts/19680717 HTTP/1.0
.. rubric:: Responses
Text exists::
HTTP/1.0 200 OK
{
"body": "r\u00e4ksm\u00f6rg\u00e5s",
"recipient_list": [
{
"conf_name": "Oskars Testperson",
"type": "to",
"loc_no": 29,
"conf_no": 14506
}
],
"author": {
"pers_no": 14506,
"pers_name": "Oskars Testperson"
},
"creation_time": "2012-05-08 18:36:17",
"comment_in_list": [],
"content_type": "text/x-kom-basic",
"text_no": 19680717,
"comment_to_list": [],
"subject": "jaha"
}
Text does not exist::
HTTP/1.0 404 NOT FOUND
{ TODO: error stuff }
.. rubric:: Example
::
curl -b cookies.txt -c cookies.txt -v \\
-X GET -H "Content-Type: application/json" \\
http://localhost:5001/texts/19680717
"""
try:
return jsonify(to_dict(g.ksession.get_text(text_no), True, g.ksession))
except kom.NoSuchText as ex:
return error_response(404, kom_error=ex)
def texts_get(text_no):
"""Get a text.
Note: The body will only be included in the response if the content type is text.
.. rubric:: Request
::
GET /texts/19680717 HTTP/1.0
.. rubric:: Responses
Text exists::
HTTP/1.0 200 OK
{
"body": "r\u00e4ksm\u00f6rg\u00e5s",
"recipient_list": [
{
"conf_name": "Oskars Testperson",
"type": "to",
"loc_no": 29,
"conf_no": 14506
}
],
"author": {
"pers_no": 14506,
"pers_name": "Oskars Testperson"
},
"creation_time": "2012-05-08 18:36:17",
"comment_in_list": [],
"content_type": "text/x-kom-basic",
"text_no": 19680717,
"comment_to_list": [],
"subject": "jaha"
}
Text does not exist::
HTTP/1.0 404 NOT FOUND
{ TODO: error stuff }
.. rubric:: Example
::
curl -b cookies.txt -c cookies.txt -v \\
-X GET -H "Content-Type: application/json" \\
http://localhost:5001/texts/19680717
"""
try:
return jsonify(to_dict(g.ksession.get_text(text_no), True, g.ksession))
except kom.NoSuchText as ex:
return error_response(404, kom_error=ex)
def sessions_get(session_id):
"""Get information about a session. Usable for checking if your
session is still valid.
.. rubric:: Request
::
GET /sessions/033556ee-3e52-423f-9c9a-d85aed7688a1 HTTP/1.1
.. rubric:: Responses
Session exists (i.e. logged in)::
HTTP/1.1 200 OK
{ "id": "033556ee-3e52-423f-9c9a-d85aed7688a1",
"person": { "pers_no": 14506, "pers_name": "Oskars testperson" },
"client": { "name": "jskom", "version": "0.2" } }
Session does not exist (i.e. not logged in)::
HTTP/1.1 404 Not Found
.. rubric:: Example
::
curl -b cookies.txt -c cookies.txt -v \\
-X GET http://localhost:5001/sessions/abc123
"""
session_id = _get_session_id()
ksession = _get_komsession(session_id)
if ksession:
return jsonify(to_dict(ksession, True, ksession))
else:
return empty_response(404)
def sessions_get(session_id):
"""Get information about a session. Usable for checking if your
session is still valid.
.. rubric:: Request
::
GET /sessions/033556ee-3e52-423f-9c9a-d85aed7688a1 HTTP/1.1
.. rubric:: Responses
Session exists (i.e. logged in)::
HTTP/1.1 200 OK
{ "id": "033556ee-3e52-423f-9c9a-d85aed7688a1",
"person": { "pers_no": 14506, "pers_name": "Oskars testperson" },
"client": { "name": "jskom", "version": "0.2" } }
Session does not exist (i.e. not logged in)::
HTTP/1.1 404 Not Found
.. rubric:: Example
::
curl -b cookies.txt -c cookies.txt -v \\
-X GET http://localhost:5001/sessions/abc123
"""
session_id = _get_session_id()
ksession = _get_komsession(session_id)
if ksession:
return jsonify(to_dict(ksession, True, ksession))
else:
return empty_response(404)
def conferences_list_unread():
"""Get list of unread conferences with information about how many
unread texts each conference has.
.. rubric:: Request
::
GET /conferences/unread/ HTTP/1.1
.. rubric:: Response
::
HTTP/1.1 200 OK
{
"confs": [
{
"no_of_unread": 265,
"name": "Oskars Testperson",
"conf_no": 14506
}
]
}
.. rubric:: Example
::
curl -b cookies.txt -c cookies.txt -v \\
-X GET http://localhost:5001/conferences/unread/
"""
return jsonify(
confs=to_dict(g.ksession.get_unread_conferences(), False, g.ksession))
def conferences_list_unread():
"""Get list of unread conferences with information about how many
unread texts each conference has.
.. rubric:: Request
::
GET /conferences/unread/ HTTP/1.1
.. rubric:: Response
::
HTTP/1.1 200 OK
{
"confs": [
{
"no_of_unread": 265,
"name": "Oskars Testperson",
"conf_no": 14506
}
]
}
.. rubric:: Example
::
curl -b cookies.txt -c cookies.txt -v \\
-X GET http://localhost:5001/conferences/unread/
"""
return jsonify(confs=to_dict(g.ksession.get_unread_conferences(),
False, g.ksession))
def conferences_get(conf_no):
"""Get information about a specific conference.
======= ======= =================================================================
Key Type Values
======= ======= =================================================================
micro boolean :true: (Default) Return micro conference information (`UConference <http://www.lysator.liu.se/lyskom/protocol/11.1/protocol-a.html#Conferences>`_) which causes less load on the server.
:false: Return full conference information.
======= ======= =================================================================
.. rubric:: Request
::
GET /conferences/14506 HTTP/1.1
.. rubric:: Responses
With micro=true::
HTTP/1.0 200 OK
{
"highest_local_no": 1996,
"nice": 77,
"type": {
"forbid_secret": 0,
"allow_anonymous": 1,
"rd_prot": 1,
"secret": 0,
"letterbox": 1,
"original": 0,
"reserved3": 0,
"reserved2": 0
},
"name": "Oskars Testperson",
"conf_no": 14506
}
With micro=false::
HTTP/1.0 200 OK
{
"super_conf": {
"conf_name": "",
"conf_no": 0
},
"creator": {
"pers_no": 14506,
"pers_name": "Oskars Testperson"
},
"no_of_texts": 1977,
"no_of_members": 1,
"creation_time": "2012-04-28 19:49:11",
"permitted_submitters": {
"conf_name": "",
"conf_no": 0
},
"conf_no": 14506,
"last_written": "2012-07-31 00:00:11",
"keep_commented": 77,
"name": "Oskars Testperson",
"type": {
"forbid_secret": 0,
"allow_anonymous": 1,
"rd_prot": 1,
"secret": 0,
"letterbox": 1,
"original": 0,
"reserved3": 0,
"reserved2": 0
},
"first_local_no": 20,
"expire": 0,
"msg_of_day": 0,
"supervisor": {
"conf_name": "Oskars Testperson",
"conf_no": 14506
},
"presentation": 0,
"nice": 77
}
Conference does not exist::
HTTP/1.0 404 NOT FOUND
{ TODO: error stuff }
.. rubric:: Example
::
curl -b cookies.txt -c cookies.txt -v \\
-X GET http://localhost:5001/conferences/14506?micro=true
"""
try:
micro = get_bool_arg_with_default(request.args, 'micro', True)
return jsonify(
to_dict(g.ksession.get_conference(conf_no, micro), True,
g.ksession))
except kom.UndefinedConference as ex:
return error_response(404, kom_error=ex)
def conferences_list():
"""Get list of conferences.
Query parameters:
======= ======= =================================================================
Key Type Values
======= ======= =================================================================
unread boolean :true: Return conferences with unread texts in.
:false: (Default) *Not implemented.*
micro boolean :true: (Default) Return micro conference information (`UConference <http://www.lysator.liu.se/lyskom/protocol/11.1/protocol-a.html#Conferences>`_) which causes less load on the server.
:false: Return full conference information.
======= ======= =================================================================
.. rubric:: Request
::
GET /conferences/?unread=true HTTP/1.0
.. rubric:: Responses
With micro=true::
HTTP/1.0 200 OK
{
"confs": [
{
"highest_local_no": 1996,
"nice": 77,
"type": {
"forbid_secret": 0,
"allow_anonymous": 1,
"rd_prot": 1,
"secret": 0,
"letterbox": 1,
"original": 0,
"reserved3": 0,
"reserved2": 0
},
"name": "Oskars Testperson",
"conf_no": 14506
}
]
}
With micro=false::
HTTP/1.0 200 OK
{
"confs": [
{
"super_conf": {
"conf_name": "",
"conf_no": 0
},
"creator": {
"pers_no": 14506,
"pers_name": "Oskars Testperson"
},
"no_of_texts": 1977,
"no_of_members": 1,
"creation_time": "2012-04-28 19:49:11",
"permitted_submitters": {
"conf_name": "",
"conf_no": 0
},
"conf_no": 14506,
"last_written": "2012-07-31 00:00:11",
"keep_commented": 77,
"name": "Oskars Testperson",
"type": {
"forbid_secret": 0,
"allow_anonymous": 1,
"rd_prot": 1,
"secret": 0,
"letterbox": 1,
"original": 0,
"reserved3": 0,
"reserved2": 0
},
"first_local_no": 20,
"expire": 0,
"msg_of_day": 0,
"supervisor": {
"conf_name": "Oskars Testperson",
"conf_no": 14506
},
"presentation": 0,
"nice": 77
}
]
}
.. rubric:: Example
::
curl -b cookies.txt -c cookies.txt -v \\
-X GET -H "Content-Type: application/json" \\
http://localhost:5001/conferences/?unread=trueµ=false
"""
micro = get_bool_arg_with_default(request.args, 'micro', True)
unread = get_bool_arg_with_default(request.args, 'unread', False)
if unread:
return jsonify(confs=to_dict(g.ksession.get_conferences(unread, micro),
True, g.ksession))
else:
abort(400) # nothing else is implemented
def sessions_create():
"""Create a new session (i.e. login).
Note: If the login is successful, the matched full name will be
returned in the response.
If no client is specified in the request, "httpkom" will be used.
.. rubric:: Request
::
POST /sessions/ HTTP/1.1
{
"person": { "pers_no": 14506 },
"password": "******",
"client": { "name": "jskom", "version": "0.2" }
}
.. rubric:: Responses
Successful login::
HTTP/1.0 200 OK
Set-Cookie: session_id=033556ee-3e52-423f-9c9a-d85aed7688a1; expires=Sat, 19-May-2012 12:44:51 GMT; Max-Age=604800; Path=/
{ "id": "033556ee-3e52-423f-9c9a-d85aed7688a1",
"person": { "pers_no": 14506, "pers_name": "Oskars testperson" },
"client": { "name": "jskom", "version": "0.2" } }
Failed login::
HTTP/1.1 401 Unauthorized
{ TODO: error stuff }
.. rubric:: Example
::
curl -b cookies.txt -c cookies.txt -v \\
-X POST -H "Content-Type: application/json" \\
-d '{ "pers_no": 14506, "password": "******" }' \\
http://localhost:5001/sessions/
"""
old_ksession = _get_komsession(_get_session_id())
if old_ksession:
# already loggedin, logout first, then try to login with the
# supplied credentials.
_logout(old_ksession)
try:
person = request.json['person']
except KeyError as ex:
return error_response(400, error_msg='Missing "person".')
try:
pers_no = person['pers_no']
except KeyError as ex:
return error_response(400, error_msg='Missing "pers_no" in "person".')
try:
password = request.json['password']
except KeyError as ex:
return error_response(400, error_msg='Missing "password".')
try:
if 'client' in request.json and request.json['client'] is not None:
ksession = _login(pers_no, password,
request.json['client']['name'],
request.json['client']['version'])
else:
ksession = _login(pers_no, password)
response = jsonify(to_dict(ksession, True, ksession))
response.set_cookie('session_id',
domain=app.config['HTTPKOM_COOKIE_DOMAIN'],
value=ksession.id,
max_age=7 * 24 * 60 * 60)
return response
except (kom.InvalidPassword, kom.UndefinedPerson, kom.LoginDisallowed,
kom.ConferenceZero) as ex:
return error_response(401, kom_error=ex)
def sessions_create():
"""Create a new session (i.e. login).
Note: If the login is successful, the matched full name will be
returned in the response.
If no client is specified in the request, "httpkom" will be used.
.. rubric:: Request
::
POST /sessions/ HTTP/1.1
{
"person": { "pers_no": 14506 },
"password": "******",
"client": { "name": "jskom", "version": "0.2" }
}
.. rubric:: Responses
Successful login::
HTTP/1.0 200 OK
Set-Cookie: session_id=033556ee-3e52-423f-9c9a-d85aed7688a1; expires=Sat, 19-May-2012 12:44:51 GMT; Max-Age=604800; Path=/
{ "id": "033556ee-3e52-423f-9c9a-d85aed7688a1",
"person": { "pers_no": 14506, "pers_name": "Oskars testperson" },
"client": { "name": "jskom", "version": "0.2" } }
Failed login::
HTTP/1.1 401 Unauthorized
{ TODO: error stuff }
.. rubric:: Example
::
curl -b cookies.txt -c cookies.txt -v \\
-X POST -H "Content-Type: application/json" \\
-d '{ "pers_no": 14506, "password": "******" }' \\
http://localhost:5001/sessions/
"""
old_ksession = _get_komsession(_get_session_id())
if old_ksession:
# already loggedin, logout first, then try to login with the
# supplied credentials.
_logout(old_ksession)
try:
person = request.json['person']
except KeyError as ex:
return error_response(400, error_msg='Missing "person".')
try:
pers_no = person['pers_no']
except KeyError as ex:
return error_response(400, error_msg='Missing "pers_no" in "person".')
try:
password = request.json['password']
except KeyError as ex:
return error_response(400, error_msg='Missing "password".')
try:
if 'client' in request.json and request.json['client'] is not None:
ksession = _login(pers_no, password,
request.json['client']['name'], request.json['client']['version'])
else:
ksession = _login(pers_no, password)
response = jsonify(to_dict(ksession, True, ksession))
response.set_cookie('session_id', domain=app.config['HTTPKOM_COOKIE_DOMAIN'],
value=ksession.id, max_age=7*24*60*60)
return response
except (kom.InvalidPassword, kom.UndefinedPerson, kom.LoginDisallowed,
kom.ConferenceZero) as ex:
return error_response(401, kom_error=ex)
def conferences_get(conf_no):
"""Get information about a specific conference.
======= ======= =================================================================
Key Type Values
======= ======= =================================================================
micro boolean :true: (Default) Return micro conference information (`UConference <http://www.lysator.liu.se/lyskom/protocol/11.1/protocol-a.html#Conferences>`_) which causes less load on the server.
:false: Return full conference information.
======= ======= =================================================================
.. rubric:: Request
::
GET /conferences/14506 HTTP/1.1
.. rubric:: Responses
With micro=true::
HTTP/1.0 200 OK
{
"highest_local_no": 1996,
"nice": 77,
"type": {
"forbid_secret": 0,
"allow_anonymous": 1,
"rd_prot": 1,
"secret": 0,
"letterbox": 1,
"original": 0,
"reserved3": 0,
"reserved2": 0
},
"name": "Oskars Testperson",
"conf_no": 14506
}
With micro=false::
HTTP/1.0 200 OK
{
"super_conf": {
"conf_name": "",
"conf_no": 0
},
"creator": {
"pers_no": 14506,
"pers_name": "Oskars Testperson"
},
"no_of_texts": 1977,
"no_of_members": 1,
"creation_time": "2012-04-28 19:49:11",
"permitted_submitters": {
"conf_name": "",
"conf_no": 0
},
"conf_no": 14506,
"last_written": "2012-07-31 00:00:11",
"keep_commented": 77,
"name": "Oskars Testperson",
"type": {
"forbid_secret": 0,
"allow_anonymous": 1,
"rd_prot": 1,
"secret": 0,
"letterbox": 1,
"original": 0,
"reserved3": 0,
"reserved2": 0
},
"first_local_no": 20,
"expire": 0,
"msg_of_day": 0,
"supervisor": {
"conf_name": "Oskars Testperson",
"conf_no": 14506
},
"presentation": 0,
"nice": 77
}
Conference does not exist::
HTTP/1.0 404 NOT FOUND
{ TODO: error stuff }
.. rubric:: Example
::
curl -b cookies.txt -c cookies.txt -v \\
-X GET http://localhost:5001/conferences/14506?micro=true
"""
try:
micro = get_bool_arg_with_default(request.args, 'micro', True)
return jsonify(to_dict(g.ksession.get_conference(conf_no, micro),
True, g.ksession))
except kom.UndefinedConference as ex:
return error_response(404, kom_error=ex)
def conferences_list():
"""Get list of conferences.
Query parameters:
======= ======= =================================================================
Key Type Values
======= ======= =================================================================
unread boolean :true: Return conferences with unread texts in.
:false: (Default) *Not implemented.*
micro boolean :true: (Default) Return micro conference information (`UConference <http://www.lysator.liu.se/lyskom/protocol/11.1/protocol-a.html#Conferences>`_) which causes less load on the server.
:false: Return full conference information.
======= ======= =================================================================
.. rubric:: Request
::
GET /conferences/?unread=true HTTP/1.0
.. rubric:: Responses
With micro=true::
HTTP/1.0 200 OK
{
"confs": [
{
"highest_local_no": 1996,
"nice": 77,
"type": {
"forbid_secret": 0,
"allow_anonymous": 1,
"rd_prot": 1,
"secret": 0,
"letterbox": 1,
"original": 0,
"reserved3": 0,
"reserved2": 0
},
"name": "Oskars Testperson",
"conf_no": 14506
}
]
}
With micro=false::
HTTP/1.0 200 OK
{
"confs": [
{
"super_conf": {
"conf_name": "",
"conf_no": 0
},
"creator": {
"pers_no": 14506,
"pers_name": "Oskars Testperson"
},
"no_of_texts": 1977,
"no_of_members": 1,
"creation_time": "2012-04-28 19:49:11",
"permitted_submitters": {
"conf_name": "",
"conf_no": 0
},
"conf_no": 14506,
"last_written": "2012-07-31 00:00:11",
"keep_commented": 77,
"name": "Oskars Testperson",
"type": {
"forbid_secret": 0,
"allow_anonymous": 1,
"rd_prot": 1,
"secret": 0,
"letterbox": 1,
"original": 0,
"reserved3": 0,
"reserved2": 0
},
"first_local_no": 20,
"expire": 0,
"msg_of_day": 0,
"supervisor": {
"conf_name": "Oskars Testperson",
"conf_no": 14506
},
"presentation": 0,
"nice": 77
}
]
}
.. rubric:: Example
::
curl -b cookies.txt -c cookies.txt -v \\
-X GET -H "Content-Type: application/json" \\
http://localhost:5001/conferences/?unread=trueµ=false
"""
micro = get_bool_arg_with_default(request.args, 'micro', True)
unread = get_bool_arg_with_default(request.args, 'unread', False)
if unread:
return jsonify(confs=to_dict(g.ksession.get_conferences(unread, micro),
True, g.ksession))
else:
abort(400) # nothing else is implemented
