Ruby On Rails GEMS – CRUD контроллер с decent_exposure

Решил я недавно вспомнить RubyOnRails на котором писал 3 года и было это 2 года назад, поэтому вспоминать пришлось многое, хотя и не все.

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

Об одном из них и этот пост, называется он decent_exposure, его задача упростить наисание CRUD контроллеров.

Подробно с этим компонентом можно ознакомиться перейдя на гитхаб проекта – https://github.com/hashrocket/decent_exposure

Ниже пример использования 🙂

 

Проектирование 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.

Golang: пакеты

По поводу пакетов в голанге есть множество статей и ресурсов, например – https://thenewstack.io/understanding-golang-packages/. Но лично у меня в самом начале изучения этого языка прграммирования возникли две проблемы:

  1. Как использовать пакеты внутри совего приложения для разделения кода(что-то вроде namespace в других языках);
  2. Ошибка цикличного импорта пакетов.

Первый вопрос снимается легко, допустим у нас в проекте с названием project7(директория /go/src/project7) есть модели и контроллеры в соответствующих директориях(models и controllers), тогда мы можем их использовать в нашем главном файле main.go вот так:


То есть, по сути мы просто используем их как локальный неймспейс, все очень просто.

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

Т.е. получается, что вы попадаете в бесконечный цикл импорта, так как оба пакета импортируют друг друга.

Избежать этой проблемы легко – используйте интерфейсы.