Nested micro APIs - design pattern and best practices

[#1]

Dear experts,

We are currently exploring the possibilities of micro services, like: /cities and /hotels. What I would like is a solution or design pattern for nesting API's, as an example: /cities/paris/hotels will give all the hotels in Paris. (or 3 nested apis: /cities/paris/hotels/all/prices to return all the prices from the hotels in paris).

I am not sure how this design pattern is called and if there are solutions / best practices for this, but if anyone can assist me in this question, any help is welcome.

[anilsr]

Dear @jan.willem.hennink ,

For your Apis, Please find my opinion.....

• Use Nouns Instead of Verbs. Keep Verbs out of your base path. You are on right path, /cities and /hotels is the best way to start with.
• Use Plurals Instead of Singulars. Again, You are on right path.
• /resource/identifier/resource is a good option to represent relationships between resources. I would suggest to use city id instead of city name because some times multiple cities share same name. /cities/{CITY_ID}/hotels

Coming to the question of /cities/paris/hotels/all/prices here is what i suggest ...

• You need to sweep complexity behind the '?'
• Generally /cities/{CITY_ID}/hotels lists all hotels so you don't need a base path cities/paris/hotels/all
• Coming to the prices of hotels, you can use API like /cities/{CITY_ID}/hotels?fields=hotels.price,hotels.name which lists hotels name and price information.

Please refer our E-Book Web API Design for API Design best practices.

Keep us posted if you have any queries after going through above e-book.

Cheers,

Anil Sagar

[#3]

This is a great topic for discussion. The client exposure /cities/{city.id}/hotels/{hotel.id|alias}/{propertySet} is a common one.

Typically I recommend not going deeper than 3 levels as the logical navigation starts to break down.

The interesting bit to me is the micro services angle you are mentioning. I would be curious if you are thinking of implementing the targets as micro services and using an orchestration pattern to build the relevant payload to the consuming client?

[#4]

Hi David, that was exactly what I was looking for!

I would like to have microservices in the backend, and do orchestration in Edge, but I am still looking for more info on that topic 😉 (if possible)

[ceber]

I have two opinions to share. Feel free to yell "pedant" at me and ignore both of them. 😉

1) Don't mix nice API design with deployment details. Microservices (in this pedant's opinion) are about deployment, not API design.

I do like the idea of following some of the DDD stuff and having nice clean services.. having a service as the sole technical authority for specific data elements is good stuff, IMO. Finding the bounds is the tricky bit, it seems to me.

2) I'd put the resource I'm going after at the top level of the url. E.g. if I want to get hotels, I

GET /hotels

I don't really understand enough about the domains to comment on the hierarchy. To me, cities and hotels are pretty unrelated. My default reaction is to use query params to filter results of a collection, rather than navigating a path hierarchy. BUT the details really matter. Queries break down when they get unwieldy. Above all, I'd argue good developer experience trumps slick/tricky design. But you can probably have both.

Maybe a linked data sort of approach would be valuable.

[#6]

Hi Carlos, thank you for your answer. The hotel example is just for illustration (ectually we are working on a complete different subject 😉 ). My question was more about: is it possible to have microservices in the backend (as small as possible) for instance for /prices and /availability etc. and use some sort of orchestration in edge so I would be able to "dynamically" create an api like /availability/4/prices to get all the prices where availability is at least 4.

The nice thing in my opinion would be that maintainability and optimilization in the backend would be really easy. Hope something like described above would exist.