REST API Design - Single General Endpoint or Many Specific endpoints

Question

This is a relatively subjective question, but I want to get other people's opinion nonetheless

I am designing a REST Api that will be accessed by internal systems (a couple of clients apps at most).

In general the API needs to update parameters of different car brands. Each car brand has around 20 properties, some of which are shared between all car brands, and some specific for each brand.

I am wondering what is a better approach to the design for the endpoints of this API.

1. Whether I should use a single endpoint, that takes in a string - that is a JSON of all the properties of the car brand, along with an ID of the car brand.

2. Or should I provide a separate endpoint per car brand, that has a body with the exact properties necessary for that car brand.

So in the first approach I have a single endpoint that has a string parameter that I expect to be a JSON with all necessary values

PUT /api/v1/carBrands/

Whereas in the second approach in the second scenario I have an endpoint per type of car brand, and each endpoint has a typed dto object representing all the values it needs.

PUT /api/v1/carBrand/1
PUT /api/v1/carBrand/2
.
.
.
PUT /api/v1/carBrand/n

The first approach seems to save a lot of repetitive code - afterall the only difference is the set of parameters. However, since this accepts an arbitrary string, there is no way for the enduser to know what he should pass - he will need someone to tell it to him and/or read from documentation.

The second approach is a lot more readable, and any one can fill in the data, since they know what it is. But it involves mostly replicating the same code around 20 times.

Its really hard for me to pick an option, since both approaches have their drawbacks. How should I judge whats the better option

Answer 1

I am wondering what is a better approach to the design for the endpoints of this API.

Based on your examples, it looks as though you are asking about resource design, and in particular whether you should use one large resource, or a family of smaller ones.

REST doesn't answer that question... not directly, anyway. What REST does do is identify that caching granularity is at the resource level. If there are two pieces of information, and you want the invalidation of one to also invalidate the other, then those pieces of information should be part of the same resource, which is to say they should be accessed using the same URI.

If that's not what you want, then you should probably be leaning toward using separated resources.

I wouldn't necessarily expect that making edits to Ford should force the invalidation of my local copy of Ferrari, so that suggests that I may want to treat them as two different resources, rather than two sub-resources.

Compare

/api/v1/carBrands#Ford
/api/v1/carBrands#Ferrari

with

/api/v1/carBrands/Ford
/api/v1/carBrands/Ferrari

In the former case, I've got one resource in my cache (/api/v1/carBrands); any changes I make to it invalidate the entire resource. In the latter case, I've got two resources cached; changing one ignores the other.

It's not wrong to use one or the other; both are fine, and have plenty of history. They make different trade offs, one or the other may be a better fit for the problem you are trying to solve today.