I've been working on a REST API for a car repair shop management app, and I've hit a design snag. Here are the routes I have so far:
- `/api/clients`
- `/api/cars`
- `/api/car`
- `/api/jobs-histories` (for storing car repair histories)
My frontend developer requested that I create an endpoint to handle sending a client and a car in one request, and also retrieving a client with their car in one call. I want to do this in a RESTful way, but I'm unsure of the best approach.
I've brainstormed a few options:
1. Incorporate the car object into the `/clients` route, allowing both to be created in one call. However, this feels wrong since `/clients` should technically only create a client.
2. Introduce a new route, perhaps `/api/registration`, but that seems misleading, and I'd prefer not to create multiple endpoints for every possible data representation.
3. Use a verb in the endpoint like `/api/client/with-car`, but that seems to go against REST principles.
4. Create a more generic actions endpoint like `/api/actions` and nest the client-car actions within it, but that doesn't feel RESTful either.
After considering the feedback, I think it might be acceptable to create both in one request since the client is an aggregate root owning the car. I could also add an `include` query parameter to make the API more flexible. What do you all think?
5 Answers
Have you thought about using a GraphQL setup? It’s designed for exactly this kind of scenario. You can fetch related resources in one go without creating a bunch of special endpoints. Though, I get if that feels like overkill for your current setup.
Honestly, I see where your frontend dev is coming from. Sending two requests can introduce lag and be a hassle for users. If reducing latency is crucial, merging the operations might be the way to go. Using the first option where you send a client along with the car seems reasonable since the client is like a root entity here.
Yeah, exactly! It’s about making things smoother for the frontend. Plus, if you keep it flexible with the `include` parameter, that’s a win for both client and server.
I would suggest separating the requests if you can, especially since they might evolve separately over time. If the user needs to add a car without a client (or vice versa), let them do that without forcing a specific pathway through the API.
That’s a fair point! Maintaining the integrity of the operations is crucial. I worry about the potential for inconsistent states, but sticking with two separate requests might be a safer bet.
A more practical way could be adjusting your current structure. Like, have a client endpoint and then nested endpoints for ‘client with car’ and ‘client without car’. This allows flexibility without clogging your API design with endpoint bloat. Just ensure your data relationships in the backend are sound, so querying for a client and their cars is straightforward.
Yeah, that’s a good point! Keeping a clean and understandable API while reflecting the underlying database structure is key.
You really shouldn't be constrained to strict REST norms when developing such a system. If your API needs to reflect actual business logic and relationships, allowing a client and car to link together makes sense. Just be careful not to create too many special cases that aren't needed.
True! GraphQL could be an option, but I wonder if it might complicate things more than I'd like right now. I appreciate the suggestion, though!