Документация Bookmates

О проекте

Bookmates - дает возможность зарегистрироваться и постить свои заметки о книгах, собирать лайки и комментарии. Находить единомышленников, обсуждать книги, проводить совместные чтения. Отслеживать свой прогресс по чтению, делать заметки в ходе чтения. Искать любые посты об интересных тебе книгах.

User

Create User - Метод регистрации пользователя

Request

POST {{url}}/users

Параметры запроса (raw json)

Параметр	Описание	Обязательность
email	email пользователя	Да
password	Пароль пользователя	Да

Response

Успешная обработка запроса:

Код ответа - 201 Created
И объект в формате json

{
"id": "id", 
"email": "email"
}

Неуспешная обработка запроса:

• Данный пользователь уже зарегистрирован в системе
  Код ответа - 409
  И объект в формате json

{
"detail": "User with this email is already registered"
}

• Не переданы обязательные параметры или переданы некорректные значения
  Код ответа - 422
  И объект в формате json с указанием на ошибку

---

Get User - Метод поиска пользователя

Request

GET

{{url}}/users/{{id}}

Параметр	Описание	Обязательность	Тип
id	Уникальный идентификатор пользователя	Да	Integer

Response

Успешная обработка запроса:

Код ответа - 200 Ok
И объект в формате json

{
"id": "id",
"email": "email"
}

Неуспешная обработка запроса:

• Данный пользователь Не зарегистрирован в системе
  Код ответа - 404 Not Found И объект в формате json

{
"detail": "User with id {{id}} was not found"
}

• Не переданы обязательные параметры Код ответа - 405 Method Not Allowed И объект в формате json

{
"detail": "Method Not Allowed"
}

• В параметре передано невалидное значение Код ответа - 422 Unprocessable Entity И объект в формате json с указанием на ошибку

---

Authentication

Login User - Метод авторизации пользователя

!!! Токен авторизации действителен в течение 30 минут

Request

POST

{{url}}/login

Параметры запроса (form-data)

Параметр	Описание	Обязательность
username	email пользователя	Да
password	Пароль пользователя	Да

Response

Успешная обработка запроса:

Код ответа - 200 Ок И объект в формате json

{
"access_token": "access_token",
"token_type": "bearer"  
}

Неуспешная обработка запроса:

• Данные пользователя не зарегистрированы в системе
  Код ответа - 404 И объект в формате json

{
"detail": "Invalid credentials"
}

• Не переданы обязательные параметры
  Код ответа - 422
  И объект в формате json с указанием на отсутствующий параметр

---

Book

Get Books - Метод поиска книг

Request

GET {{url}}/books?[limit=10]&[rating=None]

Параметр	Описание	Обязательность	Тип	Значение по умолчанию
limit	Количество записей для вывода пользователю	Нет	Integer	10
rating	Рэйтинг книг. Пользователь увидит список книг с рейтингом, равным или больше указанного	Нет	Float	None

Response

Успешная обработка запроса:

Код ответа - 200 Ok
И объект в формате json

[
{
 "title": "title",
 "author": "author",
 "rating": 0.0,            
 "id": "id",
 "created_at": "datatime",
 "owner_id": "id",
 "owner": {
    "id": "id",
    "email": "email"
    }
 },
 {}
]

Поле	Описание	Тип
title	Название книги	string
author	Автор книги	string
rating	Рейтинг книги, по мнению пользователя, запостившего эту запись	float
id	Уникальный идентификатор записи о книге	integer
created_at	Дата создания записи о книге	datatime
owner_id	Уникальный идентификатор пользователя, запостившего книгу	integer
owner_id/id	Уникальный идентификатор пользователя, запостившего книгу	integer
owner_id/email	Емейл пользователя, запостившего книгу	string

Неуспешная обработка запроса:

• В параметре передано невалидное значение
  Код ответа - 422 Unprocessable Entity
  И объект в формате json с указанием на ошибку

---

Get Books by title - Метод поиска книг по названию

Request

GET {{url}}/books/by-title/{title}?[limit=10]&[rating=None]

Параметр	Описание	Обязательность	Тип	Значение по умолчанию
title	Название книги	Да	String	-
limit	Количество записей для вывода пользователю	Нет	Integer	10
rating	Рэйтинг книг. Пользователь увидит список книг с рейтингом, равным или больше указанного	Нет	Float	None

