API Documentation

Post

API endpoints related to post.

Post (list)

GET http://<kono-api server>/api/v1/post

Retrieve a list of posts, providing the filters and pagination.

Query Parameters

Name	Type	Description
filter_type	string	Type of posts to retrieve. Only "notice" or "lostfound" values are allowed.
start_index	number	The response contains the latest posts, starting from the start_index-th one. Default value is 0 if not provided. Should be larger or equal than 0.
max_size	number	Maximum number of posts to retrieve. Should be larger than 0 and lesser or equal than 64.

200 Successfully retrieved the list of posts. The posts are sorted by descending created_time timestamp. (The latest ones comes first)

[
    {
        "sid": <number, sid of the post, NOT NULL>,
        "type": "notice" | "lostfound",
        "title_kr": <string, korean title of the post>,
        "title_en": <string, english title of the post>,
        "created_time": <timestamp of the created time, NOT NULL>,
        "thumbnail": <post에 이미지가 딸려 있다면 첫 번째 이미지의 URL, 없으면 null>
    }
]

400 The request query is invalid, or required parameter is not provided.

500 Internal server error occurred.

Post (single)

GET http://<kono-api server>/api/v1/post/:sid

Retrieve a single post with detailed information.

Path Parameters

Name	Type	Description
sid	number	sid of the post to retrieve.

200 Successfully retrieved a post.

{
    "sid": <number, sid, NOT NULL>,
    "type": "notice" | "lostfound",
    "title_kr": <string, korean title of the post>,
    "title_en": <string, english title of the post>,
    "created_time": <timestamp, time of creation, NOT NULL>,
    "content_kr": <string, URL containing the korean content>,
    "content_en": <string, URL containing the english content>,
    "content_img": [
        <string, URL of the image attached to this post>
    ]
}

400 The requested sid is invalid. (in case of negative sid)

404 The post of requested sid does not exist or is deleted.

500 Internal server error occurred.

Post (count)

GET http://<kono-api server>/api/v1/post/count

Retrieve the number of posts of each type, notice or lostfound.

200 Successfully retrieved the result.

{
    "notice": <number of notice posts>
    "lostfound": <number of lostfound posts>
}

500 Internal server error occurred.

Image

API endpoints related to image.

Image (list)

GET http://<kono-api server>/api/v1/image

Retrieve the list of images attached to existing posts, providing the filters and pagination.

Query Parameters

Name	Type	Description
filter_type	string	Type of posts to retrieve. Only notice and lostfound values are allowed.
start_index	number	The response contains images from the latest posts, starting from the start_index-th image. Should be larger or equal than 0.
max_size	number	Maximum number of images to retrieve. Should be larger than 0 and lesser or equal than 64.

200 Successfully retrieved the list of images. The images are sorted by the created_time timestamp of the post, by descending order.

[
    {
        "sid": <number, sid of the image, NOT NULL>,
        "url": <string, url of the image, NOT NULL>,
        "post_sid": <string, sid of the post, NOT NULL>
    }
]

400 The request query is invalid, or required parameter is not provided.

500 Internal server error occurred.

Image (count)

GET http://<kono-api server>/api/v1/image/count

Retrieve the number of images attached to posts of each type, notice or lostfound.

200 Successfully retrieved the result.

{
    "notice": <number of images attached to notice posts.>
    "lostfound": <number of images attached to lostfound posts.>
}

500 Internal server error occurred.

Room

API endpoints related to room states.

Create

POST http://<kono-api server>/api/v1/room

Add a (room_number, state) record. Authorization via GET /api/v1/auth/login (with valid access_token cookie) is required.

Query Parameters

Name	Type	Description
room_number	number	Room number of the room to add record. Should be an integer larger or equal than 1.
state	number	0 for empty, 1 for using

201 Successfully added a record.

400 Invalid query parameter was given.

403 The client machine is not logged in.

500 Internal server error occurred.

Recent (single)

GET http://<kono-api server>/api/v1/room/recent/:room_number

Retrieve the most recent record of the specific room.

Path Parameters

Name	Type	Description
room_number	number	The index of the room to retrieve state. Should be an integer larger or equal than 1.

200 Successfully retrieved the result.

