Search code examples
apiasp.net-web-apiapi-design

How should I design WEB API in this case?

I am designing a new API and I am in doubt should it be a single API or should it be divided to end user type.

For example I have the following classes

OrderClass
ProductClass
BuyerClass
SupplierClass

And want to create API that would allow buyers and suppliers to access it

Do I create a single API such as 

CompanyAPI that uses access tokens (defining roles and types)
/api/order/orderAction [allowed for buyers, suppliers]
/api/order/orderAction2 [allowed for buyers] 
/api/order/orderAction3 [allowed for suppliers] 
/api/buyer/buyerAction [allowed for buyers, suppliers]
/api/supplier/supplierAction [allowed for suppliers]
/api/product/productAction [allowed for buyers, suppliers]

or two APIs that are designed to fit Buyers OR Supplier needs?

BuyersAPI
/BuyersAPI/order/orderAction
/BuyersAPI/order/orderAction2
/BuyersAPI/buyer/buyerAction
/BuyersAPI/product/productAction 
SuppliersAPI
/SuppliersAPI/order/orderAction
/SuppliersAPI/order/orderAction3 
/SuppliersAPI/supplier/supplierAction 
/SuppliersAPI/product/productAction

One of the main reason to use two APIs is documentation, and it seems logical that I wouldn't want buyer to see what information is supplier getting (at least a structure of it).

On the other hand having two APIs would mean that some parts would/could be repeated/duplicated.

Solution

  • The big question is going to be overlap. If 95% of your API is shared and 5% varies by client type, that's probably one API. If it's 5% shared and 95% by client, then you have multiple APIs. In your shoes, given the RPC nature of your API, I'd be inclined to lean heavily towards separate APIs. They tend to grow faster than RESTful APIs and I expect the divergent needs of the multiple client types will drive that growth.

    I assume you're using an annotation-based documentation provider, which is why you're considering the documentation as part of the tradeoff. If you take the multiple API route, I'd strongly suggest very thin API layers which depend on either a shared service layer, or a custom service layer for each client type and a common service layer for shared functions. That should help minimize duplication.

    You could, in theory, do the same trick for the API layer - define it across multiple projects, with the common endpoints in a shared project. That might get Exciting if endpoints need to move from common into the client projects or vice-versa, so make sure you research thoroughly before you try this.