In my current maintenance project, there is REST API resource URL like this:
/sites/<site id or site code>/buildings/<building id or building code>
In this endpoint URL, there are two parameters,
<site id or site code>
<building id or building code>
As the name indicates, these two parameters are ambiguous, say the value of the first parameter can be either site id or site code, the value of the second parameter can be either building id or building code. However, implicitly it means,
For instance, there is a building with 1 as building id and rake as building code, and it is located in the site with 5 as the site id and SF as the site code, then the following endpoint URL should retrieve the same result:
The implementation of such resource endpoint contains lots of
if conditions due to the ambiguity**. However, from the end-user’s aspect, this seems to be handy
My quesiton is whether such endpoint design is a good practice or a typical bad practice?
Go to Source
I would avoid this if it was up to me. It would be better practice and easier to maintain different endpoints that each does a specific purpose, rather than one that does several things. At least from my experience. Sure the code may be longer, perhaps a little repetitive. I’ll have more endpoints, but then the code will come out cleaner. There should be lesser if-else conditions too.
In case I want a functionality gone or temporarily disabled, that can be easily addressed because I only have that specific endpoint to target. Lesser chance of me altering an endpoint’s behavior unintentionally also.
Documentation will be easier to write. It won’t be ambiguous. I won’t have to write different scenarios and different combinations to instruct clients what to do and how to do it.
The next maintainers of the project should be able to understand the code faster.