Rest – Grouping and nesting of REST APIs

apiArchitecturerest

My question is around best practice of aggregating or grouping REST APIs.
I have a scenario where there are many different vendors, data sources, etc. and I think grouping REST APIs would make a lot of sense to keep the system maintainable.

I have many scenarios where there will be a single API call triggering many other (similar) API calls to create the same entity in another system. For example for an example entity "user":

Front-end calls REST API: PUT …/user
What I envision is that the code listening on the above API will then make multiple REST PUT calls to let's say vendorA/user, vendorB/user, vendorC/user, internalSystemA/user, internalSystemB/user, etc.

Like this:

                                                            +-------------------+              
+--------+                   PUT     +-----------+  CALL    | Vendor A API      |              
|        |                 +-------> | user      +--------> |                   |              
|        |                 |         +-----------+          +-------------------+              
|        |                 |                                                                   
| Front  | PUT    +--------++  PUT   +-----------+  INSERT  +-------------------+              
| End    +------> | user    +------> | user      +--------> | Internal System   |              
|        |        +--------++        +-----------+          +-------------------+              
|        |                 |                                                                   
|        |                 |         +-----------+  CALL    +-------------------+              
|        |                 +-------> | user      +--------> | Vendor B API      |              
+--------+                   PUT     +-----------+          |                   |              
                                                            +-------------------+             
                 +                                 +                                           
                 +---------------------------------+                                           
                         Internal REST APIs

Note that the example entity doesn't have to be "user", there are many entities that are going to have a counterpart on the vendor APIs.

The vendors in this scenario provide different functionality. But there might be multiple vendors who provide the same functionality (and the user will chose the vendor he wishes to use). For simplicity let's say example functionalities are

Procurement,
Human Resources,
Management,
Payment.

What is the best practice to group and nest REST APIs in such a scenario?
Is it a good idea to group them by vendor or should they be grouped functional or by business entity? How would the URL look like?

Best Answer

I'd go for more logical grouping,

Imagine a system where hotel bookings are performed, where there are 2 different hotel reservation API (A and B) and one payment gateway.

system diagram

In this sort of situation few best practices to follow would be,

Wrap any third party APIs into one of services (whenever third party API changes only the wrapper service is need to be changed), in this example single interface can be used for both A and B services.
Create higher level service facades based on functionality (in this case one facade for searching and one for booking)
This also will help to troubleshoot, because if there is an error it would be easy to track entire process since it happens in a single facade method

Related Solutions

Rest – Conceptual mismatch between DDD Application Services and REST API

I've had the same problem and "solved" it by modelling REST resources differently, e.g.:

/users/1  (contains basic user attributes) 
/users/1/email 
/users/1/activation 
/users/1/address

So I've basically split the larger, complex resource into several smaller ones. Each of these contain somewhat cohesive group of attributes of the original resource which is expected to be processed together.

Each operation on these resources is atomic, even though it may be implemented using several service methods - at least in Spring/Java EE it's not a problem to create larger transaction from several methods which were originally intended to have their own transaction (using REQUIRED transaction propagation). You often still need to do extra validation for this special resource, but it's still quite manageable since the attributes are (supposed to be) cohesive.

This is also good for HATEOAS approach, because your more fine-grained resources convey more information on what you can do with them (instead of having this logic on both client and server because it can't be easily represented in resources).

It's not perfect of course - if UIs is not modelled with these resources in mind (especially data-oriented UIs), it can create some problems - e.g. UI presents big form of all attributes of given resources (and its subresources) and allows you to edit them all and save them at once - this creates illusion of atomicity even though client must call several resource operations (which are themselves atomic but the whole sequence is not atomic).

Also, this split of resources is sometimes not easy or obvious. I do this mainly on resources with complex behaviors/life cycles to manage its complexity.

Rest APIs – mobile specific challenges

The API being designed follows the Rest style of resources-centric URI and CRUD operations mapped to HTTP verbs.

This is your problem right here.

You have limited your resources to (I'm assuming) the models in your database. As such it is taking ages to load all these resources because your server has no concept of resources that don't have a representation in the database.

For example might have

www.example.com/books/482094
www.example.com/books/582045
www.example.com/books/427454
www.example.com/books/319343

that all have to be loaded to get my library

This isn't a problem with RESTful design, this is actual a REST anti-pattern. There is absolutely nothing in REST that says our resources must have a one to one mapping with anything else in your system, including database models.

The solution is to create more resources that better match what you want to load. If you have 5 resources that always end up together create a new resource that contains the info for those 5 resources.

What you should have is something like this

www.example.com/users/334/my_library

which just loads all the books for that user. "my_library" isn't a model in your database, but it is a resource. The server creates it based on models in the database but there is no 1-to-1 mapping and the server has flexibility to create this resource without changing your DB model.

You might also have

www.example.com/users/334/favioured_books
www.example.com/users/334/books_ordered_last_week
www.example.com/users/334/wishlist

none of which have to exist as model in your database or domain space.

There is a wide spread misconception that this is the wrong thing to do because frameworks like Rails taught people to map resources in a 1-to-1 fashion to models in the domain space which map again 1-to-1 with database rows. This is not necessary nor is it recommended.

Resources should be numerous, cheap and lightweight. It should be easy to create them, and they should be abstracted from your domain model. If you find you need a new one you just make a new one. If you have problems doing that it is your frameworks fault not a fault with REST.

Now the big caveat with that of course is whether your framework allows you to do this. Frameworks like Rails and Django which have taken the course to map 1-to-1 in order to "save you time" make it hard to do this. But that is a flaw with the frameworks, not with RESTful design.

Here is Jim Webber discussing this is more detail (including a few digs at Rails as well!)

https://yow.eventer.com/yow-2011-1004/domain-driven-design-for-restful-systems-by-jim-webber-1047

Best Answer

Related Solutions

Rest – Conceptual mismatch between DDD Application Services and REST API

Rest APIs – mobile specific challenges

Related Topic