Our team heavily discuss the issues how to handle code list in a web service definition. The design goal is to describe a provider API to query a system using various values. Some of them are catalogs resp. code lists. A catalog or code list is a set of key value pairs. There are different systems (at least 3) maintaining possibly different code lists. Each system should implement the provider API, whereas each system might have different code list for the same business entity eg. think of colors. One system know [(1,’red’),(2,’green’)] and another one knows [(1,’lightgreen’),(2,’darkgreen’),(3,’red’)] etc.
The access to the different provider API implementations will be encapsulated by a query service, but there is already one candidate which might use at least one provider API directly.
The current options to design the API discussed are:
- use an abstract code list in the interface definition: the web service interface defines a well known set of code list which are expected to be used for querying and returning data. Each API provider implementation has to mapped the request and response values from those abstract codelist to the system specific one.
- let the query component handle the code list: the encapsulating query service knows the code list set of each provider API implementation and takes care of mapping the input and output to the system specific code lists of the queried system.
- do not use code lists in the query definition at all: Just query code lists by a plain string and let the provider API implementation figure out the right value. This might lead to a loose of information and possibly many false positives, due to the fact that the input string could not be canonical mapped to a code list value (eg. green -> lightgreen or green -> darkgreen or both)
What are your experiences resp. solutions to such a problem? Could you give any recommendation?
I’ve gone with option 2 in the past, it’s least painful for the clients and for adding new consumers: you can componentize codes and meanings, so as to make another client’s addition painless, and in that sense this is the most useful way.
You’ll need every client to provide a dictionary, and maybe someone from each side to figure out equivalences whenever there’s fuzziness (which, to my experience, can be very often).
2
How do you map what the client might send you to the data the API requires?
I mean if I’ve understood the question correctly, its about providing a webservice that wraps several other APIs, eg a pizza delivery service that passes requests on to either Tony’s or John’s pizza parlours, only Tony does Deep Pan and Thin Crust, and John does Traditional, Stuffed Crust and Wholemeal.
You could implement a method that returns these options to the client, so they can ask “what choices do I have” and then can use these options in subsequent calls.