Notelist

Tag based note taking REST API

Version {{ version }}

1. Authentication

1.1. Login

Endpoint:	/auth/login
Method:	POST
Description:	Get a fresh access token and a refresh token

Request data:

Field	Type	Required
username	String	Yes
password	String	Yes

Response data:

Field	Type
message	String
message_type	String
result	Object: - user_id: String - access_token: String, - refresh_token: String

Request example:

curl -X 'POST' '{{ host_url }}auth/login' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"username": "example_username", "password": "example_password"}'

1.2. Refresh

Endpoint:	/auth/refresh
Method:	GET
Request header:	Authorization: Bearer <refresh_token>
Description:	Get a new, not fresh, access token

Response data:

Field	Type
message	String
message_type	String
result	Object: - access_token: String

Request example:

curl -X 'GET' '{{ host_url }}auth/refresh' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <refresh_token>'

1.3. Logout

Endpoint:	/auth/logout
Method:	GET
Request header:	Authorization: Bearer <access_token>
Description:	Revoke an access token

Response data:

Field	Type
message	String
message_type	String

Request example:

curl -X 'GET' '{{ host_url }}auth/logout' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>'

2. Users

2.1. Get Users

Endpoint:	/users/users
Method:	GET
Request header:	Authorization: Bearer <access_token>
Description:	Get the list of users
Permission required:	Administrator

Response data:

Field	Type
message	String
message_type	String
result	List of objects: - id: String - username: String - admin: Boolean - enabled: Boolean - name: String, null - email: String, null

Request example:

curl -X 'GET' '{{ host_url }}users/users' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>'

2.2. Get User

Endpoint:	/users/user/<user_id>
Method:	GET
Request header:	Authorization: Bearer <access_token>
Description:	Get a user
Permission required:	Administrator if the user to get is other than the user that makes the request

Response data:

Field	Type
message	String
message_type	String
result	Object: - id: String - username: String - admin: Boolean - enabled: Boolean - name: String, null - email: String, null

Request example:

curl -X 'GET' '{{ host_url }}users/user/<user_id>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>'

2.3. Create User

Endpoint:	/users/user
Methods:	POST, PUT
Request header:	Authorization: Bearer <access_token>
Description:	Create a user
Permission required:	Administrator

Request data:

Field	Type	Required	Default value
username	String	Yes
password	String	Yes
admin	Boolean	No	false
enabled	Boolean	No	false
name	String, null	No	null
email	String, null	No	null

Response data:

Field	Type
message	String
message_type	String
result	Object: - user_id: String

Request example:

curl -X 'POST' '{{ host_url }}users/user' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>' \
-d '{"username": "example_username", "password": "example_password", "admin": false, "enabled": true}'

2.4. Update User

Endpoint:	/users/user/<user_id>
Method:	PUT
Request header:	Authorization: Bearer <access_token>
Description:	Update some or all fields of a user
Permission required:	Administrator if the user to update is other than the user that makes the request or if the fields to update include username, admin or enabled

Request data:

Field	Type	Required
username	String	No
password	String	No
admin	Boolean	No
enabled	Boolean	No
name	String, null	No
email	String, null	No

Response data:

Field	Type
message	String
message_type	String

Request example:

curl -X 'PUT' '{{ host_url }}users/user/<user_id>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>' \
-d '{"name": "Example User"}'

2.5. Delete User

Endpoint:	/users/user/<user_id>
Method:	DELETE
Request header:	Authorization: Bearer <access_token>
Description:	Delete a user
Fresh access token required:	Yes
Permission required:	Administrator

Response data:

Field	Type
message	String
message_type	String

Request example:

curl -X 'DELETE' '{{ host_url }}users/user/<user_id>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>'

3. Notebooks

3.1. Get Notebooks

Endpoint:	/notebooks/notebooks
Method:	GET
Request header:	Authorization: Bearer <access_token>
Description:	Get the list of notebooks of the user that makes the request

Response data:

Field	Type
message	String
message_type	String
result	List of objects: - id: String - name: String

Request example:

