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?