Notion API выйдет весной, но пользоваться им можно уже сейчас

На днях Notion рассказала о запуске закрытого бета-тестирования своего официального API, которое находилось в разработке не меньше двух лет. На страничке ^[1] очень мало конкретной информации, не описан даже приблизительный функционал, но можно оставить заявку на участие — компания обещает постепенно раскрывать информацию и опрашивать разработчиков, чтобы выкатить как можно более удобный и полезный интерфейс. Единственная загвоздка в том, что этот долгострой пока не близок к завершению, запуск назначен на весну 2021 года и легко может сдвинуться, как это уже случалось раньше. Но если ждать некогда и хочется поработать с API сейчас, можно воспользоваться одной из пользовательских реализаций на разных языках и с разным функционалом.

API с доступом к чтению публичных данных довольно много, а полноценная запись реализована только в питоновом notion-py. Так как нормальной возможности получить токен нет, все варианты — это обёртки для внутреннего Notion API и для доступа к приватным данным нужно достать токен из кук:

В DevTools можно взять значение token_v2 из куки notion.so

Неофициальные реализации API

notion-py

Самый крупный и проработанный проект, написан на питоне.
Репозиторий ^[2] (2.1k звёзд / 224 форка)

• Реактивные чтение/запись в любых местах
• Перевод данных из внутренних форматов Notion в объекты питона, компиляция таблиц баз данных в классы/атрибуты
• Кэширование данных в локальном хранилище
• Колбеки для действий и внешних изменений
• Много примеров и тестов, покрытие основных юзкейсов

notion-py используется более чем в 240 репозиториях и точно останется лучшим проектом до релиза официального API. Может полноценно записывать любые данные, от текста до загрузки файлов, и в реальном времени реагирует на изменения. Для большинства типов данных нет валидации, поэтому при работе с пользовательским вводом её придётся писать самостоятельно. Централизованное хранилище отключено по умолчанию, но довольно полезно для больших объёмов данных и тяжёлых операций. Редактировать можно не только страницы целиком, но и отдельные блоки по их id.

notionapi

Предшественник и вдохновитель notion-py, реализация для Go
Репозиторий ^[3] (1.4k звёзд / 59 форков)

• Чтение публичных и приватных страниц и блоков
• Ограниченная запись: можно изменять заголовки и форматы страниц
• Из коробки доступны типы блоков, в которых сохраняются полученные блоки Notion'а
• Есть готовые конвертеры в HTML и Markdown

Функционал записи на самом деле не страдает от каких-то ограничений, автор просто написал ровно столько, сколько ему самому было нужно. При желании можно допилить до уровня notion-py, но пока таких Go-энтузиастов не нашлось. notionapi используется в проекте presstige.io ^[4], где Notion выступает в роли CMS, а посты публикуются на presstige.

notion-api

Обёртка для JS, доступна на npm.
Репозиторий ( 222 звёзды / 28 форков), npm ^[5] (44 загрузки за неделю)

Это очень нехитрая библиотека, она умеет только читать публичные и (при наличии токена) приватные страницы по id или список страниц по id корня. Данные не парсятся, ответ возвращается в виде строки.

notion-sdk-kotlin

Реализация на Kotlin/Java
Репозиторий ^[6] (45 звёзд)

Здесь также только базовый функционал чтения по id и авторизация как по токену, так и по email с паролем. Есть готовый маппинг данных из таблиц/коллекций. Зато на котлине.

Примеры использования

notion-api-worker

Ещё пример использования Notion в качестве CMS
Репозиторий ^[7] ( 538 звёзд / 38 форков)

Есть хостинг ^[8], но веселее такое развернуть самостоятельно. Позволяет удобно пользоваться данными, взаимодействовать с базами данных, использует моднейшее stale-while-revalidate ^[9] кэширование.

react-notion-x

Турбо-ускоритель для публичных страничек на Notion
Репозиторий ^[10] ( 137 звёзд / 9 форков)

NotionX — почти полностью доделанный проект по рендерингу страниц Notion на React. Приложение просто получает даныне из API и отрисовывает их в несколько раз быстрее оригинала. Поддерживаются все блоки (внушительный список), кроме календаря, но и это вопрос времени. Автор очень любит оптимизировать:

md2notion

Конвертер из Markdown в Notion
Репозиторий ^[11] ( 175 звёзд / 12 форков)

Импортирует содержимое md-файла в страницу на Notion. Написан на питоне, есть CLI. Очень продуманный инструмент, бережно обращается с данными:

• Сохраняет форматирование кода, насколько это возможно
• Сохраняет inline HTML
• Работает со списками и вложенными структурами
• Умеет загружать картинки по URL и записывать alt'ы в подписи в Notion

Заключение

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

На правах рекламы

VDSina предлагает VDS ^[12] с посуточной оплатой, возможностью в пару кликов создать собственную конфигурацию сервера, установить любую операционную систему. Каждый сервер подключён к интернет-каналу в 500 Мегабит и бесплатно защищён от DDoS-атак!

Автор: Mikhail

Источник ^[13]