How should I design WEB API in this case?

Question

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.

Eric Stein · Accepted Answer · 2016-03-01 16:19:25Z

1

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.

answered Mar 1, 2016 at 16:19

Eric Stein

13.8k3 gold badges39 silver badges51 bronze badges

Sign up to request clarification or add additional context in comments.

2 Comments

mko Over a year ago

A shared service layer is planned, that is why I specified provisional class names such as OrderClass, ProductClass, BuyerClass, SupplierClass (not actual names). That would be a service layer (using micro-service approach) and each API would only load API specific models using controller logic. So according to this, I am slightly shifting towards separate APIs.

mko Over a year ago

Furthermore shared service layer would retrieve some additional data in order to match multiple API needs, but that is a trade-off to avoid writing duplicate code..

Konstantin Chernov · Accepted Answer · 2016-03-02 03:03:21Z

1

There is a popular modern technology, called micro-services. And it obliges u to split the services you provide in a 'per resource' fashion. It allows you in future easily balance and scale your services, but requires additional overhead in terms of devops and infrastructure.

Considering routing, I didn't like both proposed by you variants. RESTful services are resource, not action centric. So in your case I would end up having order, product, buyer, supplier...(whatever the resources may be) web-api projects, each having simple semantics of operations upon the resource.

E.g.:

/api/orders {POST an order instance} 
/api/order {GET an order instance}
/api/order {PUT an existing instance}
...

If I got you wrong and the mentioned entities are not the resources in your case, then you need to redefine architecture, find those resources and build routing around them. Anyway, I advise not to stick to that SOAP style when web service turns into the bunch of poorly supportable/extensible methods GetCustomerCodeFromYetAnotherSetOfAttributes(...).

Considering the access to the service - I take it as completely different aspect of sdlc, so it has nothing to do with routing. So all of the operations should be invariants to the set of system user Roles.

answered Mar 2, 2016 at 3:03

Konstantin Chernov

1,9462 gold badges22 silver badges40 bronze badges

1 Comment

mko Over a year ago

I used terms action more as a an action inside a controller (asp.net web api), so this could be misleading. Nice tip for microservices. Microservices is a good pattern, here is a nice link about it microservices.io/patterns/microservices.html

Collectives™ on Stack Overflow

How should I design WEB API in this case?

2 Answers 2

2 Comments

1 Comment

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

2 Comments

1 Comment

Your Answer

Sign up or log in

Post as a guest

Related