API Evangelist Profiling: Profilng A Specific API

Over the last nine years I have worked to regularly refine my approach to profiling APIs. As my view of the API landscape continues to shift, I make sure that I invest in evolving my approach to profiling APIs, while also making sure I implement it against the growing number of APIs I discover across the landscape. My approach to profiling APIs helps me document the companies who are putting APIs to work across almost every business sector, as well as the technical details of the APIs they are making available. This work is all about profiling APIs, but the primary value behind doing it for me is all about educating myself around how companies are approaching their API efforts. API profiling is how I develop my understanding and expertise as the API Evangelist, and establish a process that represents the core of my brand, and is something I regularly look to shape as part of my overall narrative.

Profiling Entities

Every API I profile first involves profiling the company, organization, institution, or government agency behind it, working to better understand not just the API, but also the motivations and operations behind it. I find understanding the entity behind an API is just as important as the API itself, documenting the operational aspects of how they provide APIs, and how they generally conduct business online using web technologies. There are some distinct categories of information I am looking for when profiling the entities behind each API, helping me better document what is going on.

Basics Information

To begin with, I’m looking for the basic information that describes what a company does, providing me with a very precise overview of what is going on that I can use when listing or displaying an entity as part of my work.

• Name - Record a clear and accurate name for each entity.
• Description - Record / write a short, concise description for each entity.
• Image - Record a single logo or other image representing an entity.
  

You’d be surprised how hard it is to just get a clear concise name, description, and image for an entity. For some it is easy, but for others it can take a couple minutes of work to track down each part, and then potentially edit and clean up for better presentation.

Essential Building Blocks

After getting the basic information for an entity I also want to document the resources they put in place to support their API operations, helping me better understand if they are investing in the right places when it comes to operating a successful API program--hopefully emulating other leading API providers when it comes to delivering what API consumers expect.

• Developer - Having a dedicated developer portal for their API.
• Authentication - Providing an authentication page for their API.
• Blog w / Atom - Publishing a blog with feed dedicate to the API.
• Change Log - Documenting the changes made for an API.
• Code - Providing a page dedicated to snippets, libraries, and SDKs.
• Documentation - Publishing documentation for all APIs.
• FAQ - Providing a simple FAQ page for API consumers.
• Getting Started - Offering an overview of how to get started.
• Issues - Documenting the known issues for an API.
• Login - Providing a self-service loving for an API.
• Pricing - Publishing a page with all the API pricing available.
• Privacy - Providing a privacy policy for the API platform.
• Rate Limits - Clearly documenting what the API rate limits are.
• Road Map - Sharing what the future holds for an API.
• Sandbox - Providing a sandbox for API consumers.
• Security - Publishing a page that provides an overview of security.
• Sign Up - Offering a self-service signup for an API.
• Status - Publishing a status page with API monitoring information.
• Support - Providing an organized support effort around APIs.
• Terms of Services - Publishing the terms of service for an API.

I consider these to be the essential building blocks for any public or partner API. I’ve expanded this list over the years to help provide a baseline for where API providers should begin with their API efforts. These building blocks contribute to the overall health, stability, and reliability of an API, delivering what is needed to properly on-board, support, and engage with API consumers, which is required for any API community to survive and thrive.

External Links

Adding to the essential building blocks that should be present for any API, there are a handful of other external links that I look for when profiling APIs, helping me understand the scope of things behind an API. These links provide a kind of heartbeat when it comes to the operations around an API, helping them stay engaged with consumers, but also provide an important set of signals to look at when understanding if an API has lost a champion, or maybe support and funding from within—setting the stage for an API going away, or at least being unreliable.

• GitHub - Record their GitHub organization or user.
• Twitter - Record their Twitter account.
• LinkedIn - Record their LinkedIn page or user.
• Facebook - Record their Facebook page or user.
• Crunchbase - Record their Crunchbase account.
• YouTube - Record their YouTube account.

While not all APIs will possess these external links, those that do demonstrate that they are serious about attracting the attention of new users, and using these channels to stay actively engaged with their community. Providing a very informative way for analysts like me to stay in tune with what is going on while also measuring the heartbeat (or lack of) coming out of each API.

Additional Building Blocks

Beyond the essential building blocks there are a handful of other elements I am looking for when profiling APIs. Ultimately, I have an exhaustive list of about 200 elements I am looking for, but these additional building blocks represent the most common ones I am looking for to further evaluate the scope of API operations, and the overall resources an entity is putting into delivering their API infrastructure. Further helping me understand how engaged each API provider is when it comes to doing the hard work of making their APIs reliable and stable enough to grow a rich community of developers.

