calendar-api

README

calendar-api

---

• calendar
  • events
  • tasks
• account
  • misc (logout, validate)
  • settings
• auth

---

calendar

All calendar endpoints require an X-CSRF-Token request header, an access token cookie and a refresh token cookie. All endpoints also set a new CSRF token cookie, access token cookie and, in the case of an expired access token, a new refresh token cookie.

events

GET /api/calendar/events/<amount>/<start>

Fetch <amount> calendar events with the offset <start>. Variables "amount" and "start" are optional. Fetches the first 10 events by default.

request header

X-CSRF-Token: <csrf-token>

success response header

Set-Cookie: access_token=<access_token>; HttpOnly; Secure
Set-Cookie: X-CSRF-Token=<csrf-token>; Secure

success response

Sample:

[
  {
    "id": 1,
    "name": "Walk dog",
    "description": "Walk the dog.",
    "starts_at": "2019-03-02T21:35:42Z",
    "ends_at": "2019-03-03T21:35:42Z",
    "task_id": 1 
  },
  {
    "id": 2,
    "name": "Eat food",
    "description": "Don't eat the dog",
    "starts_at": "2019-03-02T21:35:42Z",
    "ends_at": "2019-03-02T22:35:42Z",
    "task_id": 0  
  }
]

error response

{
    "error": <a string representing the error>
}

GET /api/calendar/events_interval/<from>/<to>

Fetch all calendar events between Unix time <from> and <to>.

request header

X-CSRF-Token: <csrf-token>

success response header

Set-Cookie: access_token=<access_token>; HttpOnly; Secure
Set-Cookie: X-CSRF-Token=<csrf-token>; Secure

success response

Sample:

[
  {
    "id": 1,
    "name": "Walk dog",
    "description": "Walk the dog.",
    "starts_at": "2019-03-02T21:35:42Z",
    "ends_at": "2019-03-03T21:35:42Z",
    "task_id": 1 
  },
  {
    "id": 2,
    "name": "Eat food",
    "description": "Don't eat the dog",
    "starts_at": "2019-03-02T21:35:42Z",
    "ends_at": "2019-03-02T22:35:42Z",
    "task_id": 0  
  }
]

error response

{
    "error": <a string representing the error>
}

GET /api/calendar/event/<id>

Fetch a calendar event by its id.

request header

X-CSRF-Token: <csrf-token>

success response header

Set-Cookie: access_token=<access_token>; HttpOnly; Secure
Set-Cookie: X-CSRF-Token=<csrf-token>; Secure

success response

Sample:

{
    "id": 1,
    "name": "Walk dog",
    "description": "Walk the dog.",
    "starts_at": "2019-03-02T21:35:42Z",
    "ends_at": "2019-03-03T21:35:42Z",
    "task_id": 1
}

error response

{
    "error": <a string representing the error>
}

POST /api/calendar/event/

Create a calendar event. Returns the created calendar event.

request header

X-CSRF-Token: <csrf-token>

success response header

Set-Cookie: access_token=<access_token>; HttpOnly; Secure
Set-Cookie: X-CSRF-Token=<csrf-token>; Secure

request

Properties "description" and "task_id" are optional.

Sample:

{
    "name": "Walk dog",
    "description": "Walk the dog.",
    "starts_at": "2019-03-02T21:35:42Z",
    "ends_at": "2019-03-03T21:35:42Z",
    "task_id": 1
}

success response

Sample:

{
    "id": 1
    "name": "Walk dog",
    "description": "Walk the dog.",
    "starts_at": "2019-03-02T21:35:42Z",
    "ends_at": "2019-03-03T21:35:42Z",
    "task_id": 1
}

error response

{
    "error": <a string representing the error>
}

PUT /api/calendar/event/<id>

Update a calendar event by its id. Returns the updated calendar event.

request header

X-CSRF-Token: <csrf-token>

success response header

Set-Cookie: access_token=<access_token>; HttpOnly; Secure
Set-Cookie: X-CSRF-Token=<csrf-token>; Secure

request

Sample:

