Keith Casey will SPOIL you with a better-than-average tech talk.

Yesterday, I attended the annual Austin Code Camp which the Austin .NET Users Group (ADNUG) puts on. The best talk I saw, which I will write of first, was "SPOIL your users with Great Helper Libraries" by D. Keith Casey, formerly of Twilio, now of Clarify (makes audio and video clips searchable and SEO-friendly by crafting copy from uploaded media with voice recognition software), and author of a technology agnostic book on API design called "A Practical Approach to API Design." API designs themselves should be done with care and be more than just exposing CRUD functionality over an API in one afternoon of coding as APIs may be hard to work with if they are not designed well. The status codes need to make sense (more on that later) ...and so on. Mr. Casey spoke of a scenario in which an API was sketched on a Monday, followed by the JSON going back and forth being sketched on a Tuesday, and then on the Wednesday and Thursday a simulator was built out. That's more like it! Something further to take seriously and not to shortchange are the SDKs which exposition how to use the API you have hopefully built with obsessive compulsive hand washing love. As a guideline for good practices in doing so, Keith has invented his own acronym, SPOIL which stands for:

• Succinct
• Purposeful
• Open Source
• Idiomatic
• Logical

 
 

S is for succinct, briefly and clearly expressed, precise but concise. An example should just be a few lines of code. At Clarify, it takes just two lines of code to do anything and three is too many. Users will commonly copy and paste code examples from SDKs and then hammer then into shape in their apps and if an example is twenty-two lines of code long instead of two there is a clearly a greater chance of a misconfiguration. What if the developer fails to see the couple of key spots to alter in a twenty-two line mess? When writing examples try to cover the scenarios which cover eighty percent of use cases instead of ninety-nine. It is important that an example be readable not confusing. P is for purposeful, having or showing resolve. It is usually an afterthought to throw together an API and that's bad. If someone is using your companies' product and they feel rage, then you're doing it wrong. Keith recommends writing all of the documentation first before development. O is for Open Source, universal access and a free license. Don't compile your SDKs into binaries that others cannot change up. The libraries should be free to use and modify. Keith once tweeted a request for links to bad API designs and one of the many responses he got asked him to sign a nondisclosure agreement first. Not cool. Your copyright should never come off your product. You should just simply offer a use agreement in which parties cannot pretend that you endorse them and cannot remove your copyright. Otherwise the public should be allowed to manhandle and mangle your SDKs at will in the name of understanding your API. At the end of the talk I asked a question about the next point, I for Idiomatic, and Keith suggested that amongst the things one might do to get an SDK in a language that is out of the norm and sweet spot for its authors shipshape is to request that the community around that other language you've never written code in give you feedback and critiques. This scared me as it requires being really vulnerable, but as I sit here and type this up I realize that the Python community, for example, (I've never written Python) should be able to critique my Python SDK anyways if I offer one and I really do things the right way and make the SDK open source. The scary, I'm-going-to-let-you-have-a-laugh-at-my-poor-code aspect of being vulnerable in offering SDKs across more languages than you personally truly know is probably just a part of the SDK game that I've got to get used to. I should just remind myself that others doing the same thing are facing the same challenge. I is for Idiomatic. An SDK should not be akin to a language it is not intended for. One should not look at Keith's C# SDK and recoil at how it is PHP-flavored and goofy if considered in a C# context. Swagger will give you JSON representations of your API and APImatic can turn around and generate SDKs from the Swagger objects in seven different languages, but some of what it spits out is just goofy. In circling back to the question I asked, which more or less was "What should I do if I'm the wrong person to write an SDK in a language I don't know?" I was told that it might indeed be wise to bring in outside consultants. When I started to stress over the likelihood of getting budget approved for as much another gentleman in the audience suggested it might be smart to pick a customer who uses the other language and get them to audit what is crafted and offer suggestions and feedback. L is for Logical, clear and sound reasoning, consistent and predictable. To me this last point felt like it had less to do with the SDKs than the API design itself. The status codes that your API gives back should make sense. Beyond that, they shouldn't do silly things like returning 403 Forbidden when attempting to delete something one is not permissioned to delete as this sort of reveals that the thing to be deleted does exist to someone who doesn't need to be told anything about it. 404 Not Found would be better in this circumstance. If you are not being deliberate in your reasoning for what you return and it's not a part of your documentation, you're going to drive your users up the wall. Different coders will do different things in building out an API if there isn't a plan and some standards. Don't let your API become a hodgepodge of madness. Do wireframes and user process diagrams. Write stories. Other things said of interest were:

• The way authentication works at Clarify is that a bearer-token is given to a user when he/she first creates an account and there is an expectation that such a token will be included whenever the user uses the API every time.
• I/ODOCS is something akin to Swagger. It is an alternative.
• Brain Wolfe of Volusion (and also Habanero Software, LLC) was at the table I sat at and he said that Volusion offers a sister endpoint for each of its API endpoints which just gives metadata on the first API endpoint. The metadata is crafted by C# reflection using an in-house tool.