Плоские против вложенных API

Question

Я разрабатываю и API-схему для управления, скажем, комментариями и обсуждениями. я бы себе иметь enpoint

/discussions/:discussionId 

, который когда GET возвращает массив комментариев плюс некоторые мета-данные. Комментарии, возможно, может быть доступны индивидуально

/discussions/:discussionId/comments/:commentId 

То, что я хотел бы также, чтобы это искать комментарии, чтобы быть в состоянии ответить на такие вопросы, как: Сколько от комментариев пользователей XYZ осталось? Имея указать discussionId не представляется возможным, поэтому я полагаю, надо иметь

/comments/:commentId 

, на котором вы можете ?q=XYZ, например. Можно было бы тогда также извлечь все комментарии, принадлежащие к обсуждению путем, например,

/comments/:commentId?discussion=discussionId 

и выше конечной точки

/discussions/:discussionId/comments/:commentId 

становится излишним. В конце концов, все, кажется, тяготеют к плоской структуре API. Однако в дикой природе я вижу много таких вложенных конечных точек.

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

Answer 1

Что мне нравится делать, это разоблачение информации с использованием принципов CQS. Если вы отделяете запросы от команд, вы можете выставлять специальные контракты, которые возвращают данные так, как они используются вашими прецедентами.

В основном это означает, что в вашем случае вы могли бы:

/discussions 

... который отображает до обработчика запросов FindDiscussions(), который дает вам список лучших дискуссий х и основные свойства (название , автор, количество комментариев и т. д.).

Чтобы получить подробную информацию о дискуссии:

/discussions/{discussionId} 

... который отображает до обработчика запросов FindDiscussionDetails(), который дает вам все подробности дискуссии, вместе с верхними х комментариями.

Чтобы получить другие комментарии:

/comments/{discussionId}?{other parameters} 

... который отображает до обработчика запросов FindComments(), который дает вам все комментарии (отсортированные по дате и т.д.).

Чтобы получить общее количество комментариев пользователя, это информация, которую вы можете сохранить с пользователем (Денормализованным) и получить его любит:

/users/{userId} 

... который отображает до обработчика запросов FindUserDetails (), который дает вам информацию о пользователе, а также общее количество комментариев. Не нужно вычислять это на лету, просто получите денормализованное значение в быстрый запрос.

То же самое относится к командам.

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

Да, читайте here.