Grouping and nesting of REST APIs

Question

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":

1. Front-end calls REST API: PUT .../user
2. 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?

Answer 1

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.

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

Answer 2

The answer depends on some assumptions not described in the question: 1. You don't have the liberty to change the vendor or internal API 2. The grouping has to be performed in a single transaction. i.e., how strict should the API be against vendor API failures. What happens if 1 vendor fails and the rest succeeds. Do we still consider this a success or initiate a rollback API (e.g., delete user)

Based on the assumptions I will not design my API based on the implementation, such as having a vendor API etc.., But purely based on functionality, i.e., who are users of the new API and their requirements.