curl -X 'GET' '{{ host_url }}notebooks/notebooks' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>'

3.2. Get Notebook

Endpoint:	/notebooks/notebook/<notebook_id>
Method:	GET
Request header:	Authorization: Bearer <access_token>
Description:	Get a notebook

Response data:

Field	Type
message	String
message_type	String
result	Object: - id: String - name: String

Request example:

curl -X 'GET' '{{ host_url }}notebooks/notebook/<notebook_id>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>'

3.3. Create Notebook

Endpoint:	/notebooks/notebook
Methods:	POST, PUT
Request header:	Authorization: Bearer <access_token>
Description:	Create a notebook

Request data:

Field	Type	Required
name	String	Yes

Response data:

Field	Type
message	String
message_type	String
result	Object: - notebook_id: String

Request example:

curl -X 'POST' '{{ host_url }}notebooks/notebook' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>' \
-d '{"name": "Example Notebook"}'

3.4. Update Notebook

Endpoint:	/notebooks/notebook/<notebook_id>
Method:	PUT
Request header:	Authorization: Bearer <access_token>
Description:	Update some or all fields of a notebook

Request data:

Field	Type	Required
name	String	No

Response data:

Field	Type
message	String
message_type	String

Request example:

curl -X 'PUT' '{{ host_url }}notebooks/notebook/<notebook_id>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>' \
-d '{"name": "Example Notebook"}'

3.5. Delete Notebook

Endpoint:	/notebooks/notebook/<notebook_id>
Method:	DELETE
Request header:	Authorization: Bearer <access_token>
Description:	Delete a notebook

Response data:

Field	Type
message	String
message_type	String

Request example:

curl -X 'DELETE' '{{ host_url }}notebooks/notebook/<notebook_id>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>'

4. Tags

4.1. Get Tags

Endpoint:	/tags/tags/<notebook_id>
Method:	GET
Request header:	Authorization: Bearer <access_token>
Description:	Get the list of tags of a notebook

Response data:

Field	Type
message	String
message_type	String
result	List of objects: - id: String - name: String - color: String, null

Request example:

curl -X 'GET' '{{ host_url }}tags/tags/<notebook_id>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>'

4.2. Get Tag

Endpoint:	/tags/tag/<tag_id>
Method:	GET
Request header:	Authorization: Bearer <access_token>
Description:	Get a tag

Response data:

Field	Type
message	String
message_type	String
result	Object: - id: String - notebook_id: String - name: String - color: String, null

Request example:

curl -X 'GET' '{{ host_url }}tags/tag/<tag_id>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>'

4.3. Create Tag

Endpoint:	/tags/tag
Methods:	POST, PUT
Request header:	Authorization: Bearer <access_token>
Description:	Create a tag

Request data:

Field	Type	Required	Default value
notebook_id	String	Yes
name	String	Yes
color	String, null	No	null

Response data:

Field	Type
message	String
message_type	String
result	Object: - tag_id: String

Request example:

curl -X 'POST' '{{ host_url }}tags/tag' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>' \
-d '{"notebook_id": "<notebook_id>", "name": "Example Tag", "color": "#00ff00"}'

4.4. Update Tag

Endpoint:	/tags/tag/<tag_id>
Method:	PUT
Request header:	Authorization: Bearer <access_token>
Description:	Update some or all fields of a tag

Request data:

Field	Type	Required
name	String	No
color	String, null	No

Response data:

Field	Type
message	String
message_type	String

Request example:

curl -X 'PUT' '{{ host_url }}tags/tag/<tag_id>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>' \
-d '{"name": "Example Tag"}'

4.5. Delete Tag

Endpoint:	/tags/tag/<tag_id>
Method:	DELETE
Request header:	Authorization: Bearer <access_token>
Description:	Delete a tag

Response data:

Field	Type
message	String
message_type	String

Request example:

curl -X 'DELETE' '{{ host_url }}tags/tag/<tag_id>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>'

5. Notes

5.1. Get Notes

Endpoint:	/notes/notes/<notebook_id>
Method:	POST
Request header:	Authorization: Bearer <access_token>
Description:	Get the list of notes of a notebook by a filter

