Наименование конечной точки API REST для форматов данных - PullRequest
Новая
       13

Наименование конечной точки API REST для форматов данных

0 голосов
/ 18 февраля 2019

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

Пример API

  • / api / Applications - получает список всех приложений
  • / api / Applications/ {applicationId} - получает конкретные данные приложения
  • / api / application / {applicationId} / themes - получает все темы для конкретного приложения

Проблема

Пара приложений-потребителей могут требовать доставки данных в разных форматах - например, список, дерево и, возможно, разный уровень детализации / детализации.Как лучше всего представить это в RESTful API?

Возможные решения

Различные имена конечных точек .Не нравится это, потому что это выглядит грязно, смешивая конечные точки и типы данных:

  • / api / application / {applicationId} / themes
  • / api / application / {applicationId} /подробные темы
  • / api / application / {applicationId} / topicHierarchy

Подпуть .Не нравится это, поскольку кажется, что нарушает соглашения об именах RESTful.Я ожидал бы / themes / {topicId}:

  • / api / Applications / {applicationId} / themes / details
  • / api / application / {applicationId} / themes / list
  • / api / application / {applicationId} / themes / иерархия

Строка запроса .Это кажется лучшим решением, но я все еще не удовлетворен им на 100%:

  • / api / application / {applicationId} / themes? Detail = обзор
  • / api /Applications / {applicationId} / themes? format = list
  • / api / application / {applicationId} / themes? format = tree

Хотелось бы услышать некоторые из ваших мыслей!Спасибо!

Ответы [ 2 ]

0 голосов
/ 18 февраля 2019

Если разные «форматы» имеют принципиально разные данные, у меня лично были бы разные конечные точки.

Если «форматы» представляют одни и те же данные, но они просто организованы по-разному, стандартным способом решения этой проблемы являетсячерез заголовок accept.

Например, если у вас есть конечная точка /topics, которая поддерживает формат csv и два типа форматов json, я бы использовал: 

Accept: text/csv
Accept: application/vnd.ross.list+json
Accept: application/vnd.ross.hierarchy+json
0 голосов
/ 18 февраля 2019

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

  • GET: / api / Applications- список приложений
  • GET: / api / Applications / {id} - получить одно приложение
  • POST: / api / apps - создать отдельное приложение
  • PUT: / api/ Applications - редактировать отдельное приложение
  • PATCH: / api / Applications - Редактировать отдельное приложение
  • УДАЛИТЬ: / api / application - Удалить отдельное приложение

Насколько далекокак что-то вроде тем, я бы переместил его в свою конечную точку

  • GET: / api / themes? application = {applicationId} - список тем для конкретного приложения

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

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

  • / api / appications / {id} .json
  • /api / appications / {id}? format = json
  • / api / appications / {id} с Accept: application/json в заголовке запроса.
...