5 must haves if you're building APIs

Building APIs is fundamentally hard because it's an unusual UI paradigm. A bit like designing command line tools you aren't interacting with things like a mobile app. Getting users to that happy path is super important!1. Docs matter. Never underestimate the importance of building great docs. A good tactic is to have a friend or colleague interact with the docs in front of you. You'll see the challenges in the user journey.A great positive example is Stripe. Stripes docs are super focused and help the developer get started fast.Stripe is a great concrete example. Here is a bad example. I couldn't tell what this tooling is for. It's still nevertheless better than most github applications.2. Names matter. It's very important to map the names of your endpoints and sdk functions to things the user understands. Many Apis use the technical terms not the accessible terms.Speech Sync for example we when we built our real time speech endpoint opted for speech and sync. Based on user research. User research is an under appreciated way to learn. An example from the mobile industry might be using pstn rather than phone number 3. Error messages matter. You have an opportunity to help users get back onto the happy path with your error messages. This allows users to thrive. A bad example is anything opaque. Such as error messages that you might have received with early operating systems. A particularly bad example is if you patronise the user. Here has a great list. Another set of bad examples are AWS lambda. See here for an explanation hereGood examples include the likes of twilio I've always found that their error codes are helpful with debugging.4. Users are impatient. You need to tell them why your api matters asap and what its for. Related to docshttps://docs.checkhq.com/docs/quickstart is a great positive example. It's for payroll.Lots of bad examples out there! Too many to mention 5. Constantly look for the opportunities to streamline workflows and simplify. In PyMC3 and API.audio at various points we had cumbersome workflows any time we simplified thus it helped users get to producing value faster. We added github.com/aflorithmic/apiaudio-python#orch.. to dramatically simplify the first time to your first request.Another example from a few years ago is this refactoring of one of PyMC3 functionality - This this is an in-depth discussion of some of the design decisions in a biggish refactoring.A bad example is an XML based API, XML isn’t the standard for payload, or poor documentation. Salesforce is a great example - https://rishidhar.me/salesforce-and-the-return-of-the-soap-api/ (so ugly and so hard to use) Peadar helped build PyMC3 a Bayesian Statistics framework for ML in Python and now works on www.api.audio the simplest way for developers to create audio experiences and add to their apps. He’s fascinated by developer experience, and in his free time enjoys craft beer and watching Rugby.