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

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

[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);
    }
}

Answer 2

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

首先，您的 API 设计应该面向 API 的用户。如果您的 API 将是面向 API 的 public，您可以考虑 REST. It's is a widely used (and debated) architectural style and lots of programmers are used to this style. A very useful list of recommendations on designing a RESTful API can be 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
}

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

Add a single or multiple API endpoints when accepting POST request?

api

api-design

asp.net-web-api