Skip to content
This repository has been archived by the owner on Jan 15, 2024. It is now read-only.

Latest commit

 

History

History
398 lines (271 loc) · 8.08 KB

rest_api.md

File metadata and controls

398 lines (271 loc) · 8.08 KB
Raw

REST API

This document contains API specification for the web app.

Beside these endpoints, the web app must also implement Common Errors.

Login

POST: /api/session

This endpoint is used by client to log in the user. Upon successful call, this endpoint returns access_token that will be used to authenticate subsequent API calls.

Notice that access_token has very short lifetime. In this system the lifetime duration is set to 20 seconds. So after 20 seconds the access_token will be expired.

When the current access_token is already expired, client must call Refresh Access Token to generate the new access_token using refresh_token from the response.

Currently only 2 users available in the system:

  • email: alice@mail.com, password: 123456
  • email: bob@mail.com, password: 123456

Note:

Since refresh_token will be used every time the client want to generate new access_token, it should be stored in client storage indefinitely.

Body:

  • email, String => The email for login into the system.
  • password, String => The password for given username.

Example Request:

POST /session
Content-Type: application/json

{
    "email": "alice@mail.com",
    "password": "123456"
}

Success Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "ok": true,
    "data": {
        "user": {
            "id": 1,
            "email": "alice@mail.com",
            "name": "Alice"
        },
        "access_token": "933e89b1-980b-4c98-8d73-18f7ccfac25d",
        "refresh_token": "8eebef3c-03e0-4ead-b78e-27bac3fc43c3"
    }
}

Error Responses:

  • Invalid Credentials (401)

    HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "ok": false,
    "err": "ERR_INVALID_CREDS",
    "msg": "incorrect username or password"
}

    Client will receive this error when it submitted incorrect combination of username & password.

Back to Top

Refresh Access Token

PUT: /api/session

This endpoint is used by client to replace expired access_token with the new one.

Header:

  • Authorization, String => The value is Bearer <refresh_token>.

Example Request:

PUT /session
Authorization: Bearer 8eebef3c-03e0-4ead-b78e-27bac3fc43c

Success Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "ok": true,
    "data": {
        "access_token": "933e89b1-980b-4c98-8d73-18f7ccfac25d"
    }
}

Error Responses:

  • Invalid Refresh Token (401)

    HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "ok": false,
    "err": "ERR_INVALID_REFRESH_TOKEN",
    "msg": "invalid refresh token"
}

    Client will receive this error when it submitted invalid refresh token. There are 2 causes of invalid refresh token: either the value is incorrect or the value is deemed expired by the system. In case client receiving this error, the client should redirect user to the login page.

Back to Top

List Reminders

GET: /api/reminders?limit={limit}

This endpoint returns the upcoming reminders for the user. The reminders are sorted by remind_at in ascending order.

Header:

  • Authorization, String => The value is Bearer <access_token>.

Query Parameters:

  • limit, Integer, OPTIONAL => The maximum number of reminders to be returned. The default value is 10.

Example Request:

GET /reminders?limit=5
Authorization: Bearer 933e89b1-980b-4c98-8d73-18f7ccfac25d

Success Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "ok": true,
    "data": {
        "reminders": [
            {
                "id": 1,
                "title": "Meeting with Bob",
                "description": "Discuss about new project related to new system",
                "remind_at": "1701246722",
                "event_at": "1701223200"
            }
        ],
        "limit": 5
    }
}

Error Responses:

No specific error responses.

Back to Top

Create Reminder

POST: /api/reminders

This endpoint is used by client to create a new reminder. When the reminder is successfully created, the system will send email notification to the user when the reminder is due (when reminder_at is reached).

Header:

  • Authorization, String => The value is Bearer <access_token>.

Request Body:

  • title, String => Title of the reminder.
  • description, String => Description of the reminder.
  • remind_at, Integer => Unix timestamp in seconds when the reminder should be reminded to the user.
  • event_at, Integer => Unix timestamp in seconds when the event will occurs.

Example Request:

POST /api/reminders
Authorization: Bearer 933e89b1-980b-4c98-8d73-18f7ccfac25d

{
    "title": "Meeting with Bob",
    "description": "Discuss about new project related to new system",
    "remind_at": 1701246722,
    "event_at": 1701223200
}

Success Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "ok": true,
    "data": {
        "id": 1,
        "title": "Meeting with Bob",
        "description": "Discuss about new project related to new system",
        "remind_at": "1701246722",
        "event_at": "1701223200"
    }
}

Error Responses:

No specific error responses.

Back to Top

View Reminder

GET: /api/reminders/{id}

This endpoint is used by client to view details of a reminder.

Header:

  • Authorization, String => The value is Bearer <access_token>.

Path Parameters:

  • id, Integer => Id of the reminder.

Example Request:

GET: /api/reminders/1
Authorization: Bearer 933e89b1-980b-4c98-8d73-18f7ccfac25d

Success Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "ok": true,
    "data": {
        "id": 1,
        "title": "Meeting with Bob",
        "description": "Discuss about new project related to new system",
        "remind_at": "1701246722",
        "event_at": "1701223200"
    }
}

Error Responses:

No specific error responses.

Back to Top

Edit Reminder

PUT: /api/reminders/{id}

This endpoint is used by client to edit a reminder.

Header:

  • Authorization, String => The value is Bearer <access_token>.

Path Parameters:

  • id, Integer => Id of the reminder.

Request Body:

  • title, String, OPTIONAL => Title of the reminder.
  • description, String, OPTIONAL => Description of the reminder.
  • remind_at, Integer, OPTIONAL => Unix timestamp in seconds when the reminder should be reminded to the user.
  • event_at, Integer, OPTIONAL => Unix timestamp in seconds when the event will occurs.

Example Request:

PUT /api/reminders/1
Authorization: Bearer 933e89b1-980b-4c98-8d73-18f7ccfac25d

{
    "title": "Meeting with Bob",
    "description": "Discuss about new project related to new system",
    "remind_at": 1701246722,
    "event_at": 1701223200
}

Success Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "ok": true,
    "data": {
        "id": 1,
        "title": "Meeting with Bob",
        "description": "Discuss about new project related to new system",
        "remind_at": "1701246722",
        "event_at": "1701223200"
    }
}

Error Responses:

No specific error responses.

Back to Top

Delete Reminder

DELETE: /api/reminders/{id}

This endpoint is used by client to delete a reminder.

Header:

  • Authorization, String => The value is Bearer <access_token>.

Path Parameters:

  • id, Integer => Id of the reminder.

Example Request:

DELETE: /api/reminders/1

Success Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "ok": true
}

Error Responses:

No specific error responses.

Back to Top