为函数调用设计 REST API

Question

所以我正在构建一个REST APi，它将负责在特殊硬件上运行各种作业。

所以我明白 REST 用于访问资源而不是调用函数。
那么设计负责调用函数的 API 的建议和最佳方法是什么？

例如，我将有一个 apijob/run如果作业成功运行，它将返回作业的 PID。 我还将有一个用于访问有关给定作业的信息的job/{pid}。以及停止上述工作的job/cancel/{pid}。

Answer 1

那么设计

API 的建议和最佳方法是什么 负责调用函数

1. 创建用户：发布/用户
删除用户
2. ：删除/用户/1
3. 获取所有用户：GET/users
4. 获取一个用户：GET/users/1

获取记录

糟糕的设计

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

Answer 2

应考虑以下几点

1. 平台独立性 .(任何客户端都应该能够调用 API，无论 API 如何在内部实现(
2. 服务演进 .(Web API 应该能够独立于客户端应用程序发展和添加功能。

资源具有标识符，该标识符是唯一标识该资源的 URI。例如，特定客户订单的 URI 可能是：

请求 ： 获取 -> https://domain/orders/1 响应： 杰伦 {"orderId"：1111，"amount"：99.90，"productId"：1，"quantity"：1}

最常见的操作是 GET、POST、PUT、PATCH 和 DELETE。

• GET 检索指定 URI 处的资源表示形式。响应消息的正文包含所请求资源的详细信息。

• POST 在指定的 URI 处创建新资源。请求消息的正文提供新资源的详细信息。请注意，POST 还可用于触发实际上不会创建资源的操作。

• PUT 在指定的 URI 处创建或替换资源。请求消息的正文指定要创建或更新的资源。
• PATCH 执行资源的部分更新。请求正文指定要应用于资源的一组更改。
删除
• 删除指定 URI 处的资源。

REST API 使用无状态请求模型。HTTP 请求应该是独立的，并且可以按任何顺序发生，因此在请求之间保留瞬态信息是不可行的。

我们可以返回带有超媒体链接的响应，作为具有此功能的 spring 启动

[春季启动：] 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