{
    "name": "Updated event",
    "description": "Updated description.",
    "starts_at": "2019-03-02T21:35:42Z",
    "ends_at": "2019-03-03T21:35:42Z"
}

success response

Sample:

{
    "id": 1,
    "name": "Updated event",
    "description": "Updated description.",
    "starts_at": "2019-03-02T21:35:42Z",
    "ends_at": "2019-03-03T21:35:42Z",
    "task_id": 1
}

error response

{
    "error": <a string representing the error>
}

DELETE /api/calendar/event/<id>

Delete a calendar event by its id.

request header

X-CSRF-Token: <csrf-token>

success response header

Set-Cookie: access_token=<access_token>; HttpOnly; Secure
Set-Cookie: X-CSRF-Token=<csrf-token>; Secure

success response

{
    "result": "success"
}

error response

{
    "error": <a string representing the error>
}

tasks

GET /api/calendar/tasks/

Fetch all calendar tasks.

request header

X-CSRF-Token: <csrf-token>

success response header

Set-Cookie: access_token=<access_token>; HttpOnly; Secure
Set-Cookie: X-CSRF-Token=<csrf-token>; Secure

success response

Sample:

[
  {
    "id": 1,
    "name": "Walk dog",
    "description": "Walk the dog",
    "created_at": "2019-03-02T21:35:42Z",
    "deadline": "2019-03-07T21:35:42Z",
    "hours": 10
  },
  {
    "id": 2,
    "name": "Eat food",
    "description": "Don't eat the dog",
    "created_at": "2019-03-02T21:35:42Z",
    "deadline": "2019-03-06T21:35:42Z",
    "hours": 10
  }
]

error response

{
    "error": <a string representing the error>
}

GET /api/calendar/task/<id>

Fetch a calendar task by its id.

request header

X-CSRF-Token: <csrf-token>

success response header

Set-Cookie: access_token=<access_token>; HttpOnly; Secure
Set-Cookie: X-CSRF-Token=<csrf-token>; Secure

success response

Sample:

{
    "id": 1,
    "name": "Walk dog",
    "description": "Walk the dog",
    "created_at": "2019-03-02T21:35:42Z",
    "deadline": "2019-03-07T21:35:42Z",
    "hours": 10
}

error response

{
    "error": <a string representing the error>
}

POST /api/calendar/task/

Create a calendar task. Returns the created calendar task.

request header

X-CSRF-Token: <csrf-token>

success response header

Set-Cookie: access_token=<access_token>; HttpOnly; Secure
Set-Cookie: X-CSRF-Token=<csrf-token>; Secure

request

Property "description" is optional.

Sample:

{
    "name": "Walk dog",
    "description": "Walk the dog",
    "deadline": "2019-03-07T21:35:42Z",
    "hours": 10
}

success response

Sample:

{
    "id": 1,
    "name": "Walk dog",
    "description": "Walk the dog",
    "created_at": "2019-03-02T21:35:42Z",
    "deadline": "2019-03-07T21:35:42Z",
    "hours": 10
}

error response

{
    "error": <a string representing the error>
}

PUT /api/calendar/task/<id>

Update a calendar task by its id. Returns the updated calendar task.

request header

X-CSRF-Token: <csrf-token>

success response header

Set-Cookie: access_token=<access_token>; HttpOnly; Secure
Set-Cookie: X-CSRF-Token=<csrf-token>; Secure

request

Property "description" is optional.

Sample:

{
    "name": "Updated task",
    "description": "Updated description.",
    "deadline": "2019-03-07T21:35:42Z",
    "hours": 10
}

success response

Sample:

{
    "id": 1,
    "name": "Updated task",
    "description": "Updated description.",
    "starts_at": "2019-03-02T21:35:42Z",
    "ends_at": "2019-03-03T21:35:42Z"
}

error response

{
    "error": <a string representing the error>
}

DELETE /api/calendar/task/<id>

Delete a calendar task by its id.

request header

X-CSRF-Token: <csrf-token>

success response header

Set-Cookie: access_token=<access_token>; HttpOnly; Secure
Set-Cookie: X-CSRF-Token=<csrf-token>; Secure

