api - 接受 POST 请求时添加单个或多个 API 端点？

Question

我计划构建多个服务端点，以便更新多个实体项。

/api/order(orderInfo) [httppost]
/api/orderChangeCurrency(orderCurrency) [httppost]
/api/orderChangeClientName(orderClientName) [httppost]

public class orderInfo()
{
public int orderID {get;set;}
public int orderType {get;set;}
}

public class orderCurrency()
{
public int orderID {get;set;}
public int currencyID {get;set;}
}

public class orderClientName()
{
public int orderID {get;set;}
public string firstName{get;set;}
public stringlastName{get;set;}
}

但我突然想到有一个端点可以完成所有这一切

/api/order(orderExtendedInfo) [httppost]

public class orderExtendedInfo()
{
public int orderID {get;set;}
public orderInfo? OrderInfo{get;set;}
public orderCurrency? OrderCurrency{get;set;}
public orderClientName? OrderClientName{get;set;}
}

在这种情况下，我会有一个业务逻辑，它会根据提供的信息(是否为空值)更新实体。

在这种特定情况下，是否有针对 API 端点的推荐做法或规则？

Answer 1

好吧，这是一个相当宽泛的问题，可能更适合 http://programmers.stackexchange.com但无论如何我都会放弃一些考虑。

首先，您的 API 设计应面向 API 的用户。如果您的 API 将是面向公众的 API，您可能会考虑 REST .它是一种广泛使用(和争论不休)的架构风格，许多程序员都习惯了这种风格。关于设计 RESTful API 的非常有用的建议列表可以是 found here

其次，您应该考虑 API 的易用性。以您的设计为例:消费者一个一个地更新实体是否合乎逻辑，或者一次更新一个或多个甚至所有实体是否更合乎逻辑？

第三，您必须考虑数据库事务。如果应在一个原子操作中更新所有实体，则您无法提供三个端点。

就我个人而言，我非常喜欢 REST，所以我很乐意为您的用例提供一个示例。

示例

首先让我介绍一个新实体:

public class OrderLine 
{
    public int Id {get;set;}
    public int OrderId {get;set;}
    public int ProductId {get;set;}
    public int Quantity {get;set;}
    public decimal Price {get;set;}
}

端点

POST /api/orders                  # creates a new order 
GET  /api/orders                  # gets all orders
GET  /api/orders/1                # gets order 1
POST /api/orders/1/orderlines     # creates a new order line for order 1.
GET  /api/orders/1/orderlines/1   # gets order line 1 of order 1
GET  /api/orderlines/{id}         # gets order line 1

如果您需要在单个操作中更新多个实体，您可以这样做:

为更新创建模型:

public class EditOrder
{
    public int orderID {get;set;}
    public int orderType {get;set;}
    public int currencyID {get;set;}
    public string firstName{get;set;}
    public string lastName{get;set;}
}

然后使用这个端点

PUT  /api/orders/1 

还有这个方法

public IHttpActionResult Put(int id, EditOrder editOrder)
{
    // retrieve current Order, OrderCurrency and OrderClient
    // update the entities 
    // save entities
}