Разработка REST API для вызовов функций

Question

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

Итак, я понимаю, что REST используется для доступа к ресурсам, а не для вызова функций.
Так что же такое рекомендации и лучший способ разработки API для ответственных за вызов функций.

Например, у меня будет API job/run, который будет возвращать PID задания, если задание было успешно выполнено. У меня также будет job/{pid} для доступа к информации о данной работе. и job/cancel/{pid} за прекращение указанной работы.

Answer 1

Ниже следует учитывать

1. Независимость от платформы. (Любой клиент должен иметь возможность вызывать API, независимо от того, как API реализован внутри).
2. Развитие службы. (Веб-API должен иметь возможность развиваться и добавлять функциональность независимо от клиентских приложений.)

Ресурс имеет идентификатор, который представляет собой URI, который уникальным образом идентифицирует этот ресурс. Например, URI для конкретного заказа клиента может быть:

Запрос: GET -> https://domain/orders/1 Ответ: JSON {"orderId": 1111, "сумма": 99,90 , "productId": 1, "количество": 1}

Наиболее распространенными операциями являются GET, POST, PUT, PATCH и DELETE.

• GET возвращает представление ресурса по указанному URI. Тело ответного сообщения содержит сведения о запрашиваемом ресурсе.

• POST создает новый ресурс по указанному URI. Тело сообщения запроса содержит подробности нового ресурса. Обратите внимание, что POST также можно использовать для запуска операций, которые фактически не создают ресурсы.

• PUT создает или заменяет ресурс по указанному URI. Тело сообщения запроса указывает ресурс, который будет создан или обновлен.
• PATCH выполняет частичное обновление ресурса. Тело запроса указывает набор изменений, которые должны применяться к ресурсу.
• DELETE удаляет ресурс по указанному URI.

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

Мы можем вернуть ответ с гиперссылками в виде пружинной загрузки с этой функцией

[Spring Boot:] https://spring.io/guides/gs/rest-hateoas/

https://domain/orders (лучше)

https://domain/create-order (избегать)

• Ресурс не обязательно должен быть основан на одном физическом элементе данных. Например, ресурс заказа может быть реализован внутри как несколько таблиц в реляционной базе данных, но представлен клиенту как единый объект. Избегайте создания API, которые просто отражают внутреннюю структуру базы данных.
• Клиент не должен подвергаться внутренней реализации.
• Не требовать, чтобы URI ресурсов были более сложными, чем (заказ / коллекция / элемент / детали)

Резюме

- Pagination Support  : /orders?limit=25&offset=50
- Error handing : 
- API Version (avoid as much as if possible)

См. Здесь https://www.openapis.org/blog/2017/03/01/openapi-spec-3-implementers-draft-released

Answer 2

Итак, каковы рекомендации и лучший способ разработать API для ответственных за вызов функций

1. Создать пользователя: POST / users
2. Удалить user: DELETE / users / 1
3. Получить всех пользователей: GET / users
4. Получить одного пользователя: GET / users / 1

To GET Record

Плохие проекты

GET /FetchUsers                  // To fetch all records
GET /getAllUsers/12              // To fetch specific records

Предпочитаемые проекты

GET /users                      //To fetch all records
GET /users/12                   // To fetch specific records

Для создания записи

Плохие дизайны

POST /createUsers                //To create users
GET  /createrecordforUsers      //To fetch all records

Предпочитаемые дизайны

POST /users                     //To create users records

Обновить запись

Плохие проекты

PUT  /updateUsersid               // To update user
POST /id/modifyuser              // To update users

Предпочитаемые проекты

PUT /users/:id                     // To update users

Удалить запись

Плохие проекты

DELETE /deleteuser/id              //To delete users
POST   /id/removeusers            //To delete users

Предпочитаемые проекты

DELETE /users/:id               // To delete users