How to handle REST API paths when related resources belong to different microservices?

Question

I have two microservices:

• UserService, which defines paths such as /users, /users/:id;
• MessageService, which defines paths such as /messages, /messages/:id.

Also, each message in MessageService has an attribute user_id which references a user in UserService.

Now, lets say I want to list all messages of a given user. Right now I can think of the following approaches:

1. A path such as /users/:id/messages seems like the best approach if I want to follow the best REST API practices. However, it seems to me that I couldn't define such path inside MessageService because I would be tight-coupling it to UserService. I believe paths starting with /users should belong to UserService only.
2. /messages?user_id=:id so I could use the existing /messages path and add a filter by attribute (user_id). Not sure if a good practice.
3. Put an API gateway in front of the microservices and create a proxy from /users/:id/messages to /messages?user_id=:id. This allows clients to use the most REST-friendly path while keeping the microservices loosely coupled.

Which of these approaches would be the most appropriate?

Answer 1

There's no right or wrong answer for this question. IMO, it depends on whether messages are stand-alone resources or are part of a user resource in your domain logic.

If messages always belong to a single user, then you could view the user's messages as a sub-resource or a hierarchical division in the collection of messages and I would probably prefer the first URI scheme. In this case, I would probably go with a path like /user/:id/messages instead of the plural 'users'. Or put the user id behind the messages like: /messages/user/:id

If messages are an entity by themselves within your domain or can belong to multiple users (like email messages) it would make more sense to filter messages using a query string scheme.

Answer 2

If you already designed your micro service where users and messages are two different domain/micro services, then your best bet will be designing a edge service that combines the two services and provide what client needs. For example, the service could be

/messages_by_user/:id

Remember a micro service will primarily provide CRUD operation on a domain resource, but client will need more than just CRUD operations on a resource and in that case you should always consider creating edge services to facilitate clients need.

If you haven't implemented the services yet then I would suggest putting both users and messages into the same micro service and consider user as a sub-resource of messages. In that case all the bellow paths are valid.

/messages
/messages/:id
/message/:id/users
/messages/user/:id

When you design a micro service, you need to strike the balance of what makes more sense. Although in theory every resource and their CRUD operation should have a separate micro service, but practically you can combine few related resources and make them a sub-resource as long as you are not compromising scalability, performance of the service.