Уровни зрелости частного REST API и дополнительные уровни сложности

HAL - это всего лишь один формат. Цель состоит в том, чтобы иметь возможность обнаруживать / перемещаться по API с помощью ссылок. Таким образом, это не обязательно должно быть в формате HAL, если вы можете выполнить цель. Мне лично не нравится формат HAL, но мне очень полезно иметь ссылки на связанные объекты.

@PaulSamsotha, я согласен с вами, HAL не является обязательным и часто является делом вкуса, но в случае HATEOAS это необходимо для частного API с одним и определенным клиентом (на данный момент)? Есть ли какие-то преимущества, кроме лишения клиентского интерфейса необходимости создавать ссылки для доступа к определенным конечным точкам? Поскольку мы можем устно сообщить, к какой конечной точке получить доступ для определенных действий.

Если я обращаюсь к конечной точке для клиента, и у клиента есть список связанных с ней заказов, нужны ли мне все данные заказа или я просто предпочитаю иметь URL-адрес, указывающий на данные заказа, которые я могу получить, когда захочу? Наверное, последнее. Это то, что я имею в виду под удобством обнаружения и навигации. Вы должны иметь возможность перемещаться по разным ссылкам. Вы не видите в этом пользы?

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

Очень хороший пример, который прояснил ситуацию. Но давайте предположим, что наш API используется только для внутренних целей, где конечные точки могут быть доступны через документацию и обмен данными. И вместо того, чтобы иметь конечную точку для клиента, которая в полезной нагрузке также предоставляет конечную точку для его заказов, просто имейте две конечные точки: api / customers и api / customers / {: id} / orders и передайте их разработчику интерфейса через любой канал. ты хочешь.

Есть разные типы разработчиков: те, кто любит переходить по ссылкам, и те, кто любит документы. Мне лично нравятся ссылки. Если я заворачиваю конечную точку во время изучения API, я хочу видеть ссылки, чтобы я мог видеть, что еще связано с клиентом. У вас должны быть и документы, и ссылки. Удовлетворите оба типа разработчиков.

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

Вам следует применять принципы REST всякий раз, когда вы не хотите, чтобы изменения сервера нарушили работу клиентов. REST - это просто обобщение Интернета, в котором браузеры остаются стабильными всякий раз, когда сервер меняет, то есть URI определенных ресурсов или добавляет новый контент. Если вам не нужны такие свойства (то есть ваш сервер и клиент всегда меняются вместе, и всегда доступна только одна версия), просто не переходите на REST-поезд, но не попадайтесь в маркетинговую ловушку и просто не используйте не называйте это REST API / клиент, тогда

чтобы предоставить больше контекста: в первую очередь закрытый API будет использоваться веб-приложением и, в конечном итоге, мобильным клиентом. И в настоящее время я ищу лучшие практики, которые действительно принесут пользу закрытому API.

С точки зрения зрелости REST API, учитывая, что вы будете иметь дело с двумя клиентами, оба из которых являются внутренними, я думаю, вам следует придерживаться правильного использования HTTP-глаголов и согласованного дизайна URI.

@RomanVottner: ну, если вы хотите прострелить себе ногу (как вы описали в своем примере), я считаю, что никакие рекомендации по дизайну, принципы и классификации вас не остановят. Я думаю, что вся идея, лежащая в основе модели зрелости Ричардсона, состоит в том, чтобы предоставить некоторые руководящие принципы, которые в данном контексте, относительно определенных осей изменений, потенциально могут обеспечить некоторую гибкость при заданных затратах. Это ни в коем случае не серебряная пуля дизайна API. Перед применением вы должны проанализировать, есть ли у вас какие-либо проблемы, которые он пытается исправить.

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

Если вы задумаетесь о том, как Интернет развился до своего текущего состояния, вы можете согласиться с тем, что его успех, вероятно, был обеспечен благодаря его надежности и свободе, которую он предоставил веб-серверам, предоставляющим веб-контент. Помимо HTML-страниц, обменивается тонна дополнительного контента, такого как изображения, видео и многое другое. Множество функций добавлялось с годами с помощью расширений или плагинов. Вместо того, чтобы браузер ожидал, что определенная ссылка вернет изображение PNG, клиент сообщает серверу, в каком формате он может работать, и сервер предоставит (в идеале) представление, понятное клиенту.

