How to maintain cohesion in my REST API?

Question

I have two features of a REST API Specialists and Services. An expert can perform various services.

I needed to list all services that have at least one associate expert.

get services/? criteria get experts/? criteria

How could I make this request without leaving the api too confusing and maintaining cohesion?

Answer 1

Based on some documentation (even the Microsoft Webapi), we have a "REST standard" to keep the API organized and "beautiful".

your domain api/servicos

GET List => api/servicos

GET Single => api/servicos/{ID} or api/servicos?id={ID}

POST Create => api/servicos

PUT Update => api/servicos/{ID} or api/servicos?id={ID}

DELETE Delete => api/servicos/{ID} or api/servicos?id={ID}

This is the basics that the documentation shows, so we have a standard to keep the API more "cohesive".

In your case, to keep the API cohesive and self-explanatory, nothing better than opting for simple (KIS - Keep It Simple)

then we would have: GET List => api/servicos/com-especialista.

I believe that any people who access your API documentation, by tapping the URL name, will already have a good sense of what it will return as a response.

I recommend taking a look at Swagger, it will help you a lot to document your API, and save you a lot of time, hehehe.

https://swagger.io/