Category: REST

Golang и WOPI: превью документов через Office Online

Введение

Возникла у нас в компании проблема с превью документов, использовали мы для превью на портале всем известную тулзу от гугла. Но с ней были проблемы, у пользователя не всегда рендерился документ(видимо лимиты по количеству вызовов) и когда он рендерился, то бывало, что внешне превьюсильно отлиалосьот оригинала. Поэтому было решено разработать превью документов на нашем кор. портале с использованием уже имеющегося у нас Office Online.

Теория

По счастливому стечению обстоятельств для работы с документами в Office Online используется неплохо задокументированный протокол – WOPI (http://wopi.readthedocs.io/).

Что нам нужно реализовать для организации предпросмотра:

1) Нужно получить необходимые для обращения к Office Online данные:

– файл discovery.xml

– ссылка на файл /wopi/<fileId> и ссылка на действие офис онлайн из файла discovery.xml

– токен и время его жизни в виде таймстемпа в миллисекундах

2) Нужно написать реализацию метода CheckFileInfo, который будет возращать информацию о файле

3) Нужно написать реализацию метода GetFile, который будет возращать содержимое файла

Практика

Лучше слов расскажет код, шутка, на самом деле мне пока немного лень писать то, как это было реализовано 🙂

Но надеюсь, что и этот код сможет оказаться полезным.

https://github.com/ildarusmanov/msofficepreview

Проектирование Web API

Одним из самых распространенных подходов при проектировании API является REST API, что такое REST API можно узнать здесь.

Я же хочу рассказать о тех принципах, которые помогут сделать ваш API удобным для других разработчиков, т.е. для ваших клиентов.

Перейдем к принципам, поскольку для REST используется протокол HTTP, то он силньо завязан на его особенностях и в частности на адресе URL.

URL

Чтобы ваш API было легче понимать уделите особое внимание идентификаторам ваших ресурсов(URI):

  1. делайте минимальными и понятными(краткое название ресурса);
  2. абстрактные ресурсы лучше заменить на конкретные(/videos вместо /items)
  3. не используйте в них глаголы, вместо них используйте HTTP методы (POST, PUT, GET, PATCH, DELETE);
  4. используйте в названии только множественное или только единственное число для ресурсов во всем проекте;
  5. используйте не более двух адресов на один ресурс (/videos и /videos/{id});
  6. для вложенных ресурсов используйте URL вида /videos/{id}/comments;
  7. используйте простые и прозрачные имена в параметрах запросов после знака “?”;

Ошибки

Всегда обрабатывайте ошибки и сообщайте о них клиенту, используйте соответствующие коды статуса ответа HTTP, также сопровождайте ошибки описанием в теле ответа, возвращайте внятное текстовое описание ошибки.

Версии

Всегда версионизируйте API, например с помощью префикса /v1 или в заголовках и поддерживайте как минимум две последнии версии. Это позволит вашим клиентам плавно и без проблем переходить на новые версии вашего API.

Пагинация и поля ответа

Испольуйте для пагинации параметры limit и offset, не забывайте возвращать в ответе общее количество доступных ресурсов.

Клиентам не всегда нужны все доступные поля, потому предусмотрите возможность кастомизации списка возвращаемых полей параметром fields.

Параметр fields может содержать одно и более названий полей, перечисленных через запятую, эта возможность бывает полезной для сложных ресурсов с большим количеством метаданных.

API субдомен

Выделите для вашего API отдельный субдомен(например api.example.com/v{version_id}) и сосредоточьте все ваше API в зоне этого субдомена.

Формат

Для передачи формата входных и получаемых данных указывайте формат в виде расширения файла(например /v1/videos.json) и обеспечьте поддержку нескольких форматов данных.

Интеграция и документация

Напишите SDK или библиотеки для платформ, которые используют ваши клиенты. Cопроводите это все качественными и подробными примерами использования вашего API и документацией по использованию ваших инструментов и API.