Documenting types used in services

Arseni Mourzenko
Founder and lead developer
October 16, 2019
Tags: rant 33 microservices 2 short 48

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:

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:

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: