The “Ugly Duckling” API syndrome

As an advisor and a digital strategist, part of my role is to talk to customers about their APIs, IoTs, and their overall digital strategy. After conversations with a lot of them, one thing stands out: Almost everyone thinks their API is awesome. While a good portion of them are very impressive, and some are moderate to good, I do see a bunch of ugly ones too. However, if you are a producer — whether it is a movie, a baby, or an API – it will be hard for you to realize, admit, and come to terms with your “Ugly Ducklings.” Obviously, the amount of sweat and tears that went into your initiative causes you to look at your APIs through beer goggles, which makes them look good in your eyes, even if the APIs are mediocre.

If you are an API producer, and your API fails to meet the following expectations, you might have an ugly duckling. Keep in mind, just because you are great in some of these areas it doesn’t compensate for if you suck in other areas. My good friend John Musser (@johnmusser) had a great presentation at IBM Interconnect conference API track on this very topic, “Top 10 Reasons Your Developers Hate Your API”. You might want to check it out.

Duckling #1: Build it, they will come

There is a common belief that when you build your APIs, your users will come and find it magically. This is a major reason why APIs fail adoption in the first place.

First, you need to identify who your users are, and you need to make sure they know you have APIs for them. Good communication and promotion is mandated. Think almost like you are establishing a new brand and the user group needs to find out. API discovery is the first step in leading your users to a self-serve digital revolution. If that fails, all else will fail. If it is an internal API, consider listing them in an internal API portal where the internal users will find it. If it is an open/public API for anyone to find, consider listing it on public directories in addition to your own API portal. ProgrammableWeb, IBM API Harmony, Public APIs by Mashape, and APIs.io by Kin are all good places. There is whole other category when you are doing B2B APIs – partner APIs. While these APIs are external it is not open for anyone to register and use. You have to either control the visibility of those APIs to public developers or expose those APIs to select groups by “invitation only.”

Don’t forget to promote your APIs via other mechanisms as well – such as lunch and learn meetings, promotional emails, on-site show and tell on how to use your APIs, etc. and of course using the god-like power of hackathons. Not all hackathons are done in person; you can do virtual hackathons or a coordinated hackathon with other brands to reduce the cost and to improve traffic. I wouldn’t do justice to hackathons by trying to explain the power in a paragraph, but I will write a blog on it soon.

Duckling #2: Your documentation sucks

The whole idea of providing APIs and a digital platform is so the developers can find, learn, use, and promote your APIs in a self-serving manner and to provide mass education without the need for additional cost or resources. Even if you built a great API, if your documentation, samples, and usage patterns are not explained well, then your APIs will still cause confusion. The developers will get frustrated soon and move on to the next API.

To that end, you also need tools for your developers to automate the process of documentation. We all know how much developers hate the paperwork or like to sit and read white papers.

There are about a dozen tools that might be able to help you in that front. The most popular ones I have seen are Swagger, RAML, and Blueprint –Swagger seems to be the most popular one among them. While I am not recommending a specific solution, you need to consider using such tools to make your documentation better and up to date.

Strangely enough, I see a lot of API producers still provide “white papers” on how to use their APIs. In my mind, they missed the mark with the developer community completely.

Duckling #3,4,5: Your APIs are unreliable (QOS, Scalability, Volume Controls)

After you build your great APIs, and provide good and easy-to-understand documentation, the developers put their heart into it to build something magical. Now the stakes are even higher. They are spending their time trying to side with you and to promote your solution and your brand to the world. This is a very crucial step in which not only you provide all the help they need to build their apps, but you also need to:

1. Be careful with version control. The last thing you need is breaking things as you continue to crank newer versions. Even worse, don’t provide details about what changed between versions. A service offered by my buddy Bruno Pedro can help there. Read more details at https://www.apichangelog.com/. If you are offering a public API, you could have them listed in their directory, which can notify the developers of all the changes between revisions. When you do introduce a new version of an existing API, make sure you have the option to easily migrate your existing subscribers to the new version and a way to communicate the change via the API portal.
2. Monitor API failure so you can be aware of your API uptime. If you are the last one to find out that your API is down, you have a lot to lose. For every digital developer that departs with a bad experience, there will be another 100 who will find out about this from that developer in a nasty way. There are some great solutions out there to help you monitor your APIs constantly from different geo locations. Runscope, APImetrics, and APIScience are all good tools that can constantly monitor your APIs, from a global perspective, to alert when your API is down or provide performance metrics on response times, which will help you to analyze any issues.
3. Watch for APIs going down because there are no limit controls. I have seen time after time APIs go down because of unauthorized or greedy overuse. If you don’t have rate limiting controls in place, some rookie (unintentional) or a greedy developer (intentional) will build an app that will use your API to death. There is also a possibility that your APIs are so popular that almost every developer built an app for it, and almost every user uses it, putting tons of useful traffic, but still crashing your API. At a minimum, you need to have controls to put specific user groups in specific plans. You also need to provide a self-service option for the developer/user to choose and upgrade the plans without a need to call someone.

Duckling #6: Your APIs are unsecure and untrusted

