tinynote API documentation

[GET] /api
{
  "data": {
    "name": "tinynote API RESTful",
    "description": "A simple markdown note taking application with encryption support built in PHP",
    "documentation": "https://ricardogj08.github.io/tinynote/",
    "repository": "https://notabug.org/ricardogj08/tinynote/",
    "license": "AGPL-3.0-or-later",
    "author": {
      "fullname": "Ricardo García Jiménez",
      "email": "ricardogj08@riseup.net",
      "homepage": "https://ricardogj08.github.io/blog/",
      "role": "Backend developer"
    }
  }
}

  •  »
  •  Authentication »
  •  Login

Login

Generates a JWT authentication token to the API.

[POST] /api/v1/auth/login

Request body

Field Type Required Range Description
nickname string true length: [4, 255] Username or email of the access user.
password string true length: [8, 64] Access user password.

Example

curl -X POST \
  --data-urlencode 'nickname=ricardogj08' \
  --data-urlencode 'password=12345678' \
  http://localhost:8080/api/v1/auth/login

curl -X POST \
  --data-urlencode 'nickname=ricardogj08@riseup.net' \
  --data-urlencode 'password=12345678' \
  http://localhost:8080/api/v1/auth/login

Response

{
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ0aW55bm90ZSIsInN1YiI6ImQ0Njc0YjkwLTVjZWItNDM0OS1iNGMzLWNlN2NkY2Q0ZmZjOCIsImF1ZCI6Imh0dHA6Ly9sb2NhbGhvc3Q6ODA4MC9pbmRleC5waHAvIiwiZXhwIjoxNzQxODI0MDAwLCJpYXQiOjE3NDE3NjczODJ9.fTB5G4Nr07-ngUuFjw2VSxhvnpUWjwAT50fiFM0-1bXSk8tlAgRYneWVYeQLgzmuFws6gYVC2QLNqGnM8O6v4cjd5Ybp1zf7cZ-0zWrrnBl0V00cFaLikMw70Zp3gp3kXJvEUlFyCF17onCWSw5f8bGXq42DTzNEu6YRcJmCwMTP05aM1KXT0FSScK-8TNdI8GzZ2jfZeDwSW_VL5VQzS8VMJTCgnkDH51SCn16deZZ2DT7hppxgZxOC2G4DU4MWl-n2LWbmlzoBBRyfsypE36KD1zW2VOvjurGnFW2SeOIgqS5hbNSs5jwAKtlqysspL6VGqoMxRXTqspeykrZOaQ"
  }
}

  •  »
  •  Authentication »
  •  Authenticated user

Authenticated user

Shows the authenticated user information.

[GET] /api/v1/auth/me

Example

curl -X GET \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --oauth2-bearer AUTH_TOKEN \
  http://localhost:8080/api/v1/auth/me

Response

{
  "data": {
    "id": "d4674b90-5ceb-4349-b4c3-ce7cdcd4ffc8",
    "username": "ricardogj08",
    "email": "ricardogj08@riseup.net",
    "active": 1,
    "is_admin": 0,
    "created_at": "2024-11-23 21:00:33",
    "updated_at": "2024-11-23 21:00:42"
  }
}

  •  »
  •  Notes »
  •  All notes

All notes

[GET] /api/v1/notes

Example

Response


  •  »
  •  Notes »
  •  Create a note

Create a note

Registers note information.

[POST] /api/v1/notes

Request body

Field Type Required Range Default Description
title string true length: [1, 255] Note's title.
body string true length: [1, pow(16, 2) - 1] Note's markdown content.
tags array[tags] false [] A list of tags ids for the note (see).

Example

curl -X POST \
  --oauth2-bearer AUTH_TOKEN \
  --data-urlencode 'title=PHP' \
  --data-urlencode 'body=# PHP is awesome!' \
  --data-urlencode 'tags%5B%5D=84eacd98-43e9-425b-8d36-382ef01715e6' \
  --data-urlencode 'tags%5B%5D=9a7ab1a2-5ad2-42dd-872a-dc49a3d3d213' \
  http://localhost:8080/api/v1/notes

Response

{
  "data": {
    "id": "c56928b9-e32f-4913-95bf-619faa506dc0",
    "user_id": "d4674b90-5ceb-4349-b4c3-ce7cdcd4ffc8",
    "title": "PHP",
    "created_at": "2025-03-12 22:39:49",
    "updated_at": "2025-03-12 22:39:49",
    "tags": [
      {
        "id": "84eacd98-43e9-425b-8d36-382ef01715e6",
        "name": "php"
      },
      {
        "id": "9a7ab1a2-5ad2-42dd-872a-dc49a3d3d213",
        "name": "servidores"
      }
    ]
  }
}

  •  »
  •  Notes »
  •  Show a note

Show a note

Gets note information.

[GET] /api/v1/notes/:id

Example

curl -X GET \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --oauth2-bearer AUTH_TOKEN \
  http://localhost:8080/api/v1/notes/:id

Response