success response

{
    "result": "success"
}

error response

{
    "error": <a string representing the error>
}

account

All account endpoints require an access token cookie, a refresh token cookie and a CSRF token in the X-CSRF-Token request header.

misc

DELETE /api/account/logout/

Logs the user out.

request header

X-CSRF-Token: <csrf-token>

success response header

Set-Cookie: access_token=""; HttpOnly; Secure
Set-Cookie: refresh_token=""; HttpOnly; Secure
Set-Cookie: X-CSRF-Token=""; Secure

success response

{
    "result": "successfully logged out"
}

error response

{
    "error": <a string representing the error>
}

GET /api/account/validate/

Simple endpoint to check if the user is logged in. Returns a new access token cookie and a new CSRF token.

request header

X-CSRF-Token: <csrf-token>

success response header

Set-Cookie: access_token=<access_token>; HttpOnly; Secure
Set-Cookie: X-CSRF-Token=<csrf-token>; Secure

success response

{
    "result": "user is logged in"
}

error response

{
    "error": <a string representing the error>
}

settings

GET /api/account/settings/

Returns all of the user's settings.

request header

X-CSRF-Token: <csrf-token>

success response header

Set-Cookie: access_token=""; HttpOnly; Secure
Set-Cookie: refresh_token=""; HttpOnly; Secure
Set-Cookie: X-CSRF-Token=""; Secure

success response

{
    "preferred_time": "morning",
    "preferred_length": "long"
}

error response

{
    "error": <a string representing the error>
}

GET /api/account/settings/<key>

Returns the setting value of the given <key>.

request header

X-CSRF-Token: <csrf-token>

success response header

Set-Cookie: access_token=""; HttpOnly; Secure
Set-Cookie: refresh_token=""; HttpOnly; Secure
Set-Cookie: X-CSRF-Token=""; Secure

success response

Sample:
GET /api/account/settings/preferred_time

{
    "preferred_time": "morning"
}

error response

{
    "error": <a string representing the error>
}

POST /api/account/settings/

Set all settings at once.

request header

X-CSRF-Token: <csrf-token>

success response header

Set-Cookie: access_token=""; HttpOnly; Secure
Set-Cookie: refresh_token=""; HttpOnly; Secure
Set-Cookie: X-CSRF-Token=""; Secure

request

{
    "preferred_time": "morning",
    "preferred_length": "long"
}

success response

{
    "result": "success"
}

error response

{
    "error": <a string representing the error>
}

PUT /api/account/setting/<key>

Update the value of setting <key>. Returns the updated setting.

request header

X-CSRF-Token: <csrf-token>

success response header

Set-Cookie: access_token=""; HttpOnly; Secure
Set-Cookie: refresh_token=""; HttpOnly; Secure
Set-Cookie: X-CSRF-Token=""; Secure

request

Sample:
PUT /api/account/setting/preferred_time

Note that the key always should be "setting".

{
    "setting": "afternoon"
}

success response

{
    "preferred_time": "afternoon"
}

error response

{
    "error": <a string representing the error>
}

auth

POST /auth/register/

Registers an account using the supplied email and password. Returns an access token, refresh token and X-CSRF-Token cookie.

request

{
    "email": "test@example.com",
    "password": "examplepassword"
}

success response header

Set-Cookie: access_token=<access_token>; HttpOnly; Secure
Set-Cookie: refresh_token=<refresh_token>; HttpOnly; Secure
Set-Cookie: X-CSRF-Token=<csrf-token>; Secure

success response

{
    "result": "registration successful"
}

error response

{
    "error": <a string representing the error>
}

POST /auth/login/

On success, returns an access token, a refresh token and an X-CSRF-Token cookie.

request

{
    "email": "test@example.com",
    "password": "examplepassword"
}

success response header

Set-Cookie: access_token=<access_token>; HttpOnly; Secure
Set-Cookie: refresh_token=<refresh_token>; HttpOnly; Secure
Set-Cookie: X-CSRF-Token=<csrf-token>; Secure

success response

{
    "result": "login successful"
}

error response

{
    "error": <a string representing the error>
}