• Branding - Identifying if there is a branding page for the entity.
• Case Studies - Tracking on any case studies published for an API.
• Command Line Interface - Noting if there is a CLI available for an API.
• Contact Form - Documenting if there is a contact form present.
• Errors - Identifying if they document their errors alongside other essentials.
• Forum - Tracking on if they have a public or private forum for an API.
• Integrations - Documenting if there is an integrations page present.
• Licensing - Cataloging any of the licensing I noticed used by a platform.
• Marketplace - Acknowledging the presence of an API, application, or other marketplace.
• News - Documenting the presence of a news section beyond just a blog.
• Partners - Tracking on an API platform’s partner program if there is one.
• Plugins - Understanding if there are plugin or extension opportunities.
• Press - Documenting the presence of a press section beyond news and blogs.
• SDK - Tracking on any formal SDKs that are present with each platform.
• Service Level Agreement - Noting the presence of an SLA for each API.
• Tutorials - Documenting the tutorials that are provided for an API.
• Webhooks - Cataloging the web hooks that are provided alongside APIs.
• Webinars - Documenting the webinars that are provided for an API.

These additional building blocks further help me round of the overall impact each API is making, helping me understand the amount of expertise and resources they are bringing to the table. The number of building blocks present demonstrate how organized each API provider is, helping set the stage for how successful their efforts will, or will not be. These building blocks represents the common patterns I see in play across almost all of the leading API providers out there today.

Profile APIs

After understanding the entities behind each API, and defining the operations that support them, I work to profile each of the APIs that exist, getting down the technical details of what is actually being delivered. Helping me understand the patterns being used by each API provider, providing rich details about the value, which I find tends to be a more honest look at what is happening behind the marketing and fluff.

• info - Provide as much information about the API.
• host - Provide a host, or variables describing host.
• basePath - Document the basePath for the API.
• paths - Detail the paths that are made available.
• parameters - Document tag the parameters in use.
• body - Ensuring each request body is well defined.
• schema - Provide schema for all requests and responses.
• properties - Document the properties for each object.

This level of detail helps me understand the nature of each HTTP 1.1 API, allowing me to craft API definitions, and transcend each providers own API documentation. I’m working to evolve this profiling beyond just HTTP 1.1 APIs, and expanding to HTTP/2, TCP, and other approaches for delivering APIs—for now I am just working to stay afloat in defining the technical details for the flood of APIs I’m coming across as part of my API discovery automation.

API Access

After understanding the technical details of an API I like to identify each API provider’s approach to API access. The motivations behind each provider will be slightly different, and I have a handful of ways in which I identify the access levels involved with each API, which can significantly impact what you can do with an API, providing a pretty good snapshot the overall business goals of a company, and whether or not you want to integrating an API into your applications.

• Open - The API is publicly available and doesn’t require any keys to access.
• Self-Service - You can sign up and obtain API key without talking to anyone.
• Request Access - You have to request access before you will get an API key.
• Pay as You Go - An API employs a pay as you go model for access to resources.
• Tiers - An API has a variety of access tiers which define what success looks like.

API access tells me a lot about the motivations of the entity behind an API. Not all APIs are created equal and I find that the business and politics of API operations often trumps the technical details of what is going on. API access often changes over time, and is something that has to be regularly updated to keep in sync with the changing business strategy of the entities operating each API that I am profiling.

Types of API

Next, I’m looking at what type of API it is. I’d say most of the APIs I’m looking at are simply web or HTTP APIs, but increasingly I’m interested in understanding what the other types of APIs exist. It can be very difficult to appropriately describe each type of API, but these are the areas I’m currently using to separate out the different types of APIs I’m profiling as part of my work.

• Web - APIs that are accessible via HTTP 1.1, HTTP/2 or HTTP/3.
• TCP - APIs that are accessible via TCP, going beyond the web.
• Open Source - An API that can be deployed by anyone.
• Browser - Browser APIs that are a common standard.
• Language - Programming language specific API infrastructure.
• Hardware - APIs that provide access to physical components.

As web APIs become more widespread, the overlap with browser, language, or hardware types of APIs continues to intersect. As part of this shift I am also looking to better highlight how some APIs are actually open source solutions that can be deployed by anyone, increasing the interoperability and reuse that exists within some business sectors. Assigning a type to each API helping me better understand how APIs are shifting and morphing depending on where Internet technology is potentially moving to next.

API Ranking

Once I have sufficiently profiled each API I like to rank the entity and the APIs they provide, giving me a set of numbers that I can use to sort my API search results, and refine how I find different APIs as part of my research and storytelling. My ranking is pretty heuristic at the moment, but is continuing to evolve into a more automated and data-driven approach to ranking and rating APIs, helping sort out what the good and bad APIs might be, based upon a common set of criteria.