Response

Успешная обработка запроса:

Код ответа - 200 Ok И объект в формате json

[
{
"title": "title",
"author": "author",
"rating": 0.0,
"id": "id",
"created_at": "datatime",
"owner_id": "id",
"owner": {
    "id": "id",
    "email": "email"
    }
},
{}
]

Поле	Описание	Тип
title	Название книги	string
author	Автор книги	string
rating	Рейтинг книги, по мнению пользователя, запостившего эту запись	float
id	Уникальный идентификатор записи о книге	integer
created_at	Дата создания записи о книге	datatime
owner_id	Уникальный идентификатор пользователя, запостившего книгу	integer
owner_id/id	Уникальный идентификатор пользователя, запостившего книгу	integer
owner_id/email	Емейл пользователя, запостившего книгу	string

Неуспешная обработка запроса:

• В параметре передано невалидное значение
  Код ответа - 422 Unprocessable Entity
  И объект в формате json с указанием на ошибку

---

Get Books by author - Метод поиска книг по автору

Request

GET {{url}}/books/by-author/{author}?[limit=10]&[rating=None]

Параметр	Описание	Обязательность	Тип	Значение по умолчанию
author	Автор книги	Да	String	-
limit	Количество записей для вывода пользователю	Нет	Integer	10
rating	Рэйтинг книг. Пользователь увидит список книг с рейтингом, равным или больше указанного	Нет	Float	None

Response

Успешная обработка запроса:

Код ответа - 200 Ok
И объект в формате json

[
{
"title": "title",
"author": "author",
"rating": 0.0,
"id": "id",
"created_at": "datatime",
"owner_id": "id",
"owner": {
    "id": "id",
    "email": "email"
    }
},
{}
]

Поле	Описание	Тип
title	Название книги	string
author	Автор книги	string
rating	Рейтинг книги, по мнению пользователя, запостившего эту запись	float
id	Уникальный идентификатор записи о книге	integer
created_at	Дата создания записи о книге	datatime
owner_id	Уникальный идентификатор пользователя, запостившего книгу	integer
owner_id/id	Уникальный идентификатор пользователя, запостившего книгу	integer
owner_id/email	Емейл пользователя, запостившего книгу	string

Неуспешная обработка запроса:

• В параметре передано невалидное значение
  Код ответа - 422 Unprocessable Entity
  И объект в формате json с указанием на ошибку

---

Create Book - Метод создания записи о книге

Request

POST (Метод доступен только авторизованным пользователям) {{url}}/books

Параметры запроса (raw json)

Параметр	Описание	Обязательность	Тип
title	Название книги	Да	string
author	Автор книги	Нет	string
rating	Рейтинг книги по мнению пользователя	Нет	float
description	Заметки/Мнение о книге	Нет	string
status_of_book	Статус книги (Читаю/Прочитана/Отложена)	Да	string

Response

Успешная обработка запроса:

Код ответа - 201 Created
И объект в формате json

{
"title": "title",
"author": "author",
"rating": "rating",
"description": "description",
"status_of_book": "status_of_book",
"id": "id", 
"created_at": "datatime",
"owner_id": "id",
"owner": {
    "id": "id",
    "email": "email"
    }
}

Неуспешная обработка запроса:

• Не переданы обязательные параметры или переданы некорректные значения
  Код ответа - 422
  И объект в формате json с указанием на ошибку

---

Update Book - Метод создания записи о книге

Request

PUT (Метод доступен только авторизованным пользователям) {{url}}/books/{{id}}

Path parameter: id - Уникальный идентификатор книги (Integer), Обязательный

Параметры запроса (raw json)

Параметр	Описание	Обязательность	Тип
title	Название книги	Да	string
author	Автор книги	Нет	string
rating	Рейтинг книги по мнению пользователя	Нет	float
description	Заметки/Мнение о книге	Нет	string
status_of_book	Статус книги (Читаю/Прочитана/Отложена)	Да	string

Response

Успешная обработка запроса:

Код ответа - 200 Ok
И объект в формате json

{
"title": "title",
"author": "author",
"rating": "rating",
"description": "description",
"status_of_book": "status_of_book",    
"id": "id", 
"created_at": "datatime",
"owner_id": "id",
    "owner": {
        "id": "id",
        "email": "email"
    }
}