{
  "data": {
    "id": "c56928b9-e32f-4913-95bf-619faa506dc0",
    "user_id": "d4674b90-5ceb-4349-b4c3-ce7cdcd4ffc8",
    "title": "PHP",
    "body": "# PHP is awesome!",
    "created_at": "2025-03-12 22:39:49",
    "updated_at": "2025-03-12 22:39:49",
    "tags": [
      {
        "id": "84eacd98-43e9-425b-8d36-382ef01715e6",
        "name": "php"
      },
      {
        "id": "9a7ab1a2-5ad2-42dd-872a-dc49a3d3d213",
        "name": "servidores"
      }
    ]
  }
}

  •  »
  •  Notes »
  •  Update a note

Update a note

Modify note information.

[PUT] /api/v1/notes/:id

Request body

Field Type Required Range Description
title string false length: [1, 255] New note's title.
body string false length: [1, pow(16, 2) - 1] New note's markdown content.
tags array[tags] false A list of news or deleteds tags ids for the note (see).

Example

curl -X PUT \
  --oauth2-bearer AUTH_TOKEN \
  --data-urlencode 'title=PHP 8.4' \
  --data-urlencode 'body=# PHP 8.4 is awesome!' \
  --data-urlencode 'tags=[]' \
  http://localhost:8080/api/v1/notes/:id

Response

{
  "data": {
    "id": "c56928b9-e32f-4913-95bf-619faa506dc0",
    "user_id": "d4674b90-5ceb-4349-b4c3-ce7cdcd4ffc8",
    "title": "PHP 8.4",
    "created_at": "2025-03-12 22:39:49",
    "updated_at": "2025-03-12 22:53:59",
    "tags": []
  }
}

  •  »
  •  Notes »
  •  Delete a note

Delete a note

Deletes note information.

[DELETE] /api/v1/notes/:id

Example

curl -X DELETE \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --oauth2-bearer AUTH_TOKEN \
  http://localhost:8080/api/v1/notes/:id

Response

{
  "data": {
    "id": "c56928b9-e32f-4913-95bf-619faa506dc0",
    "user_id": "d4674b90-5ceb-4349-b4c3-ce7cdcd4ffc8",
    "title": "PHP 8.4",
    "created_at": "2025-03-12 22:39:49",
    "updated_at": "2025-03-12 23:00:07",
    "tags": []
  }
}

  •  »
  •  Profile »
  •  Update profile

Update profile

Modify user profile information.

[PUT] /api/v1/profile

Request body

Field Type Required Range Description
email string false length: [4, 255] New user's email.
username string false length: [4, 32] New user's username.
password string false length: [8, 64] New user's password.
pass_confirm string false equals: password User's password confirmation.

Example

curl -X PUT \
  --oauth2-bearer AUTH_TOKEN \
  --data-urlencode 'name=ricardog08' \
  --data-urlencode 'username=ricardogj08' \
  --data-urlencode 'email=ricardogj08@riseup.net' \
  --data-urlencode 'password=12345678' \
  --data-urlencode 'pass_confirm=12345678' \
  http://localhost:8080/api/v1/profile

Response

{
  "data": {
    "id": "d4674b90-5ceb-4349-b4c3-ce7cdcd4ffc8",
    "username": "ricardogj08",
    "email": "ricardogj08@riseup.net",
    "active": 1,
    "is_admin": 0,
    "created_at": "2024-11-23 21:00:33",
    "updated_at": "2025-03-12 19:49:30"
  }
}

  •  »
  •  Tags »
  •  All tags

All tags

[GET] /api/v1/tags

Example

Response


  •  »
  •  Tags »
  •  Create a tag

Create a tag

Registers tag information.

[POST] /api/v1/tags

Request body

Field Type Required Range Description
name string true length: [1, 64] Tag's name.

Example

curl -X POST \
  --oauth2-bearer AUTH_TOKEN \
  --data-urlencode 'name=php' \
  http://localhost:8080/api/v1/tags

Response

{
  "data": {
    "id": "84eacd98-43e9-425b-8d36-382ef01715e6",
    "name": "php",
    "user_id": "d4674b90-5ceb-4349-b4c3-ce7cdcd4ffc8",
    "created_at": "2025-03-12 18:59:12",
    "updated_at": "2025-03-12 18:59:12"
  }
}

  •  »
  •  Tags »
  •  Show a tag

Show a tag

Gets tag information.

[GET] /api/v1/tags/:id

Example

curl -X GET \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --oauth2-bearer AUTH_TOKEN \
  http://localhost:8080/api/v1/tags/:id

Response

{
  "data": {
    "id": "84eacd98-43e9-425b-8d36-382ef01715e6",
    "user_id": "d4674b90-5ceb-4349-b4c3-ce7cdcd4ffc8",
    "name": "php",
    "number_notes": 0,
    "created_at": "2025-03-12 18:59:12",
    "updated_at": "2025-03-12 18:59:12"
  }
}

  •  »
  •  Tags »
  •  Update a tag

Update a tag

Modify tag information.

[PUT] /api/v1/tags/:id

Request body

Field Type Required Range Description
name string false length: [1, 64] New tag's name.

Example

curl -X PUT \
  --oauth2-bearer AUTH_TOKEN \
  --data-urlencode 'name=php8.4' \
  http://localhost:8080/api/v1/tags/:id