{
    "state": 0 | 1    // 0 for empty, 1 for using
    "timestamp": <timestamp of the record, NOT NULL>
}

400 Invalid room_number was given. (0 or negative)

404 The record for given room number does not exist.

500 An internal server error occurred.

Recent (list)

GET http://<kono-api server>/api/v1/room/recent

Retrieve the most recent records of all existing rooms.

200 Successfully retrieved the result. The records are sorted by room number, increasing. An empty array cannot be the response. (In this case, the server will response by 404 Not Found)

[
    {
        "room_number": <integer (at least 1), NOT NULL>,
        "state": 0 | 1,  // 0 for empty, 1 for using
        "timestamp": <timestamp of the record, NOT NULL>
    }
]

404 There were no records.

500 An internal server error occurred.

Auth

Login

POST http://<kono-api server>/api/v1/auth/login

Administrator login.

Request Body

Name	Type	Description
password	string	Should match the password predefined or previously set by the user.

200 Logged in successfully. The response contains Set-cookie header which sets access_token cookie with newly signed JWT. (expires in 1 hour)

{
    "msg": "login success"
}

400 Missing password field in the request body.

403 Wrong password.

500 An internal server error occurred.

Logout

POST http://<kono-api server>/api/v1/auth/logout

Logout from the server. Should be already logged in.

204 Successfully logged out. The access_token cookie is removed from the requesting browser.

403 The requesting browser does not contain valid access_token cookie.

500 An internal server error occurred.

Check

GET http://<kono-api server>/api/v1/auth/check

Check if this user is logged in.

204 The requesting browser contains valid access_token cookie.

403 The requesting browser does not contain valid access_token cookie.

500 An internal server error occurred.

Change password

PUT http://<kono-api server>/api/v1/auth/password

Update the user's own password.

Request Body

Name	Type	Description
password	string	New password. Should be a string no longer than 20 characters.

204 Successfully updated the password.

400 The password field of the request body does not exist or is invalid.

403 The requesting browser does not contain valid access_token cookie.

500 An internal server error occurred.

Noti

Retrieve

GET http://<kono-api server>/api/v1/noti

Retrieve the list of active notifications.

Query Parameters

Name	Type	Description
max_size	number	Maximum number of notifications to retrieve. Should be larger than 0 and less or equal than 64.

200 Successfully retrieved the result.

[
    {
        "sid": <sid of the noti, NOT NULL>,
        "noti_kr": <noti content in korean>,
        "noti_en": <noti content in english>,
        "created_time": <time of creation, NOT NULL>
    }
]

400 Invalid query parameter max_size.

500 Internal server error occurred.

Create

POST http://<kono-api server>/api/v1/noti

Create a notification. The user should be logged in.

Request Body

Name	Type	Description
noti_kr	string	Notification content (in korean). Should be no longer than 40 characters.
noti_en	string	Notification content (in english). Should be no longer than 80 characters.

201 Successfully created a notification.

{
    "sid": <sid of the created notification>,
    "noti_kr": <noti content in korean>,
    "noti_en": <noti content in english>,
    "created_time": <time of creation>
}

400 Invalid parameter was given.

403 The user is not logged in.

500 Internal server error occurred.

Update

PUT http://<kono-api server>/api/v1/noti/:sid

Update a notification of given sid. The user should be logged in.

Path Parameters

Name	Type	Description
sid	number	sid of the notification to update.

Request Body

Name	Type	Description
noti_kr	string	Noti content in korean to update. Should be no longer than 40 characters.
noti_en	string	Noti content in english to update. Should be no longer than 80 characters.

200 Successfully updated the notification.

{
    "sid": <sid of the updated notification>,
    "noti_kr": <updated korean content>,
    "noti_en": <updated english content>,
    "created_time": <time of creation (unchanged by update)>
}

400 Invalid parameter was given.

403 The user is not logged in.

404 There are no notification with given sid.

500 Internal server error occurred.

Delete

DELETE http://<kono-api server>/api/v1/noti/:sid

Delete a notification with given sid. The user should be logged in.

Path Parameters

Name	Type	Description
sid	number	sid of a notification to delete.

204 Successfully deleted the notification.

400 Invalid parameter was given.

403 The user is not logged in.

404 There are no notification with given sid.

500 Internal server error occurred.