API Evangelist
API Evangelist is about making sense of the world of application programming interfaces, or simple APIs. APIs have become part of every layer of our Internet connected world over the last 20 years, and this is my research project into understanding what is happening. As of 2019 I am also the Chief Evangelist for Postman, but I still use this site in the same way I have since 2010, as a workbench for what I am working on each day. Providing me with a very public way to work through my projects, while helping others see the world of APIs in different ways, and hopefully learn more about how APIs are being applied across our world
This isn't meant to be a blog in the traditional sense of the word, and you should think of it as Kin Lane's personal notebook that he is fine with others reading. Once you spend time reading my work you will better understand that this is my souning board, helping me work through my ideas, and I am not doing this for page views, audience size, or other metric. However, after over ten years of doing this I tend to have a regular group of folks who are tuning in and providing commentary via Twitter, GitHub, and other channels.
The Importance of Writing and Storytelling
24 Sep 2022, by Kin Lane
I do not write on API Evangelist as much as I used to. I still write a lot, but posts tends to stay in my notebook or get published to the Postman blog. I miss writing every day. Writing is important for me. Not just to convey concepts to other people who read my writing, but to help me organize my thoughts. Writing makes me more coherent. Writing helps me practice what I want to say. Writing helps me find the signal for the noise, which in a digital world is everything. Writing is how I find my way out of the dark and into the light with any idea. Writing is how I make sense of what is going on around me in this seemingly endless pace of technological velocity we accept as part of our online world. Without writing it is easy for me stop being curious. Stop being thoughtful. Without writing I get stuck in a sort of Groundhog Day of digital blah blah blah, and organizing my thoughts into short memos, messages, and blog posts for others to read helps me reclaim what matters to me each day, but then also allows me to move forward into the future with more knowledge, wisdom, and experience that I can tap into whenever I need. Each blog post here on API Evangelist represents something I have plucked out of the chaos of the day and added to my base of experiences and knowledge. I am not a list maker or task manager. I tend to let myself be dictated by my calendar, then by my inbox, and then probably Jira. Which I guess are all task managers, but they are rarely defined by me. Writing is how I reclaim my day. Writing is how I take everything that is thrown at me and find the things that matter. In this digital age we live in this is important. Writing is how we find...[Read More]
Demystifying Identifiers
06 Sep 2022, by Pascal heus
Identifiers are used everywhere to be able to unambiguously reference resources. Examples, amongst many, include a passport number, a domain name, a book ISBN, a database record key, a UUID, a network card MAC address, a shortened URL, a string hash, a vehicle identification number, a digital object identifier, and the lkes. They play a fundamental role in the API, data, and metadata spaces. When maintaining identiffers, whether handcrafted or code generated, or creating tools, database, and APIs, there are many aspects and facets that we need to consider. Here is a summary of the ones I can think of. Format: an identifier should always be expressed as a string (even if its a numeric value). We never perform mathematical operations on identifiers. Character Set: Technically an identifier can use any character, but most systems and standards have restrictions. In my experience, to ensure an identifier works in most situations, only use alphanumeric characters, numbers, and underscore, and never start with a number. Length: the length of an identifier is typically influenced by its character set, uniqueness requirement, or algorithm (e.g. uuid, guid, hash). We ideally want identifiers to be as short as possible, as they may repeat many times and bloat up the size of resources, files, database, network traffic. Finding the right balance between length and clash probability is important Case sensitivity: Identifiers should always be case sensitive. Persistence: It is commonly expected for identifiers to exist for at least the lifetime of its underlying resource, but often beyond as a resource may be deleted but its metadata or concept continues to exist. You may always want to keep track of identifiers to ensure it does not get reused. Deletion: Once published, an identifier should never be deleted, unless we know how to remove all references using it. So this is typically only an option in the early existence of the identifier, or when used within a closed sandboxed environment. Context: An identifier...[Read More]
OAS Extension Profiles
16 Aug 2022, by Pascal heus
The use of extensions in Open API Specification (OAS) has been supported since version 2.x based on a minimalistic approach whereby anyone can define a property starting with x- (e.g. x-myextension) which can hold any information. This feature was carried over as is to version 3.x. Extensions can be used for various purposes, typically to add functionality, particular use cases, or address shortcoming of the specification. There are numerous examples out there, such as GitHub , AWS API Gateway , or readme.io extensions. While technically functional, OAS does not provide any mechanism for capturing information about the extension itself, which has a significant number of negative consequences as for example there no easy way for user or an application to: Understand the purpose of the extension Validate its content Index it in a catalog for discovery Preventing name clashes (multiple extensions using the same name) Knowing who the author or maintainer are etc. And no guidelines are provided either in terms of governance. To address these shortcomings, we are investigating options around “extension profiles” and related topics such as registration, discovery, management, or design principles. An extension profile is a object that can be embedded in or referenced by an OpenAPI document to capture elements of information about its extensions such as: namespace: a URI or similar globally unique value that ensures there is no ambiguity in terms of the extension identity. The “x-myextension” property essentially being a nickname or abbreviation. version: information: an object that carries the extension version number and potentially additional properties such as version changes, validity period, etc. description / purpose: what is this extension about, how should it be used schema: a JSON schema describing the extension content (can be a reference) lifecycle: what is the status of this extension (dev/alpha, beta, production, deprecated, retired, etc.) provenance: where does this extension come from and who is the maintainer. This is a complex object that contains information about the vendor/agency/project, contact...[Read More]
API Catalogs and Portals Keeping Pace with the Number of APIs, Change Across APIs, and the Expanding Roles Involved Across the API Lifecycle
14 Aug 2022
I have been hearing about the challenges with keeping API portals, catalogs, directories, networks, hubs, marketplaces, and other similar constructs with the needed metadata, and adequately providing an up to date snapshot of enterprise API resources and capabilities for the last decade. It is a conversation that is growing louder due to the number of APIs in operation, and the number of enterprise organizations trying to get a handle on their sprawling API landscape. There are several realities converging on this very visible layer of our increasingly critical dimension of our API operations—the “portal”. Let me try to walk through each of these layers of this API onion to help me make sense of it, and help me better articulate how we can begin peeling back the layers and moving forward without too many tears. The API Portal as a Construct It is important to remember that the current construct of an API portal, and the Venn diagram of API landing page, documentation, catalog, and base for many definitions of “developer experience” is a construct that didn’t originate, but was cultivated by API management service providers. This means that many of our conversations around this problem is framed, shaped, and almost always has a dependency on the vendor, or more likely vendors we are involved with. Compare this to the early days of the web, where our web experience was framed by the likes of AOL and YAHOO. The early days of APIs (which is just the next iteration of the web), and you see that there was a lot of money to be made owning these portals and doorways, and while this concept isn’t going anywhere, it is time to embrace what the future of the developer or builder experience will be. A Very Sprawling Landscape The sheer number of APIs that exist across the enterprise is simply too much for the current concept of an API portal or catalog can keep up with....[Read More]
Speaking to API Strategy While Still Celebrating The Little Things That Matter
09 Aug 2022
I was talking with Preetham from our product team at Postman last week about how much we’ve grown and how are messaging has shifted. Postman has 20M users, and while our bottom-up messaging is stronger than ever, we are spending a lot of time working on our top-down messaging. I am fascinated with what leadership at enterprise organizations are thinking, and find myself immersed in talks about strategy, lifecycle, and governance, but I love moments where my thoughts get grounded by folks like Preetham who is hyper focused on “sticking to our roots”, and celebrating the moments developers are having throughout their day. Preetham reminded me (once again) that most developers do not have any reason to care about strategy, the API Lifecycle, and definitely could care less about API governance. Most API developers, whether producer or consumer, are just happy when some friction in their day is reduced, and they are able to enjoy their work a little bit more. Preetham is like, developers just want the authentication to work, or be able to reduce work using environment variables, and “why can’t we just celebrate this?”. Why are we expecting that every API developer think about al of the stages along the API Lifecycle, when their day is much finer grain than that. As an API strategist, analysts, pundits, and know-it-all, we get so caught up in the big theoretical picture. Sure, It is my job to help elevate folks to help them thinking about strategy and see the big picture, but this doesn’t mean we can’t also celebrate the incremental wins, and the little moments that matter to us in our day. This is really the art and humanity in this API game where we struggle against the overlapping tractor beams of technology and business. We need to be able to steer us in the direction they want, where what matters is what reduced friction for, and enables us human beings. While our...[Read More]
What is an API workspace?
01 Aug 2022
One of the most powerful capabilities of the Postman platform is the concept of a workspace. Like many powerful concepts, it is also very misunderstood, not seen, and wildly underutilized as part of API operations. I am doing a lot of work to change this, and as I do this work I am doing what I used to always do, and ideated about it here on the blog. I am spending time considering all of the moving parts of workspaces to provide more structure guidance regarding how enterprise organizations can be taking advantage of API workspaces to ground their operations. A number of Postman users I know are completely unaware of the fact that they there are different types of workspaces or even that there are different visibilities for your workspace. An API workspace is a versatile and flexible space for doing anything you want withAPIs, but let’s start with the fundamental building blocks of a workspace. Overview - Every workspaces has a title, summary, and full description to provide the “home page” or “README” for your API workspace. APIs - The mission control for each of your OpenAPI, WSDL, GraphQL, Websockets, and gRPC defined APIs you are producing or consuming. Environments - The definitions for each of your developing, sandbox, staging, production, or other types of environments in use for APIs. Mock Servers - The ability to generate a mock server from any API contract or collection, providing a usable representation of each API. Monitors. - Enabling the running of any collection on a schedule across multiple regions in a cloud, automating testing or any other behavior. Flows - A visual tool for defining and running workflows defined across many different APIs to produce a specific business outcome. There are plenty of other capabilities available in a workspace, but these are the base foundation of any workspace. However, I have to also note the fundamental building blocks of engagement that are present around these...[Read More]
Swagger Reflects the Short-Sightedness of Many API Industry Service Providers
25 Jun 2022
Before I tell this tale, I want to make it clear I am not looking to disparage anyone who has worked at SmartBear, or still works there, and this is purely my opinion as the API Evangelist, and does not reflect my employers view in my role as Chief Evangelist for Postman. This post is in the spirit of good ol fashioned API Evangelist hellfire, brimstone, and truth telling, a hallmark of what made folks tune into API during the years between 2010 and 2020. I feel better after one of these tales, and I can’t help but feel that the world of APIs will potentially be a little less shady and fucked up as a result (but mostly it is about me). This tale is about Swagger, a proprietary set of API tooling, which used to also be the name of an API specification. Swagger began its life as an open source project developed by Wordnik, a dictionary API. The goal was to provide a machine readable specification for HTTP APIs that could be used to generate documentation and SDKs. Then around 2015 Swagger, after the specification had taken off, the specification and tooling was purchased by SmartBear, who after some pressure from the community, agreed to put the specification in a foundation. However, at the last minute they decided that they would keep the very popular name Swagger, and rename the specification simply OpenAPI after putting into the Linux Foundation. Swagger was now a proprietary trademarked brand owned by SmartBrear, loosely applying to a mix of commercial and open source offerings within SmartBears control--not the open source specification that was put into the Linux Foundation. Seven years later, Swagger still dominates search engines and many folks still think it is the specification, and do not understand the difference between Swagger and OpenAPI. I was involved in the whole journey, helping build up and popularize Swagger, as well as the transition from Swagger to...[Read More]
A Postman Resource Bot
17 May 2022
A rite of passage for most new Postman employees is creating their first collection. I asked my new collection developer Bello Gbadebo (a href="https://twitter.com/gbahdeyboh">@gbahdeyboh), or “Debo”, to spend his first week on his first collection. Now that I am writing this, I realize the gravity of this situation, and very pleased that Debo rose to the occasion with a pretty kick ass first collection. Don’t get me wrong, I’ve seen some interesting first collections from new Postmanauts, but Debo really stepped up, hitting on all the right notes when it comes to demonstrating the power of a collection, with what he called his Resource Bot. Most Postman’s will build a collection that integrates with a single API, but Debo made one that scrapes, integrates with multiple APIs, and uses webhooks, and other advanced capabilities of a Postman collection. Here is the overview Debo provides for his Postman Resource Bot: “This collection is a slack bot that can randomly suggest resources and blog posts for you to read anytime you need it to. It has a set of commands that can be sent to it and what it suggests depends on the command it receives. To read more about its usage and commands, please read this article or watch this video.” The Resource Bot collection pulls entries from the Postman learning center, the Postman blog, and Youtube, but it its use of both Slack and Postman Webhooks to leverage the collection as a Slack bot that really elevates his approach. Also, the Youtube pull is pretty straightforward, but the learning center and blog are scraping. The collection is immediately useful and educational, demonstrates the power of APIs and scraping, while showcasing the automation power of a Postman collection with webhooks. It is an implementation that is spawning a bunch more ideas for collections for me, and different ways to help educate the community around the world of APIs, the API Lifecycle, and the Postman API Platform....[Read More]
API Perspectives
08 May 2022
I enjoy a privileged perspective of the world of APIs. It has been one that I have carefully crafted over a decade in the space. I experience and engage with a lot of perspectives, and I am always fascinated by how many perspectives there are in the API space, but also how many people occupy a single perspective and cannot see or empathize with those who enjoy other perspectives, or like me, multiple perspectives in any given moment. As I am doing other writing for work I wanted to take a moment and explore what the possible perspectives are that I regularly see in my API conversation, providing the baseline for the perspective I use in my storytelling, but also to help me in the moment while I am having conversations. API Producers - The version of the world that people who are producing APIs see, based upon what they want to achieve by doing APIs. Single API - A perspective that Is closest to the ground floor, thinking in terms of the resources and capabilities available in single API. Many APIs - Expanding and being responsible for many APIs, understanding what it takes to consistently operate and deliver many APIs. Type of API - Focused on a single type of API like REST, GraphQL, Event-Driven, and other patterns that are useful and possibly trendy. API Consumer - The view of the human being who is consuming an API and actually trying to put it to work as part of their business. API Producer / Consumer - How someone sees the world when they live simultaneously as both a producer and consumer of APIs. API Lifecycle - Looking at things from across the entire lifecycle, or from a specific stop along the API lifecycle, looking across all APIs. API Governance - Having a desire to govern API Operations, defining the guidelines, rules, and other constraints and enablement for APIs. API Roles - The technical writers,...[Read More]
Zombie API Portals
05 May 2022
I learned a new phrase a couple of months ago, and it is a phrase I have been hearing more and more amongst the conversations I am having on my Breaking Changes podcast, and with Postman customers as part of my regular engagements. The phrase is “Zombie API Portals”. Referring to an internal or external API portal that isn’t up to date and you really can’t tell if there is anyone home. We’ve all been at an API portal where nothing has time stamps, the documentation is static, and even when you ask a question or email them, you learn that indeed, there is nobody home. I really like the phrase Zombie Portal because as an API storyteller it is a phrase that captures your attention and evokes a shared pain we all face in a very pop culture way that also leaves you smiling. For me, this is API storytelling gold, and helps me do some heavy lifting to both get people’s attention, but also convey an important concept along the way. I have long joked about Mashery API portals always being a ghost town. Go check it out, almost every company who bought a Mashery API management solution back in the day is a ghost town, with the last blog post being 2011, and the last Tweet being around the same time. The "build it and they will come" vision for API providers didn’t always pencil out, and it didn’t help to be shelling out six figures on a 3-5 year contract with a major API management provider. However, this Zombie virus isn’t exclusive to Mashery, and is something you will see regularly across the API Landscape, where someone got a bee in their bonnet about doing an API, published a portal, documentation, and code libraries, then wrote a blog post and didn’t do much else after that. In the end, it is a lot of work to publish and API, but it...[Read More]