When you decide to build API-based digital compute model, the APIs become the central point of interaction with the back-end systems. Just because your API is a public API doesn’t necessarily mean it has to be an open API. Not only will you be clueless on who is using your API, and how much, it is very dangerous to have people access your APIs and the back-end systems/data with very limited or no controls around your API.

Various options are available to secure your APIs — Client Key (aka API Key), IP address, user ID/password, and geo location based controls — to identify, authenticate, and authorize the user before they can use your API. For the advanced types, things like OAuth, secure messaging, and secure transport can all be options. In addition, user limitation controls based on the usage and/or based on the geo location, date/time of the use should also be taken into consideration for usage limit restrictions. This in turn can provide so much visibility into the usage, which can allow for your business teams to negotiate with the user from a monetization perspective. After all, you built an API to get revenue out of that.

Duckling #7: Lacks true self-service

There seems to be some confusion about what truly is a self-service model. Some tend to think just by putting your APIs out there on a developer portal you can call it a self-service model. A true self-service API model must have the following, at a minimum:

1. As soon as you create an API, there should be an option for your API providers to publish it to a place or places of your choice, where it can be discovered by the appropriate user group.
2. As soon as a developer discovers an API, they should be able to build apps based on that right way. In other words, those APIs should be ready to be called for that user right way. You shouldn’t make your user wait between the hours of 8 am- 2 pm like the cable companies before they can start using the APIs after they requested access to the APIs.
3. For the above, there should be appropriate security, access and data governance policies setup and enforced from their first contact.
4. When a user figures out that they are ready to liberate you should provide tools for them to choose appropriate plans for them to upgrade their usage plans to match their business models.
5. A business user should be able to identify, upsell, modify, and create custom plans for the users without the need to get the IT involved.

Finally, but most importantly, in case of misuse, lost API keys/credentials or loss of relationship it should be fairly easy to revoke/extend access to the API without involving the IT.

Duckling #8: Lacks freedom of choice

This is an interesting situation. I keep hearing from every provider about “going to where the developers/users are” and “providing them with APIs in a manner they can consume”. Yet, very often I see the provider put restrictions on where the APIs can be published, where micro-services can be run, or how to enforce the traffic.

For example, in a conversation with a large enterprise customer who was publishing all their APIs on the cloud, it became clear they would have chosen to publish APIs not only in different locations, but different portals. However, they were restricted because of the API management provider they chose. As a result, they were forcing their entire user community to go to a specific location to find the API set against their preference.

What I recommend to customers is to have one authoritative source for creation of APIs and for cataloging purposes. When you publish, you get to choose which portal and which developer groups can see the API collections, and be able to choose what plans are allowed for them. For example, while it might be appropriate to choose an unlimited plan for the internal users, the same may not be appropriate for external developers.

Essentially, the access characteristics of an API such as rate limits, security characteristics, etc. can be grouped together in a “plan” and you can publish appropriate plans for specific groups of users in specific portals. This restricts the others not only from seeing the APIs that they are not allowed to see, but also doesn’t give them usage options and models that they are not entitled to. For example, my external portal may show “Location API” with just two plans – Bronze and Gold with appropriate rate limits, but my internal portal might have a plan called Platinum or even Unlimited with much higher or no rate limit targeting specific user groups. In addition, I also advise them to restrict not just for the whole API, but even for specific methods. For example, if your PUT is much slower and consumes a lot more resources, then you can enforce a limit at a much lower level than GET.

You can also choose the option of subscriptions requiring approval. You don’t want the external developers to randomly bump themselves up without an oversight. At the same time, you should let internal developers use it as they please without someone approving them as an option.

Duckling #9: You don’t play nice with others.

The reason why APIs are becoming so popular is because you don’t have to build everything on your own. You can combine your great ideas with the world’s great ideas to bring your ideas to life quickly and safely in the digital economy. What this means is that not only can you provide options to work with APIs in adjacent space, but also provide a set of APIs that can be used in conjunction with your API, so the users can build a better app. My colleague @ARGlick had been writing on a bunch of industry APIs and thought leadership articles for a while now. You might want to check them out here –https://developer.ibm.com/apimanagement/author/glick/. He covers ONG, Electronics, Healthcare, Education, Finance, etc. Not only does he cover the compelling drivers for each industry, but also some great sample public APIs, which can either give you an idea or an opportunity to co-publish them on your API portals.

[Image Courtesy: Shoeboxblog.com]

Unfortunately, if you let your ugly ducklings continue the course, it is not going to fix itself – it will turn into an “Ugly Duck.” We at IBM help our customers to fix the ugly duckling syndrome to make a beautiful swan out of your APIs. To that end, we have an API strategy session on July 15 right here in my backyard in the Boston area where we will be discussing this and more. Please register here buff.ly/1e3P7IC if you would like to attend or reach out to me at @AndyThurai so we can set up a free API strategy consulting session to analyze, advise, and help you with your APIs.

Come join us for free to get all your “duckies” in a row. If you can’t join this event, reach out to me @AndyThurai to find out the schedule so you can attend one of them. It will be worth your while.