Request data:

Field	Type	Required	Comments
active	Boolean	No	If true, only active notes are returned. If false, only archived (not active) notes are returned. If this item is not present in the request data, then no filter by state is applied and all notes are returned regardless their state.
tags	List of strings	No	List of strings containing the tag names to filter the notes by. If this item is present in the request data, only notes than have any of these tags are returned in the result. If this item is not present in the request data, then no filter by tags is applied and all notes are returned regardless their tags.
no_tags	Boolean	No	This item applies only if the tags item is present in the request data too. If true, notes with no tags are returned as well. If false or if this item is not present in the request data, notes with no tags are not returned.
last_mod	Boolean	No	If true, returned notes are sorted by their Last Modified timestamp. If false or if this item is not present in the request data, the notes are sorted by their Created timestamp.
asc	Boolean	No	If true or if this item is not present in the request data, the order of the returned notes is ascending. If false, the order is descending.

Response data:

Field	Type
message	String
message_type	String
result	List of objects: - id: String - active: Boolean - title: String, null - created_ts: Integer - last_modified_ts: Integer - tags: List of objects: - id: String - name: String - color: String, null

Request example:

curl -X 'POST' '{{ host_url }}notes/notes/<notebook_id>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>' \
-d '{"active": true, "tags": ["tag_name_1", "tag_name_2"]}'

5.2. Get Note

Endpoint:	/notes/note/<note_id>
Method:	GET
Request header:	Authorization: Bearer <access_token>
Description:	Get a note

Response data:

Field	Type
message	String
message_type	String
result	Object: - id: String - notebook_id: String - active: Boolean - title: String, null - body: String, null - created_ts: Integer - last_modified_ts: Integer - tags: List of objects: - id: String - name: String - color: String, null

Request example:

curl -X 'GET' '{{ host_url }}notes/note/<note_id>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>'

5.3. Create Note

Endpoint:	/notes/note
Methods:	POST, PUT
Request header:	Authorization: Bearer <access_token>
Description:	Create a note

Request data:

Field	Type	Required	Default value
notebook_id	String	Yes
active	Boolean	No	true
title	String, null	No	null
body	String, null	No	null
tags	List of strings	No	[]

Response data:

Field	Type
message	String
message_type	String
result	Object: - note_id: String

Request example:

curl -X 'POST' '{{ host_url }}notes/note' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>' \
-d '{"notebook_id": "<notebook_id>", "title": "Example Note", "body": "This is a test note", tags: ["tag_name_1", "tag_name_2"]}'

5.4. Update Note

Endpoint:	/notes/note/<note_id>
Method:	PUT
Request header:	Authorization: Bearer <access_token>
Description:	Update some or all fields of a note

Request data:

Field	Type	Required
active	Boolean	No
title	String, null	No
body	String, null	No
tags	List of strings	No

Response data:

Field	Type
message	String
message_type	String

Request example:

curl -X 'PUT' '{{ host_url }}notes/note/<note_id>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>' \
-d '{"title": "Note Example", "active": false}'

5.5. Delete Note

Endpoint:	/notes/note/<note_id>
Method:	DELETE
Request header:	Authorization: Bearer <access_token>
Description:	Delete a note

Response data:

Field	Type
message	String
message_type	String

Request example:

curl -X 'DELETE' '{{ host_url }}notes/note/<note_id>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>'

6. Search

Endpoint:	/search/<search>
Method:	GET
Request header:	Authorization: Bearer <access_token>
Description:	Search for notebooks, tags and notes that match a given text

Response data:

Field	Type
message	String
message_type	String
result	Object: - notebooks: List of objects: - id: String - name: String - tags: List of objects: - id: String - notebook_id: String - name: String - color: String, null - notes: List of objects: - id: String - notebook_id: String - active: Boolean - title: String - created_ts: Integer - last_modified_ts: Integer - tags: List of objects: - id: String - name: String - color: String, null

Request example:

curl -X 'GET' '{{ host_url }}search/<search>' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <access_token>'