Say you have a web service, which adds business logic on top of a data source. What each API of this service pretty much looks like is – given a set of constraints, give me the items from the data source that satisfy these constraints. You can say you get a "view" of the data source back from the API.
Now, over time you get asked to return different kinds of views over the data source. You have the option to either add new APIs for each "sufficiently distinct" view, or to switch gears and provide a getFooDataView() API, which takes a parameter that specifies what kind of view you want. You have several competing pressures for deciding which way to go:
- The existing big client of your service would prefer to be lazy, and not have to code up to new APIs when new views over the data are needed.
- But, some of your request parameters (constraints) only make sense for some views, and not for others – you'd have to make your API contract looser by saying "well if you want XYZ view, setting the "foo" parameter will have no effect", with the unfortunate side effect that you can't make "foo" a required parameter even if it is so for some of the views.
- It's becoming more and more the case that new clients want to leverage your service. You can't decide which would be more confusing to them – having to pick between different, but tighter-defined APIs, and one API where they have to know what combination of parameters really gives them what they want.
To distill this, when do you draw the line that something should be its own API as opposed to a variation of an existing API? Different people you have to work with have different views about what makes two client requests semantically distinct, so it can be hard to drive consensus about this matter. You also want to make sure that your service isn't prohibitively difficult for future clients to consume. What are some best practices arount making this kind of choice?
Best Answer
Personally I would lean towards smaller, tighter APIs. I don't think that it follows that having one one-size-fits-all API makes something simpler to use - in fact perhaps the converse since you need to figure out the right combination of loosely-typed "ju-ju" to get what you want whereas a tighter API can be made more self-explanatory. You are just hiding the complexity instead of making it explicit.
It's also likely that your one API will become ever more complex as it wraps more and more functionality, whereas the tighter APIs remain focussed and lean.
This smacks of the Interface Segregation Principle on a grander scale.
There are always other ways (such as good guidance) to help clients choose the right approach.