Неуспешная обработка запроса:

• Отсутствует запись с указанным id
  Код ответа - 404 Not Found
  И объект в формате json с указанием на ошибку

{
"detail": "book with id {id} was not found"
} 

• Не переданы обязательные параметры или переданы некорректные значения
  Код ответа - 422
  И объект в формате json с указанием на ошибку

---

Delete Book - Метод удаления записи о книге

Request

DELETE (Метод доступен только авторизованным пользователям) {{url}}/books/{{id}}

Path parameter:

Параметр	Описание	Обязательность	Тип
id	Уникальный идентификатор книги	Да	Integer

Response

Успешная обработка запроса:

Код ответа - 204 No Content

Неуспешная обработка запроса:

• Отсутствует запись с указанным id
  Код ответа - 404 Not Found
  И объект в формате json с указанием на ошибку

{
"detail": "book with id {id} was not found"
}

• Пользователь не авторизован или токен авторизации истек Код ответа - 403 Forbidden
  И объект в формате json с указанием на ошибку

{
"detail": "Not authorized to perform requested action"
}

• Не переданы обязательные параметры или переданы некорректные значения
  Код ответа - 422
  И объект в формате json с указанием на ошибку

---

Get Book - Метод поиска конкретной книги по указанному id

Request

GET {{url}}/books/{{id}}

Path parameter:

Параметр	Описание	Обязательность	Тип
id	Уникальный идентификатор книги	Да	Integer

Response

Успешная обработка запроса:

Код ответа - 200 Ok
И объект в формате json

{
"title": "title",
"author": "author",
"rating": 0.0,
"id": "id",
"created_at": "datatime",
"owner_id": "id",
"owner": {
    "id": "id",
    "email": "email"
    }
}

Поле	Описание	Тип
title	Название книги	string
author	Автор книги	string
rating	Рейтинг книги, по мнению пользователя, запостившего эту запись	float
id	Уникальный идентификатор записи о книге	integer
created_at	Дата создания записи о книге	datatime
owner_id	Уникальный идентификатор пользователя, запостившего книгу	integer
owner_id/id	Уникальный идентификатор пользователя, запостившего книгу	integer
owner_id/email	Емейл пользователя, запостившего книгу	string

Неуспешная обработка запроса:

• Отсутствует запись с указанным id
  Код ответа - 404 Not Found
  И объект в формате json с указанием на ошибку

{
"detail": "book with id {id} was not found"
}

• Пользователь не авторизован или токен авторизации истек Код ответа - 403 Forbidden
  И объект в формате json с указанием на ошибку

{
"detail": "Not authorized to perform requested action"
}

• Не переданы обязательные параметры или переданы некорректные значения
  Код ответа - 422 Unprocessable Entity
  И объект в формате json с указанием на ошибку

---

Vote

Create vote - Метод отправки лайка для записи о книге

Request

POST (Метод доступен только авторизованным пользователям) {{url}}/votes/{{id}}

Path parameter: id - Уникальный идентификатор книги (Integer), Обязательный

Параметры запроса (raw json)

Параметр	Описание	Обязательность	Тип
book_id	Идентификатор книги	Да	Integer
dir	Флаг: ставим или удаляем лайк (1 - ставим, 0 - удаляем)	Да	Integer

Response

Успешная обработка запроса:

Код ответа - 201 Created
И объект в формате json

{
"msg": "successfully added vote"
}

или

{
"msg": "successfully deleted vote"
}

Неуспешная обработка запроса:

• Отсутствует запись с указанным id
  Код ответа - 404 Not Found
  И объект в формате json с указанием на ошибку

{
"detail": "book with id {id} was not found"
}

• Пользователь не авторизован или токен авторизации истек Код ответа - 403 Forbidden
  И объект в формате json с указанием на ошибку

{
"detail": "Not authorized to perform requested action"
}

• Пользователь пытается повторно поставить лайк Код ответа - 409 Conflict
  И объект в формате json с указанием на ошибку ```json { "detail": "user {user_id} has alredy voted on book {book_id}" }
• Пользователь пытается повторно удалить лайк Код ответа - 404 Not Found
  И объект в формате json с указанием на ошибку ```json { "detail": "Vote does not exist" }

---