Allowing Your API Portal To Meet Consumers Where They Are

I am thinking a lot about the API producer and consumer experience. I am thinking a lot about the push and pull of our local development environments and cloud services and platforms. It isn’t just the technical details of this, but also the business details. I am hyper aware of the business and politics that swirls around our API operations, and the business of moving the value we generate daily into the clouds. Unfortunately the API evolution of the last decade was on the coattails of the cloud and software as a service(SAS), which left a residue of API providers seeing that all roads should lead to their platforms, rather than meeting developers where they are.

As a developer I use VSCode. I know there are other IDE camps out there, but I am a VSCode user so I am going to explore this based upon what I need in my local development environment—because in 2024 if you are going to meet me where I live as an API consumer it is something that is Git enabled, CLI accessible, and providing value and guard rails in the VSCode IDE on my desktop. To help me better plan for the type of investment I’d like to see when it comes to how API providers can meet developers where they are, I’d like to see the following capabilities.

  • Search - I want to be able to search APIs by a rich set of properties and keywords.
  • Documentation - I want documentation presented to me within my IDE experience.
  • OpenAPI - Give me access to the OpenAPI behind the documentation for other uses.
  • Authentication - Make it dead simple for me to sign up, obtain keys, and authenticate.
  • Code - Allow me to generate SDKs or simple snippets for any of the available APIs.
  • Feedback Loop - Provide me with some form of feedback loop with an API ecosystem.

I have more I want in there, but that represents the essentials I’d like to see. I think API providers and even API service providers can have their API portals, but I think in 2024 your API portal should meet your consumers where they operate. Honestly, too. Not all roads lead to your cloud, but an actual usable suite of building blocks available at my fingertips in my IDE.

While there undoubtedly will be SaaS and cloud interfaces you will have to visit in this journey, I want the lionshare of my API onboarding, integration, and support experience to be in the comfort of my IDE. Forget what your investors told you about driving users to your platform, but deliver real value where they already live—the returns will be greater. The API portal experience across all of my public and private APIs should be built on the following existing cornerstones of my development experience.

  • Git - Put your APIs at my fingertips using Git, weaving it into my existing source control.
  • CLI - Give me a useful set of resources available at my fingertips in my CLI, via my IDE.
  • Extension(s) - Provide me with one or more API solutions as modular extensions I can use.

I get how API service provider startups feel about meeting developers where they are vs coming to their platform in the cloud to do things. I get it. I’ve lived it. There definitely should be a cloud experience, but you should also meet me at least halfway, if not more. I want your API discovery and onboarding to be simple and at my fingertips. I want your API alongside the many other APIs I use frequently or infrequently. I don’t want to have to go find your API, I want it to come to me.

Think of what I am talking about like an API portal projection into my IDE. Think of your APIs like channels that are available to me locally. Of course I will have to visit you somewhere along the journey, but don’t force me out of my comfort zone. Project your API into my world, and compliment the other APIs I am using, don’t just compete with them for my time. I don’t think there is too much rocket science going on here, and something I can shape my work on APIs.json to service. I think all of it is doable with a little bit of coding and APIs, but the one stickiest piece is the authentication dimension—it is of a scale that will be very difficult to crack due to the business and politics of API access.