Home - and-se/nmbook_webapi GitHub Wiki

Назначение api

API предназначено для сбора и анализа сведений о Новомучениках Русской Православной Церкви.

Первоначальные данные взяты из изданий ПСТГУ "За Христа пострадавшие. Гонения на Русскую Православную Церковь. 1917-1956", но постоянно проверяются и дополняются.

Что делает api

Исследователям с правами записи API предоставляет возможность редактировать биографии Новомучеников в простом формате.

Биографии от исследователей разворачиваются в полные биографии с большим набором доступных для анализа полей. Пользователи могут искать полные биографии по различным критериям.

Корректоры следят за процессом преобразования биографий в полную версию и при необходимости вмешиваются.

На данный момент биография содержит в себе следующую информацию:

  • фамилия, имя, отчество (иногда несколько - для монахов, при разночтениях)
  • священный сан или иное церковное служение (например, певчий)
  • набор событий со следующими полями:
    • датировка
    • текст события
    • места, упомянутые в тексте события
    • сведения об источниках информации
    • сведения о связях с другими людьми в рамках описываемого события
  • сведения о канонизации
  • дополнительная информация в текстовой форме (рассказ о некоторых ярких эпизодах жизни, об обстоятельствах кончины пострадавшего за веру, иногда - развёрнутая статья)
  • приложенные фотографии и прочие файлы
  • сводный список источников информации и связей с другими людьми

Для кого api

  • исследователям новейшей истории РПЦ - позволяет анализровать и дополнять информацию о Новомучениках
  • рядовым пользователям - искать информацию по интересующим критериям.

Как работать с api

API реализовано согласно принципам REST. У каждого ресурса есть URL. Посредством отправки http-запросов на этот URL пользователь api производит те или иные операции над ресурсом.

В api сейчас есть следующие ресурсы:

  • коллекция биографий для редактирования /editor/dela
  • конкретная биография дле редактирования /editor/dela/{key}
  • коллекция полных биографий /public/dela
  • полная биография /public/dela/{key}
  • информация о файле и его содержимое /files/{file_id} и /files/{file_id}/content
  • средства авторизации и проверки прав доступа /login и /whoami
  • документация на все конечные точки /docs и /redoc

Зная URL ресурса, над ним можно произвести то или иное действие. Тип действия задаётся http-методом. В api используются следующие:

  • GET - получить ресурс или его часть (если это коллекция). Например, получить биографию либо 20 первых биографий на букву "Б". Условия отбора и формат результатов задаётся в параметрах URL.
  • POST - создать новый ресурс. В теле POST запроса нужно указать данные создаваемого ресурса. Например, создать новую биографию либо загрузить файл.
  • PUT - обновить существующий ресурс. В теле PUT запрос нужно указать новые данные. Например, внести изменения в существующую биографию.
  • DELETE - удалить ресурс. Например, удалить биографию.

Все данные api представляет в формате JSON. Также и при создании новых биографий нужно представлять их в виде JSON. Исключение - файлы и отчасти узел авторизации.

По умолчанию имена полей в JSON представлении биографии русскоязычные, что позволяет использовать специфичную для предметной области терминологию. Однако есть возможность получить данные с англоязычными полями, добавив параметр запроса eng.

Дальнейшее чтение