API-план, как определить конечные точки для коллекции и отдельного объекта с похожими точками

У меня есть конечная точка, которая возвращает набор контактов, и это конечная точка: .../api/v1/contact. Теперь у меня есть еще одна конечная точка, которая будет возвращать один контакт, и это конечная точка: .../api/v1/contact?Id=

68 ## Contacts Endpoint [/v1/api/Contact]
69 ### Retrieve All Contacts [GET]

154 ## Contact Endpoint [v1/api/Contact?id=HashID]
155 ### Get single contact [GET]

Теперь я получил следующие две ошибки:

неожиданный блок заголовка, ожидаемая группа, ресурс или определение действия, например. '# Group', '# []' или '#' Строка: 154• API Blueprint

действие с методом GET, уже определенным для ресурса '/v1/api/Contact' Строка: 155• API Blueprint


apiblueprint
person Wasyster    schedule 15.04.2017    source источник

Ответы (1)


arrow_upward
0
arrow_downward

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

Однако я бы постарался избежать того, чтобы одна и та же конечная точка выполняла несколько действий (возвращала контакт или все контакты), поэтому вам может понадобиться определить две конечные точки:

/v1/api/Contacts

/v1/api/Contact/:id (в любом случае с параметром запроса все в порядке)

person Vincenzo    schedule 27.07.2017