• Analyst (Me) - I always apply a number on a scale of 1-10 to my APIs, staying in tune with anything above 6.
• Building Blocks - Counting up the scores I apply to each building block, to understand the overall scope of each API.
• Activity - Understanding the activity surrounding API operations, and across the wider API community.

Right now my ranking is simply to help me prioritize which APIs I tune into, but eventually it is something I will apply to the API search I’m making available via API Evangelist. I’m still evolving the API index, and working out the details of how I make APIs available, while also growing my API index, but eventually I will be publishing a search interface for my APIs, where I leverage API ranking to help sort the results of each keyword search.

API Vocabulary

As part of the profiling of APIs, I am actively tagging the entities, as well as each API, providing more context about what is being offered. Helping me better define what each entity provides, but also the fine grain details of what each individual API path provides. My goal is to provide a meaningful set of tags for each API provider, helping me better break down what is being offered as part of my API research—focusing on the following elements.

• Tags - I apply keywords and phrases to each entity, API, and individual API paths.
• Industry - I apply an industry classification to each of the entities I profile.
• Grouping - Being able to group tags and industries into a variety of buckets.

Tagging is still a manual process for me, ensuring that I am not just developing my own vocabulary, and the details of each API, but I am also working to evolve my own awareness around what is going on. My tagging vocabulary reflects both what is going on with each API, across each business sector, as well as shaping how I share information about the APIs I’m profiling as part of this API research.

Publish API Definitions

The objective of all of this profiling is to come out the other end with three key API definitions for each of the APIs I am profiling. Everything I list above as part of this API profiling process goes into the crafting of three API definitions which I use to drive my research, storytelling, and ultimately share with my audience. These API definitions help me document what is going on, while also demonstrating to API providers what they should be doing as part of their own API efforts.

• OpenAPI - I publish an OpenAPI definition for each of the APIs I am profiling, detailing the technical details of each API.
• Postman Collection - I use Postman to manage the central truth for each API I am defining, ensuring it is also executable.
• APIs.json - I use APIs.json to document the moving parts of each entities API operations in a machine readable way.

These API definitions provide the meat of my API research, and allow me to quickly recall APIs as part of my storytelling. I am also using these artifacts in the evolution of my own API search engine, something I’d like to make publicly available once I reach a level of maturity and organization with my API index. My goal with these definitions is to first and foremost stabilize my research, secondarily influence API providers regarding how they invest in their API operations, and then finally make my research more accessible by developers, end-users, and other API stakeholders.

API Narrative

The final results of my API profiling is all about incorporating what I find into the storytelling I conduct on the API Evangelist blog. My API research fuels my storytelling in general, but each set of API definitions I produce as part of my API profiling ends up being used as part of my wider narrative in a handful of ways, providing exposure to each API I profile, but also shining a light on the practices of the entity behind each API, providing potentially healthy or unhealthy practices that other API practitioners can consider as part of their strategy--this storytelling comes in the following formats as part of my work.

• Blogs - I write up each of the APIs I profile as part of my regularly scheduled blog posting, writing up what I found.
• Guides - I include the results of my API profiling as part of the API industry guides that I publish for readers.
• Stacks - I list each API on my network of API sites, and within the resulting API stacks PDFs I publish for each area.
• Blueprints - When a provider rises to the occasion I will publish an API blueprint based upon their approach to doing APIs.
• Discovery - I include each API I profile in my API index, which I will be publishing as part of an API search engine in the near future.

The more information I have about an API, the more it will be included in my overall API narrative. Each profiled API ends up with a detail page as part of my API Evangelist network of sites, as well as getting at least on story on the blog. Depending on the overall value being offered by each provider, and the creative or innovative approach each API provider takes, they might end up in my storytelling even more. Shaping my narrative, and the stories I tell online and offline as part of my work as the API Evangelist, and now as the Chief Evangelist for Postman.

If you’d like to talk to me about profiling your API, or profiling other APIs, or entire dimensions of the API space, feel free to reach out to me. I offer a standard package for profiling APIs that already exist, providing a flat rate for implementing my profiling process against specific APIs—helping fund my research and storytelling. While some of these APIs take me much more time to profile, others taking me much less time, allowing me to balance a desire to fund my research, and make API profiling something others can also afford. Depending on the scope of an entity, and the APIs they provide, I might end up not making any money, but my overall goal is to fuel my storytelling and enrich my API index, so I’m not really worried about profiting from revenue brought in from profiling. I am more interested in just keeping the gears turning, APIs being documented, and my awareness of everything API reaching new heights.