Это именно то, что REST пытается предоставить другому приложению, кроме веб-браузера. Большинство так называемых REST API - это RPC только с надетой на них маркетинговой меткой «REST». Поэтому я не думаю, что прицеливание в ОТДЫХ - это удар себе в ногу. Я скорее пытаюсь понять смысл раскрытия уровня БД через дополнительный уровень модели и преобразовать его в JSON с помощью операций CRUD вместо прямого раскрытия самой БД, особенно для внутреннего приложения. БД уже предоставляет множество вещей, таких как просмотры или ограничения пользователей.

@RomanVottner Я согласен, вебу нужна была масса гибкости, и в этом случае имело смысл разрабатывать его с учетом этой гибкости. Но я думаю, что немногие приложения, которые мы разрабатываем сегодня, имеют (реально говоря) те же ограничения, что и Интернет. Вы не согласны?

Что ж, если у вас действительно нет бизнес-логики (то есть вы действительно используете только CRUD через HTTP), RPC может быть более разумным подходом.

По крайней мере, по моему опыту, большинство приложений не являются ни "сетью", ни обычным "CRUD через HTTP". Они обычно находятся где-то посередине. Я понимаю вашу точку зрения (и моя инженерная сторона фактически согласна с вами, гораздо круче создавать REST API, чем маскированный RPC), но с точки зрения бизнеса чистота архитектуры редко вызывает беспокойство. Наши контексты редко бывают чисто техническими.

В конце концов, нам платят за предоставление наилучшего решения в срок и в рамках бюджета, и наши инженерные решения должны это отражать (IMO).

Проголосовали за решение, поскольку понимание, которое я нашел в этих комментариях, было намного больше, чем я просил. Реквизиты вам @RomanVottner и @alexrolea!

@AdrianBrad рад, что наша дискуссия была вам чем-то полезна. По мнению Алекса, REST следует использовать в тех случаях, когда API может развиваться со временем, и вы не контролируете клиентов. Т.е. Я работаю в области EDI с множеством различных систем ERP. Наш HTTP-RPC API основан на прагаматических принципах и лучших практиках 5-8-летней давности, и в прошлом многие клиенты ERP не могли взаимодействовать с API из-за изменений в самом API или в некоторых зависимостях. Код теперь перегружен настраиваемой логикой, и его частично сложно поддерживать. Поскольку никто не будет платить за редизайн, он длится в текущем состоянии

Системы ERP обычно понимают разные форматы. Некоторые из них стандартизированы, как application/edifact, другие следуют специальной спецификации или диалекту XML / CSV. В настоящее время API определяет, какие форматы (и какие поля) получает клиент, когда было бы более выгодно, если бы клиент просто отправлял медиа-типы, которые он знает, как обрабатывать, а API возвращал бы их. Кроме того, отношения ссылок и сопровождающие их URI могут использоваться для направления клиентов к загрузке или загрузке документов и извлечения их состояния или создания архива за последний месяц.

Я пытаюсь прояснить то, что вы не можете предвидеть будущее, и даже внутренний API / инструмент может стать достоянием общественности через годы. Если вы находитесь в ситуации, когда у вас много клиентов, использующих ваш API (внутренний или внешний, на самом деле не имеет значения), и вам нужно что-то изменить, у вас есть в основном 3 варианта. Если у вас уже есть архитектура REST, все должно быть в порядке, иначе вам либо нужно как-то исправить изменения в вашем приложении, либо перепроектировать его с нуля. Вариант 2 (патч), однако, приводит либо к затруднению использования API, либо к затруднению поддержки кода (или того и другого) на протяжении многих лет.

@RomanVottner Действительно хороший разговор. Вы правы, если вы не будете проектировать с учетом гибкости и в конечном итоге будете нуждаться в такой гибкости, вам будет больно. С другой стороны, если вы добавите большую гибкость, и в конечном итоге она вам не понадобится, вам придется иметь дело с ненужными сложностями. Поскольку ни у кого из нас нет хрустального шара со 100% точностью, никто не может гарантировать, что вам не понадобится чрезвычайная гибкость (или что она вам понадобится, если на то пошло). В конце концов, вы должны сделать расчетное предположение (которое окажется правильным или неправильным :)) на основе имеющейся у вас (возможно, неполной) информации.