接受 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
}

Answer 2

我认为你应该像这样在业务层实现一个控制器动作方法和三个方法

[HttpPost]
[Route("api/order")]
public async Task<IHttpActionResult> SubmitOrder(OrderExtendedInfo info)
{
    var bl = new BusinessLayer();
    if(info.orderInfo.HasValue)
    {
        bl.UpdateOrderInfo(orderInfo);
    }
    if(info.orderCurrency.HasValue)
    {
        bl.UpdateOrderCurrency(orderCurrency);
    }
    if(info.orderClientName.HasValue)
    {
        bl.UpdateOrderClientName(orderClientName);
    }
}