Documenting types used in services

SOA and mi­croser­vices trends caused the fren­zy where every­one start­ed to ex­pose every­thing as a ser­vice. Large and small com­pa­nies want­ed to re­place big sys­tems of com­po­nents with rel­a­tive­ly un­clear in­ter­faces be­tween them by big­ger sys­tems of ser­vices with what should have been clear, easy to use in­ter­faces. Un­for­tu­nate­ly, for most, the prac­tice was a bit... un­ex­pect­ed.

For de­vel­op­ers who have to con­sume any in-house ser­vices, it shouldn't be a sur­prise that the qual­i­ty of those ser­vices range from poor to ter­ri­fy­ing. Made by peo­ple who were nev­er taught to cre­ate ser­vices and who, it seems, nev­er even con­sumed the ones cre­at­ed by Twilio, Ama­zon or Google, those mon­sters are not a huge step for­ward com­pared to the old as­sem­blies of com­po­nents. There is even one par­tic­u­lar as­pect where they are even more ter­ri­ble: their lev­el of hazi­ness. The cause: the de­vel­op­ers don't think too much about the types be­ing used, be­cause they as­sume it will work, mag­i­cal­ly.

For ex­am­ple, imag­ine that an HTTP ser­vice is ask­ing for a num­ber as one of the in­puts, or spec­i­fy­ing that the out­put con­tains a num­ber. De­vel­op­ers didn't make any doc­u­men­ta­tion, since they pub­lished Swag­ger, and in their heads, the pres­ence of Swag­ger some­how frees the de­vel­op­ers from the ne­ces­si­ty of doc­u­ment­ing stuff. So the Swag­ger tells that there is a num­ber you should put or that there is a num­ber which would be sent back. Great. Does it tell you:

• What is the min­i­mum and max­i­mum val­ue?
• What would be the pre­ci­sion, in­clud­ing the max­i­mum pre­ci­sion?
• What are the round­ing rules be­ing ap­plied, if ap­plic­a­ble?
• Is the for­mat which uses ex­po­nents, such as 2.5e6, sup­port­ed?
• Is there a way to spec­i­fy that the val­ue doesn't ex­ist?
• Is NaN a valid en­try?
• Is there a sup­port for neg­a­tive zero?

Those are, how­ev­er, very ba­sic and sim­ple ques­tions, and de­pend­ing on the an­swers, there may be im­por­tant con­se­quences. Re­gard­ing the pre­ci­sion, for in­stance, it would be use­ful to know whether 1.234567890123456789 and 1.23456789012345678 or 1.23456789012345679 would be con­sid­ered as the same num­ber or not, be­cause de­pend­ing on that, I should be par­tic­u­lar­ly care­ful when writ­ing the code which uses the ser­vice. It is im­por­tant when I'm us­ing the same lan­guage, but it be­comes even more im­por­tant when I'm in­ter­act­ing through a text-based pro­to­col with a ser­vice which may be de­vel­oped in a very dif­fer­ent lan­guage than my con­sumer ap­pli­ca­tion, and which could fol­low slight­ly dif­fer­ent rules re­gard­ing the rep­re­sen­ta­tion of a num­ber.

Or take strings. Wouldn't it be use­ful to know:

• The max­i­mum al­lowed length?
• The en­cod­ing?
• The list of de­nied char­ac­ters, if any?
• The pos­si­bil­i­ty to use \x00 in­side the string?
• The rep­re­sen­ta­tion of the ab­sence of a val­ue?
• The con­se­quences of start­ing or end­ing the string by a space?

When de­vel­op­ers don't think about those de­tails, the ser­vices and ap­pli­ca­tions they cre­ate are frag­ile. In fact, doc­u­ment­ing types al­lows both the pro­duc­er of a ser­vice and its con­sumers to think about the edge cas­es that should be test­ed. If those cas­es are not doc­u­ment­ed, it of­ten in­di­cates that no­body thought about them in the first place when cre­at­ing a ser­vice, and a string a bit too long or a NaN as in­put could eas­i­ly break it. When con­sumers ac­cept us­ing those ser­vices, it of­ten means they didn't test those cas­es ei­ther, and are hop­ing for the best—not the best ap­proach for mak­ing re­li­able soft­ware.

Why is it so? Es­sen­tial­ly, for two rea­sons:

• The un­will­ing­ness of de­vel­op­ers to think about the edge cas­es. Un­der­stand­able, al­though it's what they are paid for, isn't it?
• The in­com­pe­tence of the de­vel­op­ers. In fact, most sim­ply don't know the lan­guage well enough to un­der­stand the caveats of a giv­en type and the mech­a­nisms in play when re­ceiv­ing in­puts or se­ri­al­iz­ing the re­sponse. Un­for­tu­nate­ly for them, if they ac­tive­ly avoid think­ing about the edge cas­es, they will nev­er learn the specifics of the lan­guage they use in the first place.