API Portfolio Management, your missing link

Shopping around

When you stumble upon a potentially useful product in a catalogue or on a website, the first thing you typically do is to sniff it out. Either consciously or subconsciously, you look at the grammar, the typography, the coloring, and the quality of the photos. When you decide to start reading (that’s already a decision, mind you), you’ll look for well-structured information, easily readable, concise, clear and to-the-point. Then, assuming you’re still interested, you’ll have a look at the reviews, and see if you can find any information on the reliability of the supplier. For how long is the product already on the market? Is there a newer version available? What’s the price history? When, after your research, you’re sufficiently confident that you are not going to regret this purchase, you might decide to buy it.

Impulsive buyers

Oh, and then there are the impulsive buyers who are not so much into research. They are generally much easier to convince, if you just manage to excite them, and as long as you promise to reimburse them if they send your product back.

Now, why would it be any different if the product you’re looking for is offered as an API?

Think outside-in

Thinking outside-in is probably the best advice you get when searching for how to succeed with APIs and API best practices. Outside-in thinking is simply trying to understand the adoption process your subscribers will go through and make it as tempting as you can. This is how you can make that happen.

1. Reduce friction

Make it easy to discover your API. Publish it wherever you expect your potential subscribers to go. Make sure that you have a good ranking in search engines. Give it a catchy name. Blog about it, podcast about it and make sure you’re on YouTube, LinkedIn, Github, StackOverflow, Slack. And, most importantly, engage actively, share success stories, and keep the discussion going. Avoid the appearance of a deserted place.

Also make sure that your visitors can easily test your API. That’s often the first impression they’ll have. Share sample code, provide an SDK in their language of choice. Think of the proper localization of your API Developer Portal.

2. Map your customer journey

Embedding an API in your application can be an intimate affair. After all, you’re exposing your users to a feature you don’t control. That can be both exciting and frightening, when you think of it. And you probably should think about it.

Personas can be of great help in personifying typical actors in an API adoption journey. Try to imagine where they go to discover APIs, what it is that attracts them, and what puts them off. In today’s hyper polarized world, it’s all too easy to evoke negative feelings. Keeping a neutral stance may help your reach across ages, cultures and the political spectrum.

Build community

On the other hand, a well-targeted approach may strengthen your bond with your audience and can help to build a community. It does make a real difference if your persona is a college dropout that just started her first business, or a banker whose oldest just graduated for his MBA, or an information manager at a hospital who is expecting her second baby. A community of likeminded people is not always required for a successful API. But intentionally establishing your product-market combinations sure is.

And even if you target your API at your own colleagues, it pays to imagine walking in their shoes for a bit.

3. Be smart

You know that developers are critical when it comes to their applications. They will look carefully at your API definitions, and if they spot any potential bottlenecks, you’re up to resistance. So, as an example, do not simply define your paged results with an ?offset={nr} parameter, because they might sense this comes at a performance penalty and does not scale well to larger result sets. Instead, define ?start={ID}, which would even work predictably should someone bookmark or store the URI. It’s little things like this that make for a professional and trustworthy impression. If nothing else, your tone of voice should resonate with your target audience.

4. Be diligent

In all cases, you need to be consistent across your APIs and especially with different methods inside your API. So, spend some time on standardizing object definitions and their notation. Avoid having different RegEx’s for the same attribute in different APIs. An API must not expose in any way how your applications, services and data are structured.

You should also be careful about your error handling. Generating sensible return codes, with useful descriptions, without revealing information that you don’t want to share with anyone having malintent. Don’t be as silly as responding with an HTTP 200 {Created} after a PUT request, or a 405 {Not Acceptable}. That’s just confusing.

Units of measurement

Units of measurement are often an issue. If you plan to do business outside the US, don’t make the mistake of forcing your peculiar date format, temperature readings, miles and gallons upon the world. That wouldn’t be polite. Face it, you’re the exception here, not the standard.

It’s not that hard for an API Definition to express carefulness and robustness, rather than haphazardness. Use those regular expressions, limits and enumerations to define your APIs. There’s beauty to be found in a well-written API definition. It’ll make life easier for subscribers to use your API and for you to secure it. No excuse.

5. Plan for the long run

A successful API strategy requires a long-term commitment, aiming to engage with developers throughout the entire life cycle of your APIs. Like any part of the business, it does not stop with the end of business development. To be successful, you will need to organize API Management as a valuable business function. Don’t make the mistake that deploying the tool will bring you any lasting success. The tool is just a tool, you fool. This is true whether you want to monetize your APIs, or simply offer them as a value added service. It is still true if you expose your APIs only within your own organization.

API Portfolio Management

If you have more than one API, you will benefit from API Portfolio management. An API Portfolio Manager is a role responsible for managing the API backlog, governing API delivery and governing API operations. It’s the person who owns the API platform and the services it provides, who defines the API workflows, and drives the API developer engagement. In larger settings, the manager is supported by the API Portfolio management team, who act as the linking pin to API developers – producers as well as consumers. Typically, they guide the design of new APIs, safeguarding the design and naming guidelines. When APIs are monetized, the API Portfolio Manager will be the first one accountable for the revenues.

API Market Strategy

Most importantly, the API Portfolio Manager is responsible for the cohesion and consistency of their portfolio. An API Portfolio should be the result of an API market strategy, just as much as a product portfolio is the result of a product market strategy.

API Board and API Sponsor

The API Portfolio Manager reports to the API Board. This is a decisioning body, typically sourced with representatives from marketing, sales, business development and operations. It is here where the API Policies are established and the priorities for the API Backlog are decided. Finally, since you need a budget to run this operation, you need an API Sponsor. This should be your ambassador at the board level, who can clearly explain the business value and ensure the active involvement of high-ranking representatives in the API Board.

How about that impulsive buyer? Well, it certainly doesn’t hurt if your pricing plan includes a free trial period or a free basic service tier. After all, free is big business these days.

If you want more than just this piece of free advice, you’re always welcome. We’d love to engage for the long run.