An API Wishlist

Posted

Sunset in Killiney Hill Park, Dublin

I’m a big believer in buy over build, especially for enterprises that are smaller or where technology is not the product. A natural consequence of such a strategy is that the team are going to spend a lot of time integrating different systems to meet the needs of the business.

While we can integrate via file transfer, the preferred method is always API. Hence, we spend a lot of time looking at and working with APIs. So what separates the great APIs from the also rans? Here’s my shopping list.

Fantastic Documentation

You would think this one would be obvious but it sill amazes me the number of vendors who lock their docuumentation behind a login page, or e-mail it to you in a PDF file (is it current? who knows!)

This one is easy: the best documentation is in HTML, indexed by Google and configuration managed alongside the source code. Bonus points if you’re using something like Swagger. Such tools increase machine readability and permit auto generation of calling stubs. Also nice to have:

Machine to Machine and Delegated Authentication Models

Sometimes you’re making a call to an API on behalf of the user who has authorized your code via something like oAuth. Other times, it’s truly a machine to machine invocation: for example, pulling FX rates into an ERP is for all the users, not just one.

The best APIs acknowledge this and permit secure authentication models for one or both without the caller resorting to potentially insecure fake ‘service’ accounts. For machine to machine think JWT and/or client certificates.

Available client (preferably Open Source) SDKs

Even the best APIs take client code to handle authentication, marshall data and form queries. Libraries like PnP Powershell give users a leg up and let them get going quicker.

If you’re the API provider it’s not really viable to provide APIs in every potential language. This is where the community can help: if you are relaxed about your API surface being visible to Google, it’s easy for others to create the SDKs for the languages they care about. For example, PSZoom is not ‘official’ yet does a good job covering much of the Zoom API.

Predicatable, consistent, design

There are good standards for many aspects of an API

If you use these, you’re adopting well worn pathways that developers know. Stray from these and you force additional cognitive burden on them as they struggle to learn your ‘special’ way. Bonus points if the standards are used consistently across the API surface. Microsoft’s Graph API is a great example here

Easy to test

Most developers I know start in Postman or SoapUI. If they can easily start testing against your API in one of these tools it greatly increases their productivity. If their code doesn’t work but Postman does, they know where the issue is. If your API is so byzantine that it can’t be exercised using a standard tool, you’ve made it much harder to chase down bugs.

Easy to light up/not an add on

I do not want to talk to a sales person, nor support, to get access to your API. Let me login to your product, click the register app button and start from there. I should neither have to explain why I want access, nor have to justify myself. You’re worried that I might ‘overwhealm’ your service? That’s your problem of inadequate throttling, not mine.

The API should not be an add-on SKU or extra charge: once a customer has integrated with your API the likelihood that they will churn is greatly reduced. Why would you want to do anything that gets in the way of that?

Fine grained access control

The best APIs are not a permissions free-for-all. The client application is granted the permissions it needs, but nothing further. Azure AD is excellent in this regard: when I register an application, I grant it the exact APIs it needs and nothing further. This greatly reduces the blast radius of any credential leak.

Published connectors

Finally, connectors. These are somewhat similar to SDKs, in that it’s difficult to support every possible permutation. However, if your API is supported by connectors for things like Anypoint Exchange or Power Platform/Logic Apps. Don’t half ass this though. There is nothing worse that a published connector that hasn’t been updated in forever. The Power Platform Workday connector is a sad example of this: being only saved by the ‘get out of jail’ SOAP Operation. Better to not have a connector than a half implemented one that lets everyone down.

Summing up

Building a great API doesn’t need to be hard, it just takes a bit of forethought and really clear vision and goals for what the API is for. Stick to known patterns, make it easy to consume and you’ll have happy, sticky, productive customers for a long time.