Skip to content

API волонтера

Jump to bottom
sky-pro-student edited this page Jul 13, 2023 · 19 revisions

Разработка API

статус документа:

  • отредактирован 13.07. Открыт для обсуждения
  • отредактирован 14.07. Открыт для обсуждения. Уточнены способы передачи значений (@RequestParam/@RequestBody/@PathVariable), добавлено получение списка адоптеров, не имеющих животных на испытательном сроке и поэтому считающихся готовыми к пробной адоптации. Фактически данная версия спецификации содержит схему-копипаст для java-деклараций методов контроллера.

Спецификация API

API - это набор end point-ов, предоставляемый сотрудникам шелтера в приложении pet-sheletr-bot.
В приложении существует по-меньшей мере два рабочих места: одно работает с шелтером котов, второе - с шелтером собак.

API обеспечивает бизнес-логику, которая соответствует ответам на следующие на вопросы:

  • как животные будут попадать в БД?
  • как назначается адоптер животным?
  • как сотрудники смогут проверять отчёты?
  • как сотрудники добавят, удалят запись о волонтёре и просмотрят список волонтёров шелтера?

Комментарии (документация) оформляется через OpenAPI-аннотации

@RequestMapping: /cat-shelter, /dog-shelter, /pet, /adopter

GET /adopter/all-ready-to-adopt

pageable

@ApiResponse(
    description="Список всех адоптеров в **системе**, для которых нет животных на испытательном периоде."
)
@RequestParameter(description="номер страницы") int page
@RequestParameter(description="количество записей на странице") int size

POST /cat-shelter/add

POST /dog-shelter/add

@ApiResponse(
    description="Добавляет кота в кошачий шелтер/собаку в собачий шелтер. Показывает сохраненные значения из БД и сообщает,
        что данные о животном сохранены или не сохранены."
)
@RequestBody(description="Животное к добавлению") Pet pet

GET /cat-shelter/pets

GET /dog-shelter/pets

pageable

@ApiResponse(
    description="Распечатывает страницу из списка всех котов, то есть как находящихся в приюте, 
        так и адоптируемых или находящихся в адоптации. Поиск в методах осуществляется по shelter_id"
)

@RequestParameter(description="номер страницы") int page
@RequestParameter(description="количество записей на странице") int size

PUT /pet/setAdopter

@ApiResponse(
    description="Назначение животному адоптера: 
    устанавливается значение полей животного Pet.adopter и дата утверждения адоптации Pet.adoptaitionDate"
)
@RequestBody(description="животное"))     Pet pet
@RequestBody(description="адоптер") Adopter adopter

PUT /pet/prolongTrial14/{petId}

@ApiResponse(
    description="Продлевает пробный период адоптации  на 14 дней"
)
@PathVariable(description="идентификатор животного"))  long pet_Id

PUT /pet/prolongTrial30/{petId}

@ApiResponse(
    description="Продлевает пробный период адоптации  на 30 дней"
)
@PathVariable(description="идентификатор животного"))  long petId

PUT /pet/cancelTrial/{petId}

@ApiResponse(
    description="Отменяет пробный период: это значит, что пробный период не пройден,
и животное возвращают в приют"
)
@PathVariable(description="идентификатор кота"))  long petId



/cat-shelter/reports

/dog-shelter/reports

API консоли по работе с ежедневными отчётами адоптеров

GET /cat-shelter/reports/all

GET /dog-shelter/reports/all

pageable

@ApiResponse(
    description="Распечатывает все имеющиеся в базе данных отчёты пользователей, сортированные по дате."
)
@RequestParameter(description="номер страницы") int page
@RequestParameter(description="количество записей на странице") int size

GET /cat-shelter/reports/to-review

GET /dog-shelter/reports/to-review

pageable

@ApiResponse(
    description="Распечатывает все отчёты пользователей, требующие проверки."
)
@RequestParameter(description="номер страницы") int page
@RequestParameter(description="количество записей на странице") int size

GET /cat-shelter/reports/{pet_id}

GET /dog-shelter/reports/{pet_id}

@ApiResponse(
    description="Распечатывает в хронологическом порядке все отчёты по конкретному животному"
)
@PathVariable(description="идентификатор животного"))  Long petId

GET /cat-shelter/overdue-reports/

GET /dog-shelter/overdue-reports/

@ApiResponse(
    description="Возвращает животных на пробном периоде адоптации, 
        для которых адоптеры не прислали текущие отчёты своевременно"
)

PUT /cat-shelter/reports/

PUT /dog-shelter/reports/

@PutMapping
@ApiResponse(
    description="Обновляет страницу отчётов в базе данных. Предполагается, что
посылаемые отчёты могут иметь обновление в полях Report.checked и Report.approved. 
При этом если approved == false, то пользователю отсылается сообщение с рекомендацией
заполнять отчёты более полно"
)
@RequestBody(description="список верифицированных отчётов") Collection <Reports> reportsPage

GET /cat-shelter/volunteers/

GET /dog-shelter/volunteers/

@GetMapping
@ApiResponse(
    description="Возвращает список всех волонтёров шелтера"
    @RequestBody(description="волонтёр к добавлению") Volunteer volunteer
)

POST /cat-shelter/volunteers/

POST /dog-shelter/volunteers/

@PostMapping
@ApiResponse(
    description="Добавляет волонтёра в список волонтёров шелтера"
@RequestBody(description="список верифицированных отчётов") Collection <Reports>
)

DELETE /cat-shelter/volunteers/

DELETE /dog-shelter/volunteers/

@DeleteMapping
@ApiResponse(
    description="Удаляет волонтёра из списка волонтёров шелтера"
@PathVariable(description="идентификатор волонтёра"))  Long chatId
)
Clone this wiki locally