I've been hired to document a family of SOAP APIs. I've got a couple of "Why are they doing that?" questions.
Yes, these really are questions for the engineers who developed the APIs I'm documenting. I've tried to get answers from them, though, and have had no luck. Either they don't know the answers -- they're just doing what someone taught them to do -- are they know, but they don't know how to explain.
I hope that experienced designers of SOAP APIs can answer these questions for me, either by pointing out some design pattern that I don't recognize, or by informing me that the design really doesn't make sense, and needs to be changed.
Required vs optional elements
Like almost any API, these contain both required and optional elements in both requests and responses. But many elements which are in fact required (a request will always fail if they're absent) are formally optional (the WSDL defines them as minOccurs="0").
These are not cases where elements are required in some use cases but not others -- something that the WSDL could not represent. I'm speaking of cases where an element is always required.
For example, the <request> element in every operation's request is defined as optional, although a request with no <request> element would be meaningless. The <response> element in every operation's response is defined as optional, although a response with no <response> element would be useless.
For another example, the response messages are defined with many parts like this (the tag names are made-up):
This construction poses a problem: there are two ways for a response to convey the fact "there are no flavors." The <flavors> element may be absent, or it may present but contain zero <flavor> elements. If I am writing code to process this response, which type of response should I check for? Or must I check for both? If I must check for both, how can I test the code when there's no apparent way to control which type of response the API gives in any particular case?
This situation reminds me of orthogonality violations in a relational database. The types of problems that it poses for the API user seem to be similar, and similarly nasty. (By the way, if the situation I've described has an accepted name, I'd like to know what it is. I've been calling it a violation of "encoding orthogonality.")
I consider the situation a nightmare that has got to be eliminated or explained. So far the engineers seem to consider it too trivial to require answers... or perhaps too overwhelming to be answerable. In any case, they are not offering enlightenment.
The incredible nillable optional element
The other problem is related; actually it's a complication of the first one. Some elements are both optional and nillable. In the example above, for example, <flavor> could be defined as minOccurs="0" maxOccurs="unbounded" nillable="true". Now there are three ways to say "there are no flavors": <flavors> may be absent, <flavors> may contain zero <flavor> elements, or <flavors> may contain one <flavor> element whose value is NULL. Why?
Yes, these really are questions for the engineers who developed the APIs I'm documenting. I've tried to get answers from them, though, and have had no luck. Either they don't know the answers -- they're just doing what someone taught them to do -- are they know, but they don't know how to explain.
I hope that experienced designers of SOAP APIs can answer these questions for me, either by pointing out some design pattern that I don't recognize, or by informing me that the design really doesn't make sense, and needs to be changed.
Required vs optional elements
Like almost any API, these contain both required and optional elements in both requests and responses. But many elements which are in fact required (a request will always fail if they're absent) are formally optional (the WSDL defines them as minOccurs="0").
These are not cases where elements are required in some use cases but not others -- something that the WSDL could not represent. I'm speaking of cases where an element is always required.
For example, the <request> element in every operation's request is defined as optional, although a request with no <request> element would be meaningless. The <response> element in every operation's response is defined as optional, although a response with no <response> element would be useless.
For another example, the response messages are defined with many parts like this (the tag names are made-up):
<response> minOccurs="0"<flavors> minOccurs="0"<flavor>string</flavor> minOccurs="0" maxOccurs="unbounded"</flavors></response>
This construction poses a problem: there are two ways for a response to convey the fact "there are no flavors." The <flavors> element may be absent, or it may present but contain zero <flavor> elements. If I am writing code to process this response, which type of response should I check for? Or must I check for both? If I must check for both, how can I test the code when there's no apparent way to control which type of response the API gives in any particular case?
This situation reminds me of orthogonality violations in a relational database. The types of problems that it poses for the API user seem to be similar, and similarly nasty. (By the way, if the situation I've described has an accepted name, I'd like to know what it is. I've been calling it a violation of "encoding orthogonality.")
I consider the situation a nightmare that has got to be eliminated or explained. So far the engineers seem to consider it too trivial to require answers... or perhaps too overwhelming to be answerable. In any case, they are not offering enlightenment.
The incredible nillable optional element
The other problem is related; actually it's a complication of the first one. Some elements are both optional and nillable. In the example above, for example, <flavor> could be defined as minOccurs="0" maxOccurs="unbounded" nillable="true". Now there are three ways to say "there are no flavors": <flavors> may be absent, <flavors> may contain zero <flavor> elements, or <flavors> may contain one <flavor> element whose value is NULL. Why?