Преминете към основното съдържание

OMI-SPEC-310 — Платформа „API“

Статус​

Чернова

Версия: 0.1.0

Старият идентификатор: OMI-SPEC-010

Цел

Платформата „API“ определя начина, по който външни приложения, плъгини, инструменти за автоматизация и платформи за публикуване взаимодействат с „Open Manuscript Initiative“ (OMI).

Системата за управление на научни ресурси „API“ е проектирана да работи със семантични научни обекти, а не с файлове.

Принципи на проектирането

Платформата API се ръководи от следните принципи:

  • API Първо
  • Обектно-ориентирано
  • Управлявано от събития
  • Независима от платформата
  • С версии
  • Сигурно
  • Разширяем

API Слоеве

Applications

↓

REST API

↓

Event API

↓

Plugin API

↓

OMI Core

Основни ресурси

Репозиториумът „API“ предоставя достъп до научни обекти.

Примери:

  • Документи
  • Раздели
  • Абзаци
  • Опорни точки
  • Бележки
  • Източници
  • Метаданни
  • Отзиви
  • Набори от данни
  • Автори
  • Членства
  • Профили на публикациите

REST API

Типичните крайни точки включват:

GET    /documents

POST   /documents

GET    /documents/{id}

PATCH  /documents/{id}

DELETE /documents/{id}

Обектите се обменят като структурирани обекти от типа „JSON“.

Обект API

Всеки научен обект следва единен интерфейс.

Пример:

GET /objects/{id}

Отговор:

{
  "id": "omi:citation:8f5a21",
  "type": "Citation",
  "version": 4,
  "metadata": {},
  "relationships": {}
}

Събитие „API“

OMI публикува събития, описващи промените в ръкописа.

Примери:

  • Дата на създаване на документа
  • Отворен документ
  • Създаден обект
  • ObjectUpdated
  • AnchorCreated
  • Добавена анотация
  • Цитиране: Проверено
  • Отзивът е изпратен
  • Публикацията започна
  • Публикация – Завършена

Плъгините се абонират за събития, вместо да променят директно ядрото.

Плъгин „API“

Плъгините взаимодействат с „OMI“ чрез стабилни интерфейси.

Примери:

register()

activate()

deactivate()

dispose()

Добавките никога не получават достъп до вътрешни детайли на реализацията.

Рендериране на API

Рендерите за публикации реализират общ интерфейс.

Пример:

render(document, profile)

Възможни резултати:

  • HTML
  • PDF
  • EPUB
  • DOCX
  • JATS XML
  • Markdown

Проверка API

Услугите за валидиране могат да извършват проверка на научни обекти.

Примери:

  • Проверка на метаданните
  • Проверка на източниците
  • Проверка на достъпността
  • Валидиране за конкретна дисциплина

Валидирането генерира структурирани отчети.

Удостоверяване на автентичността

Възможните методи за удостоверяване на самоличността включват:

  • OAuth 2.1
  • OpenID Connect
  • API Жетони
  • Служебни акаунти

Методите за удостоверяване зависят от конкретната реализация.

Упълномощаване

Правата за достъп могат да се предоставят на различни нива.

Примери:

  • Прочети документа
  • Редактиране на метаданни
  • Създаване на бележка
  • Изпрати отзив
  • Публикувай
  • Управление на плъгините

Авторизацията трябва да поддържа контрол на достъпа въз основа на роли и на ниво обект.

Управление на версиите

„API“ е версиониран.

Пример:

/api/v1/
/api/v2/

Промените, които водят до несъвместимост, изискват нова версия на „API“.

Уебхукове

Външни системи могат да се абонират за събития.

Примери:

POST

DocumentPublished

↓

https://journal.example/webhook

Подкрепяните събития могат да включват:

  • публикацията е завършена
  • прегледът е изпратен
  • ръкописът е приет
  • метаданните са актуализирани

Операции с партиди

Функцията „API“ трябва да поддържа пакетна обработка.

Примери:

  • провери всички цитати
  • възстановяване на метаданните
  • експортиране на всички формати на публикациите
  • импортиране на колекции от обекти

Търсене в „API“

Търсенето е по-скоро семантично, отколкото текстово.

Примери:

author = "Smith"

↓

all manuscripts
citation DOI = ...

↓

all references
object type = Figure

↓

all figures

Оперативна съвместимост

Бъдещите интеграции включват:

  • OJS
  • OMP
  • OPS
  • Crossref
  • DataCite
  • ORCID
  • Zenodo
  • GitHub
  • n8n
  • Zotero

Бъдещи задачи

Бъдещите спецификации ще определят:

  • Графика API
  • Език за заявки
  • Обект API
  • Синхронизация API
  • Разширение за изкуствен интелект „API“

Хронология на промените

  • 0.1.0 — Прехвърлено от временния адрес OMI-SPEC-010 към основния адрес OMI-SPEC-310.

Обобщение

Платформата „OMI“ (API) предоставя стабилен, версиониран и обектно-ориентиран интерфейс за научна комуникация.

Вместо да предоставя достъп до файлове, платформата „API“ предоставя достъп до семантични научни обекти, като по този начин осигурява оперативна съвместимост между издателски системи, хранилища, платформи за автоматизация и бъдещи научни инфраструктури.