When discussing APIs between systems (on the business level) there are often two different point of views in our team: some people prefer a more - lets say - generic abstract approach, other a straight forward concrete approach.Example: the design of a simple person search API. the concrete version would be searchPerson(String name, boolean soundEx,              String firstName, boolean soundEx,              String dateOfBirth)People in favour of the concrete version say:the API is self-documentingit is easy to understandit is easy to validate (compiler or as a webservice: schema validation)KISSThe other group of people in our team would say That is just a list of search criteriasearchPerson(List<SearchCriteria> criteria)withSearchCritera {  String parameter,  String value,  Map<String, String> options}with possibly making parameter of some enumeration type.Proponents say:without changing the (declaration of) the API the implementation can change, e.g. adding more criteria or more options. Even without synchronizing such a change at deployment time.documentation is necessary even with the concrete variantschema validation is overrated, often you have to validate further, schema cannot handle all caseswe already have a similiar API with another system - reuseThe counter-argument islots of documentation about valid parameters and valid parameter combinationsmore communication effort because it's more difficult to understand for other teamsAre there any best practices? Literature?
API design: concrete vs. abstract approach - best practices?
api;web services;api design