Response

{
  "data": {
    "id": "84eacd98-43e9-425b-8d36-382ef01715e6",
    "name": "php8.4",
    "user_id": "d4674b90-5ceb-4349-b4c3-ce7cdcd4ffc8",
    "number_notes": 0,
    "created_at": "2025-03-12 18:59:12",
    "updated_at": "2025-03-12 19:24:16"
  }
}

  •  »
  •  Tags »
  •  Delete a tag

Delete a tag

Deletes tag information.

[DELETE] /api/v1/tags/:id

Example

curl -X DELETE \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --oauth2-bearer AUTH_TOKEN \
  http://localhost:8080/api/v1/tags/:id

Response

{
  "data": {
    "id": "84eacd98-43e9-425b-8d36-382ef01715e6",
    "name": "php8.4",
    "user_id": "d4674b90-5ceb-4349-b4c3-ce7cdcd4ffc8",
    "number_notes": 0,
    "created_at": "2025-03-12 18:59:12",
    "updated_at": "2025-03-12 19:26:38"
  }
}

  •  »
  •  Users »
  •  All users

All users

[GET] /api/v1/users

Example

Response


  •  »
  •  Users »
  •  Create a user

Create a user

Registers user information.

[POST] /api/v1/users

Request body

Field Type Required Range Default Description
username string true length: [4, 32] User's username.
email string true length: [4, 255] User's email.
active boolean false contains: [on, off, yes, no, 1, 0] false If user is active.
is_admin boolean false contains: [on, off, yes, no, 1, 0] false If user is administrator.
password string true length: [8, 64] User's password.
pass_confirm string true equals: password User's password confirmation.

Example

curl -X POST \
  --oauth2-bearer AUTH_TOKEN \
  --data-urlencode 'username=ricardogj08' \
  --data-urlencode 'email=ricardogj08@riseup.net' \
  --data-urlencode 'active=false' \
  --data-urlencode 'is_admin=false' \
  --data-urlencode 'password=12345678' \
  --data-urlencode 'pass_confirm=12345678' \
  http://localhost:8080/api/v1/users

Response

{
  "data": {
    "id": "610b992b-4667-45ed-89d7-4c388edce35a",
    "username": "ricardogj08",
    "email": "ricardogj08@riseup.net",
    "active": 0,
    "is_admin": 0,
    "created_at": "2025-03-12 20:33:20",
    "updated_at": "2025-03-12 20:33:20"
  }
}

  •  »
  •  Users »
  •  Show a user

Show a user

Gets user information.

[GET] /api/v1/users/:id

Example

curl -X GET \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --oauth2-bearer AUTH_TOKEN \
  http://localhost:8080/api/v1/users/:id

Response

{
  "data": {
    "id": "610b992b-4667-45ed-89d7-4c388edce35a",
    "username": "ricardogj08",
    "email": "ricardogj08@riseup.net",
    "active": 0,
    "is_admin": 0,
    "number_notes": 0,
    "number_tags": 0,
    "created_at": "2025-03-12 20:33:20",
    "updated_at": "2025-03-12 20:33:20"
  }
}

  •  »
  •  Users »
  •  Update a user

Update a user

Modify user information.

[PUT] /api/v1/users/:id

Request body

Field Type Required Range Description
username string false length: [4, 32] New user's username.
email string false length: [4, 255] New user's email.
active boolean false contains: [on, off, yes, no, 1, 0] If user is active.
is_admin boolean false contains: [on, off, yes, no, 1, 0] If user is administrator.
password string false length: [8, 64] New user's password.
pass_confirm string false equals: password User's password confirmation.

Example

curl -X PUT \
  --oauth2-bearer AUTH_TOKEN \
  --data-urlencode 'username=ricardogj08' \
  --data-urlencode 'email=ricardogj08@riseup.net' \
  --data-urlencode 'active=true' \
  --data-urlencode 'is_admin=false' \
  --data-urlencode 'password=12345678' \
  --data-urlencode 'pass_confirm=12345678' \
  http://localhost:8080/api/v1/users/:id

Response

{
  "data": {
    "id": "610b992b-4667-45ed-89d7-4c388edce35a",
    "username": "ricardogj08",
    "email": "ricardogj08@riseup.net",
    "active": 1,
    "is_admin": 0,
    "created_at": "2025-03-12 20:33:20",
    "updated_at": "2025-03-12 20:50:40"
  }
}

  •  »
  •  Users »
  •  Delete a user

Delete a user

Deletes user information.

[DELETE] /api/v1/users/:id

Example

curl -X DELETE \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --oauth2-bearer AUTH_TOKEN \
  http://localhost:8080/api/v1/users/:id

Response

{
  "data": {
    "id": "610b992b-4667-45ed-89d7-4c388edce35a",
    "username": "ricardogj08",
    "email": "ricardogj08@riseup.net",
    "active": 1,
    "is_admin": 0,
    "number_notes": 0,
    "number_tags": 0,
    "created_at": "2025-03-12 20:33:20",
    "updated_at": "2025-03-12 20:57:51"
  }
}