Схема именования URI для API с виртуальными ресурсами + логический параметр

Question

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

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

Я начал настраивать сингл GET который существует следующим образом (возвращает объект "result" в формате JSON).

api.example.com/query?string=foo&otherparam=bar

Однако я не уверен, следует ли это передовым методам.

Проблема 1

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

Таким образом, вопрос 1 будет: api.example.com/result лучшее имя конечной точки?

Проблема 2

Это относится к семантическим URL. Рассмотрим следующий пример из Википедии: Семантические URL-адреса.

Несемантический URL:
http://example.com/products?category=12&pid=25

Семантический URL:
http://example.com/products/12/25

Семантический URL адаптирован для моего случая:
http://api.example.com/result/foo/bar

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

Итак, вопрос 2 на самом деле: если ответ на вопрос 1 "да", каким должен быть семантизованный URL в моем случае:

1. http://api.example.com/results/foo/bar?
2. http://api.example.com/results/foo?otherparam=bar?

(results Я думаю, это должно быть множественное число, так как оно описывает список возможных результатов.)

Answer 1

Нет, я не думаю result хорошее имя конечной точки Кроме того, result супер универсальный и ничего не значит.

Когда я разрабатываю API, конечными точками могут быть ресурсы или действия над ресурсами

• https://api.example.com/accounts/1/authorize - ресурс здесь accounts и действие authorize
• https://api.example.com/search - ресурсом будет вся платформа, поэтому любой ресурс может быть возвращен, а действие search

Так есть ли какой-либо тип ресурса, который вы можете прикрепить к query действие? Или кажется, что этот тип конечной точки подойдет вам лучше?

https://api.example.com/logic/run