The API Evangelist Blog - 2019

This blog is dedicated to understanding the world of APIs and exploring the technology, business, and politics of APIs.


Organizing EC2 API Actions As A Postman Collection

18 November 2019
I’m crafting Postman collections in support of the upcoming re:Invent conference in Vegas in December. One of the first collections I crafted was for Amazon EC2, allowing anyone put the Postman collection to work managing their AWS EC2 infrastructure. At first glance of the 359 actions available via the AWS EC2 API documentation page, I was overwhelmed. I definitely needed a way to tame the AWS EC2 API, making it more accessible and usable by a human—while APIs are meant for system to system integration, and delivering desktop, web, mobile, and device applications, it still has to be implemented by a human.  When crafting the AWS EC2 Postman collection I wanted to take some time to better organize the wealth of actions you can take, making them more accessible via a single Postman collection, organized by resource...

Subway Map Visualization Postman Collection

18 November 2019
I have been working to migrate all the different API driven JavaScript solutions I have developed over the years and run on GitHub using Jekyll to operate self-contained Postman collections. Now that Postman has a JavasScript visitations layer, I can make calls to APIs, parse the response, and generate HTML, CSS, and JavaScript visualizations. Allowing me to begin organizing all my API-driven visualization tools as simple, sharable, and executable Postman collections. I had developed a way to visualize the API lifecycle a while back using the Subway Map Visualization jQuery Plugin, by Nik Kalyani. It provides a pretty slick way of drawing lines, establishing stations, connectors, and other icon Subway map visualizations...

API Copyright Heading To The Supreme Court

17 November 2019
I received an email this last Friday that the Supreme Court agreed to hear the case on the freedom to reimplement APIs, as well as reconsider the copyrightability of APIs, and whether their reimplementation constitutes fair use. I’ve been a signer on two briefs as well as supporter of the case since 2012, and to help fire up my imagination and storytelling around why APIs should NOT be copyrightable, I wanted to revisit some of my storytelling over the years, and brainstorm some possible new arguments that might help in this latest wave of litigation. Here are just a sampling of the stories I have written over the years: May 2012 - APIs Have Been Copyrightable for 22 Years November 2012 - Help EFF Make Case For No Copyight on APIs June 2013 - Helping EFF Urge The Courts to Block Copyright Claims in Oracle v...

Why Is API On-Boarding And Authentication Still So Hard?

13 November 2019
I was teaching a class to business users yesterday and they were very curious about being able to play with some of the public APIs that exist, but for me, once again I found myself struggling with how to help them get over the hurdle of signing up for an API and getting the key or token you need to begin making your first call to an API. Even with having some ready to go Postman Collections that help introduce business users to some very well known APIs like Facebook, Twitter, and Instagram, I still can’t on-board them without pushing them to setup a developer account, create a new application, and obtain a set of keys or tokens. Something that is a regular hurdle for developers to jump over, and one that will keep most “normals” out of the conversation...

What You Mean When You Say You Have An Open API (Not OpenAPI)

13 November 2019
My friend Lorenzino Vaccari (@lvaccari) asked me to help him with what I think of as an open API. Not to be confused with the OpenAPI specification, but an API that is “open”. I’ll begin with the state of things and the reality that there are many API providers who proclaim that they have an open API, when in reality there are very, very, very, very, very, few APIs that are actually open. Honestly it is a term that I’d completely avoid using mostly because it doesn’t have any meaning anymore, but also because of the unfortunate name that Swagger was given after it was put into the Linux Foundation. Even so, I’d do anything for Lorenzino, so let’s work through this exercise of what it actually means when you wield the term “open API” in my opinion—so here we go...

How Much Was The API Portal A Construct Of API Management Providers?

13 November 2019
I am always wondering how much of the API sector is a construct of API providers, or something that was introduce by API service providers. Ok, I guess there is probably a third category of how much is manifested by analysts, storytellers, and bullshitters like me. One of the building blocks I have been pondering on lately is the concept of the developer or API portal. While it is something you can find organically growing in the wild, I’d say that mostly it is something you find being a construct or deliverable of the latest couple of waves of API management providers. Leaving me wondering what came first, the API management portal, or the API portal? Also, pushing me to ask other questions like whether or not we need the API portal at all? I am a big fan of having a single developer...

People Are Aware Of Public APIs But Less Aware Of Mobile APIs

13 November 2019
After some time in DC talking API governance I’m reminded that the “normals” are increasingly aware of public APIs, being able to actively discuss Facebook, Twitter, and other APIs, but are still very unaware of the larger mass of APIs that exist behind the mobile applications we are all dependent on. I don’t blame them, as many of the API providers I walk to who develop mobile APIs often do not fully see them either, leaving mobile APIs often un-secured, and operating in the shadows. Public APIs are easy to talk about, and I’m glad we’ve made progress in hing theelp “normals” be more aware, but we need to also be investing in more storytelling that helps bring mobile APIs out of the dark...

A Postman Collection As Unit of Compute For The API Lifecycle

11 November 2019
I have written several times about what a Postman collection means to my API discovery and search workflow. I have thousands of OpenAPI definitions indexed as part of my research, but until there is a Postman collection with a functional environment, my API definitions aren’t “complete”.  I can have a “complete” OpenAPI definition for the surface area of an API, but without a functional Postman collection, with API keys or tokens, and real world examples for each individual API path—it is just decoration. In this reality the Postman collection becomes a unit of compute that represents the discovery and search stops along the API life cycle, providing just two examples of how this machine readable API definition can be used across the entire API life cycle...

Thinking About Data and API Governance As Well As Observability

11 November 2019
I just got back to Seattle from Washington DC after spending a day talking about data governance at the Data Governance Design Conference. I thoroughly enjoyed the on-stage discussions as well as the hallway, and cocktail party conversation around the increasing importance of the governance of data online. I have a notebook full of thoughts from the event, and a head full of ideas after a plane ride home. I’ll be doing some more writing on the subject, but I wanted to lay the foundation of how I see the world of data governance, which is a much more technical view of things, but also overlaps nicely with the policy view of the landscape I just experienced. The group participating in the #DGDC discussions were much more focused on the important big picture elements, and the human call to action when it comes to data governance...

Getting You Up To Speed On API Definitions

11 November 2019
After spending some time in DC talking about data governance and the role API definitions play in how we quantify the data we have, as well as how it is accessed by all stakeholders, I have a serious need for a primer on API definitions—helping some smart folks I know better understand not just the history of API definitions and how we got here, but the critical role they are playing in how desktop, web, mobile, device, and network applications are defined, deployed, managed, and evolved. API definitions are tough to fully understand unless you’ve been tracking on them for a while, and have experience delivering APIs using modern API Infrastructure, so I wanted to craft a quick primer on what API definitions are, and why they matter...

What Is Behind The CLI Making A Comeback?

05 November 2019
As I read the recent announcement about Stripe releasing a command line interface (CLI) I find myself think more about the reasons behind the recent resurgence of the CLI, and what makes it a growing favorite of developers. Personally, I’ve had an on and off relationship with the CLI. Sometimes I really enjoy working in there, and other times it makes me feel like I’m working with more of a black box. In the age of API, it felt like CLIs were falling out of favor, but in recent years I am coming across more API providers like Stripe who are launching their own CLI alongside their API, and I’m interested to stay in tune with the reasons behind this shift in the landscape.I remember when I was first on-boarding with AWS S3 and EC2 back in 2006 they only had an API and CLI, no GUI dashboard...

Nobody Has API Governance Figured Out

05 November 2019
I was on a call recently with some folks doing the hard work of moving the API conversation forward across their enterprise organization, and the topic of API governance came up (again). This is a conversation I find myself having on a regularly basis, and one thing that comes up each time, is that the group I’m talking with has to state that they really haven’t figured out how to do API governance properly. I will state what I say each time I encounter this subject within these enterprise conversations so everyone can hear, NOBODY HAS API GOVERNANCE FIGURED OUT. Even the folks who I have been having this conversation with for 5+ years. Even the agile, nimble, scrappy little startups I’m having this conversation with...

Most API Definitions Are Just Fan Fiction

04 November 2019
My friend Tim Burks (@timburks) over at Google gave a great workshop presentation at the API Specifications Conference (ASC) in Vancouver. His talk was on OpenAPI, GraphQL, and gRPC, but one phase he used to describe OpenAPI definitions you find in the wild caught my attention. He described most of the OpenAPIs out there as “fan fiction”. I think this phrase is perfect for describing what happens in the world of API definitions, and accurately describes the growing number of API definitions you can find littering GitHub and other public locations. Resembling a steady flow of machine readable fan fiction about APIs, with some API producers telling their own story, but for most of the landscape, it is up to the fans to shape the narrative...

Do We Deploy, Provide, Publish, or Produce an API?

04 November 2019
I think a lot about the words we use in the technology sector. What they mean, and what they don’t mean. One of the stops along the API life cycle I struggle with a lot is about how we describe the process of deploying APIs. I chose to use the word "deploy" about five years ago when it comes to my API research, but I have also dabbled in the usage of other terms to describe what we do at this phase of the API life cycle. I wanted to pause for a moment to rethink this usage, and explore why I use deploy, instead of provide, publish, produce, or other ways of describing the act of making an API available. I’m guessing that the purpose and meaning of the words we use impacts the entire API life cycle in ways we might not fully understand...

Pushing Us To Think Externally Is The Most Important API Lesson

01 November 2019
I see it over and over—organizations learning new ways of thinking, moving beyond their legacy constraints by investing in APIs. This is one of the disruptive powers of APIs which can be all about making good things happen, or bringing unintended negative consequences, depending on the state of an organization, and the industry it operates in. This is why companies should be doing APIs, but they should always be approach them with a plan, starting small, and learning in a controlled environment before going to big. Making sure that an organization is ready for the changes being introduced before moving too fast, and going all in on participating in the API economy.API are all about entering an agreement with other parties regarding access to a particular resource...

Shit-Storming — The Latest (and Previous) Waves of How APIs Get Planned

01 November 2019
I have had the pleasure of sitting in on several event storming sessions, where an organization is brainstorming the design of the next generation of their APIs, ensuring that every idea and resource is literally put on the wall and represented as a sticky note. I have also had the opposite of pleasure of sitting in on many shit storming sessions where an organization is doing everything but properly planning the present or future of their API infrastructure. Revealing to me what I consider to be a fairly common approach to designing, defining, or just pushing tone deaf, out of sync, and unreliable APIs into production—adding to the technical debts that already exist across some large enterprise organizations...

Profiling The bunq Banking API

31 October 2019
The banking API bunq purchased one of my API profile packages, so I spent some time this week going through what they offer. Every API provider who purchases one of my profiling packages will utlimately get a post here on the blog, outlining what I found. It is no guarantee of a positive story, but it is the only way an API provider can technically pay to have a story published to API Evangelist. This is the narrative from what I found as I worked my way through what bunq offers, using my formal approach to profiling APIs. I always enjoy finding a simple description of what an API does, and bunq doesn't disappoint with, "Use bunq’s RESTful open banking API to build fintech apps you can't build anywhere else and reshape your banking experience the way you want it...

A Diverse API.json Index Example For Slack

31 October 2019
My friend James Higginbotham had a really nice example of using APIs.json in a talk I saw him give the other day. It was one of those things that jumpstarted my desire to showcase different ways of using the machine readable API discovery format. I still use APIs.json heavily in my API discovery and search efforts, but not something I've been really good at maintaining as a spec, and telling stories about. I'm working to remedy this, so thanks to James I'm pulling different examples of how to use APIs.json from my research. One example I wanted to use is out of Slack. So I pulled my most recent APIs.json index for Slack, and made sure it was updated with the latest building blocks, which included an OpenAPI, AsyncAPI, Postman collection, and JSON Schema...

API Environments Are An Essential Format For Our API Definition Toolboxes

30 October 2019
I am a big fan of there being many versatile and competiting API definitions that describe many different dimensions of how we put APIs to work. I hear folks say that they'd prefer to have one single API definition format to rule them all, which is something I think is short-sighted, lazy, and something that accomodates the future we want, not the one we need. I'm always eager to learn about new API definition formats, and always wiling to support new ones if they help us better define, communicate, and execute the APIs in our lives. One API definition I am increasingly using in my regular operations, and realizing the importance is the Postman environment format, which is a portable machine readable format you can use in unlimited ways...

A Dedicated Open Source Page For Your API Platform

30 October 2019
I’ve been studying how API providers showcase their open source efforts. Evaluating the dedicated pages API providers publish, working to better understand what the building blocks these providers are using to highlight how they make their open source projects available, as well as being more transparent about the open source tooling they are using as well. Out of this I’m looking to have a single blueprint I can share with folks, breaking down the moving parts of an open source initiative for an API provider or service provider. After looking through 20 separate open source pages for leading API providers, here are the building blocks of an open source page I’ve identified...

Managing Your API Definitions On GitHub

30 October 2019
I was profiling the banking API bunq over the weekend and noticed they were managing their Postman collections on GitHub. I have long been an advocate for API providers to manage OpenAPI and Swagger on GitHub, managing as they would any other piece of code or machine readable artifact. Anytime I find API providers like the New York Times, Box, and Slack, I make sure and try to write a post showcasing the practices, so other API providers will consider following their lead. Encouraging providers to not just manage their API definitions on GitHub, but also be very vocal about how and why you are doing it, so others will learn along the way.If you notice, Slack manages their OpenAPI, as well as their AsyncAPI and JSON Schema within the same GitHub repository...

Why Are APIs Better Than Direct ODBC / JDBC Connections?

30 October 2019
I had someone email me a question the other day, asking about how they should respond when someone asks them why APIs are a better choice that using a direct ODBC / JDBC database connection. Before I wrote a piece on it I wanted to tap my network of API geeks to see what other opinions might be lurking out there. My network is always a good place to start when it comes to looking for relevant, experienced answers. Questions from the field: Why Are APIs Better Than Direct ODBC / JDBC connections? -- I have my opinions, but I want to hear yours before I write up the story in response. pic.twitter.com/8MogddSUcM — API Evangelist (@apievangelist) October 28, 2019 Databases store end results, static state...

20 Open Source Landing Pages From Leading API Providers

29 October 2019
I am spending time understanding how API providers have invested in their open source offerings. Mapping out which leading API providers have dedicated pages for showcasing not only the open source they are building, but also the open source tools they are putting to work within their platforms. As I do with all of my API research I am looking to learn as much as I can from the approach of existing API leaders, and distill it down as part of the stories I tell, and work I'm doing at Postman and with partners. To help me get an understanding of what is happening, I took a sampling of top API providers from my database, and got to work profiling their apporach to showcasing the open source they build and put to use--here is what I'm seeing at first glance...

Portable No-Code Way Of Sending an SMS With Nexmo

29 October 2019
I am at the Vonage Campus event today in San Francisco listening to a variety of talks from their team and partners. As I’m listening I can’t help but play around with their APIs, and explore what is possible. It is easy to try out the SMS via the Nexmo documentation, but I wanted to create a more portable, sharable way of sending an SMS that anyone can use—even a non-developer. This gives me a chance to play around with Next more, while also crafting Postman collections that I can include in my catalog of simple, usable APIs. Nexmo provides a pretty straightforward API for sending SMS, with a basic set of properties for who the message is to, who it is from, and the body of the message...

The PSD2 Sandbox From Banking API Provider bunq

29 October 2019
I am a big fan of all API providers who offer sandboxes, and providing synthetic APIs, data, and other resources. It should be the default operating mode for anyone offering a public API, but it is definitely a requirement of providers who operate in regulated industries. With this in mind I am always on the hunt for sandboxes to showcase as I’m profiling APIs, so I was pleased to find a sandbox for banking API provider bunq, and impressed to learn it was also a PSD2 compliant sandbox—meeting the requirements of the EU banking API standard.As a PSD2 service provider, either an Account Information Service Provider (AISP) or Payment Initiation Service Provider (PISP), you will need a license from your local supervisor, and your unique electronic identification, authentication and trust services (eIDAS) certificate number to start using the PSD2-compliant bunq API in production...

Embedding JSON-LD To Power API Discovery

28 October 2019
If you have been in charge of operating a public API you know how hard it is to get your APIs found. One important way you can increase the discoverability of your API is by embedding JSON-LD into the HTML for your API portal, and describing your API resources using Schema.org. While this is something that all API providers should be doing, it is something that is still pretty rare in the wild, so anytime I come across a real world implementation, I make sure and showcase. My most recent example of using JSON-LD and Schema.org in the wild comes from the banking API platform bunq. bunq is a banking API that represents the future of banking in my opinion. bunq gets APIs, and understands how to do them well...

More Information Is Not Always Better When On-Boarding Someone With An API

28 October 2019
I process a lot of API documentation, trying to make sense of what each API does. As I wade through the human and machine generated API documentation for the different APIs I am profiling I am reminded that more information isn’t always better when it comes to getting started with an API. When it comes to understanding what is possible with each API, it is more meaningful to begin making API calls and seeing results than it is read lengthy descriptions about what is possible. Especially when it is rambling technical speak that doesn’t provide you with any sort of narrative about what is happening, often leaving me more confused than when I first stumbled across an API in the first place...

Individual API Life Cycle Stops And Operational Life Cycle Stops

28 October 2019
One difficulty I have telling stories across the API lifecycle involves the separation of stops along the API life cycle that are about each individual API, and those that are about serving the entire operation--all APIs. There is a relationship between the two, but there are many different ways in which you can help educate developers, and provide instruction depending on whether it is just about a single API, or something that supports all APIs. One key aspect of standardizing how APIs are brought to life is to make sure you are always thinking about the big picture, while also ensuring each individual API has what it needs.It is common for API developers to think about their immediate needs when designing, developing, delivering, ad supporting an API...

Sometimes My Desire To Automate Is More About Laziness Than Innovation

25 October 2019
As I’m working through my tasks each day I am always looking for ways to automate away the cumbersome portions of what I need to accomplish. I am always weighing having to manually accomplish something over being able to write a script to accomplish something. It is always tempting to think about writing a scrape script to work through a pile of research I need to gather, and engineer some crafty algorithm that will help me sort through it and make sense of it all. As I get older I’m finding that most of the time this automation is more about laziness than it is about the power of technology, or the benefit it can bring to my work. I am pretty good at calculating what it will cost for me to manually tackle something versus what it will take to automate something—if it is even possible in the first place...

A Salesforce API Collection

25 October 2019
I have found myself back in SaleForce doing some work, and rather than code wrangling to get the access I needed I created a SalesForce Postman collection and environment, allowing me to quickly get at the MANY objects and records available to me within the SaleSforce ecosystem. While the Postman collection doesn’t reflect 100% of the surface area of the SaleForce REST API, with over 800 individual requests it covers a significant portion of what is available via the CRM API.The SalesForce REST API has an endpoint where you can query for a list of objects, an then pass those objects in as a path parameter. This approach to designing APIs, or what I’d consider to be a lack of API design was a common pattern from 2000 through 2010, and is something you still see fairly often from providers in 2019...

Documentation Pushes The Human Readability of Your API Definitions

21 October 2019
I like machine readable definitions that are also human readable. Depending on how much you care about your API consumers, and how mature your API life cycle is, your will invest different amounts of energy into crafting your API definitions. Many will just autogenerate them, putting little refinement into them, relying on services and tooling to do most of the work. However, those who understand the value of API documentation will realize that investing in the details of your API definition and design will realize a bigger return when it comes to on-boarding developers with their API.API definitions, whether OpenAPI, Postman Collection, or other format should be accessible and always strike a balance between being both machine and human readable...

It Is Difficult To Know Where To Begin With APIs

21 October 2019
The API landscape is huge. APIs are being used to power desktop, web, mobile, and device applications across almost every business sector. While there are many common patterns used across the leading APIs, APIs still come in many shapes and sizes, making it difficult to know where to begin when first learning about APIs. This isn’t an exclusive situation with people who are just learning about APIs, it is the state of things for most people working with APIs on a regular basis. No matter how experienced you are with APIs, there is always some new approach emerging, and some evolution in how things are done that might just be out of view. Leaving us all struggling to keep up, stay aware of latest trends, while perpetually working master what we already know, always refining our approach to getting things done with APIs...

Some API Evangelism Metrics

21 October 2019
Channeling APIs, and cranking out API content i what I do. I find it pretty easy to regularly produce a regular flow of diverse content spanning the entire API life cycle. However, one challenge I do have is making sure it is all done in a consistent way, ensuring that I’m publishing across all stops along the API lifecycle, but also making my work available in a variety of formats. I prefer reading short and long form content as part of my regular intake of API information, but I know that other people thrive on obtaining their knowledge via different channels. Making it important for me to make sure I’m being consistent in how I’m measuring my output by establishing some common metrics I can use to keep track of how I am doing...

Most People Just Want to Deliver the API and Will Not Be Interested in the Process

18 October 2019
The is my regular reminder that not everyone will care about APIs as much as I do. Most people just want to do their job, and aren’t interested in understanding the nuance of API design. I’d say that this is one of my biggest sins as a technologist—believing that other people see the world as I do, and in turn will want to care about “doing APIs right”. This is not a case of I’m right, and they are wrong.  This is a case of the world is full of different people, who see the problem very differently, and not everyone will agree that APIs are the solution, let alone care about understanding and debating the details of API design with me. And I can’t expect them to always change their tune...

Introductory API Concepts Are Timeless

15 October 2019
I’ve been working on a series of introductory API blog posts for Postman, helping introduce people to the concepts of APIs. When I do series like this I tend to get comments from people that the work reflects my earlier writing on API Evangelist, and is something that reflects the past. Bringing people out of the woodwork who feel that everything I publish here on API Evangelist is always in forward motion, and my knowledge of is always advancing and marching ever into the future at a steady pace. I feel that this notion reflects a general belief that technology is always moving froward and that you either keep up with the pace, or you are left behind. Believing that most API concepts are outdated shortly after they are applied, and we will always have to be looking out for the next evolution in how APIs are being done...

Well-Defined API Workflows Are Sign Of API Maturity

15 October 2019
Having standard API practices established across our development teams plays an important role in pushing us to deliver more consistent and usable APIs. Establishing a feedback loop with API consumers and other stakeholders adds another layer of refinement to our APIs that help us iterate and harden them. Another dimension of the API conversation that helps us push our APIs towards maturity centers around discussing and defining the meaningful workflows that can be developed with our APIs. Helping us establish more meaningful business workflow with our APIs, and potentially other partner or 3rd party APIs, connecting our APIs together into workflows that help us accomplish the most valuable tasks we can...

The API Evangelist API Profiling Process

14 October 2019
This is an outline of the API profiling process for API Evangelist. Providing a structured approach to profiling a single API, and quantifying the scope and value of API being made available by a commercial or non-profit provider. This provides a narrative regarding how API Evangelist profiles APIs that targets API providers and service providers, offering up a service that anyone can purchase, but also actively demonstrate how providers can shape their own operations, and contribute to the overall API conversation. 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 AjPIs, while also making sure I implement it against the growing number of APIs I discover across the landscape...

Are You The API Librarian Within Your Organization?

14 October 2019
I think back regularly to my days as a database administrator in the 1990s, and the critical role I played in so many different organizations by being a keeper of the valuable data that was used to power the business. Over the years, I’ve seen this role done well and not so well at many different organizations across many different business sectors—a position that still holds a great deal of power today. However, the one big difference I see now, is that much of this power has been displaced, shifted, and distributed by exposing simple web APIs, making valuable data available across internal groups, amongst partners, and to 3rd party developers. Changing the balance of power, and opening up the opportunity for a new generation of users to emulate some of the realities that database administrators catered to, but often times it s something that is more about giving power to people who are closer to where the business action is, and moving things out of the classic IT departments where it has existed for decades...

Most API Owners Are Just Focused On Issues

10 October 2019
One of the biggest challenges I face in reaching API practitioners in my work as the Chief Evangelist for Postman is that most people in these roles are more focused on the day to day details of their work, and are often cognitively unable to zoom out and see the bigger picture. It isn’t that they don’t have the interest or capacity to do this, it is that the day to day demands of their jobs prevent them from having the bandwidth to pause even for a few minutes to think about the bigger picture, let alone get up to speed on what they need to, and craft a more robust API strategy. My biggest competitor when it comes to reaching these folks is not another service or tool, it is just the expectations placed on them by their organizational environment...

Learn to API

10 October 2019
You hear a lot about learning to code in the tech sector. I want to invest more in people “learning to API”. Not just developers, but anyone who wants to understand how to push back a little on the digital word we’ve built for ourselves. I’m not convinced everyone should learn to code, but I am a believer that everyone should learn to API. If you use the web, you should learn to API. To help you in your job. To help you in your hobbies. To help you better understand the physical and online worlds around us. You may never actually write any code against an API, or build an application, but with the growing number of services available today that have APIs, there is no reason why you can’t be putting these APIs to work for you using the wide array of integration opportunities available to developers and non-developers...

Making Your API Collection The Tutorial

08 October 2019
I am going through a bunch of different tutorials from API providers looking to motivate users to accomplish some fundamental API on-boarding task, or introduce them to some meaningful workflow involving their API. I am amazed at how much detail, including screenshots that people go into, and how so few of them actually provide Postman collections that help power the task or workflow they are shining a light on. I’m determined to figure out why. I’m guessing folks are used to using Postman as a simple web API client, and haven’t really fully grasped the concept of sharing collections, and how collections go above and beyond what they are used to with Swagger / OpenAPI. After over eight years of people using Swagger / OpenAPI, most still think it is a documentation solution, so I’m not really surprised that folks don’t fully get collections—I didn’t until recently...

Capital G API Governance vs Lowercase g API Governance

08 October 2019
API governance is a hot topic amongst leadership and stakeholders who care about the long term health of API operations. I regularly get questions from folks about what I’m seeing when it comes to API governance, from developing an API design guide, all the way up to the deeper dive into governance I did last year for the Department of Veterans Affairs. I would say that this work goes way beyond what most organizations are ready for, but API leadership is still interested in learning more about how they should develop what I would consider to be a capital G API Governance strategy. Something I recommend everyone think about, but make sure you also think about the more organic and incremental governance efforts as well, finding a balance between the two...

Getting API Providers To Step Up to SLOs/SLAs

07 October 2019
I am preparing for a busy week of conversation with folks at API World, and with an inbox full of requests to meet and discuss the challenges API providers and service providers face, I want to work on preparing myself by loading up a variety of topics into my old brain. Some of the folks I’m talking with have shared questions with me to prime our conversational pump, so in my way, I figured I’d work through them here on the blog to help put these thoughts on the tip of my tongue.One interesting question I received this week is around how to get API providers to step up to agreeing to and respecting service level objectives (SLOs) and service level agreements (SLAs). To provide more context, this involves APIs within a large enterprise, where there is a shared catalog of APIs for internal, as well as for external usage, and API providers can step up and publish their APIs for access within the enterprise API catalog--a situation where you have several challenges: Getting API Providers To Publish APIs - Not all groups are going to be competent and confident in publishing their API resources to a shared catalog...

API Provider On-Boarding Best Practices

07 October 2019
I am preparing for a busy week of conversation with folks at API World, and with an inbox full of requests to meet and discuss the challenges API providers and service providers face, I want to work on preparing myself by loading up a variety of topics into my old brain. Some of the folks I’m talking with have shared questions with me to prime our conversational pump, so in my way, I figured I’d work through them here on the blog to help put these thoughts on the tip of my tongue.API providers are always wanting more advice on how to help developers be more successful when it comes to their valuable API resources. This is a question with one answer—get out of their way at every turn...

Conducting An API Landscape Analysis

07 October 2019
I am having conversations with different organizations about where to start with APIs, pushing me to revisit some of my previous API landscape analysis work, like an evaluation of the Department of Veterans Affairs (VA) existing data and resource presence. The process is born out of my low hanging fruit work, identifying where the existing data sets for an organization already exist, shining a light on how and where an organization should begin with their API investment. Asking the question, if an organization is regularly publishing spreadsheets, CSV, JSON, and XML data to their website, why are these not available as APIs? A question that 98% of the enterprise organizations I come across do not have an adequate answer to...

Increasing API Adoption and Consumption

07 October 2019
I am preparing for a busy week of conversation with folks at API World, and with an inbox full of requests to meet and discuss the challenges API providers and service providers face, I want to work on preparing myself by loading up a variety of topics into my old brain. Some of the folks I’m talking with have shared questions with me to prime our conversational pump, so in my way, I figured I’d work through them here on the blog to help put these thoughts on the tip of my tongue.AN area that API providers are rabid for more information on is how we they increase adoption of their APIs, and turn consumers from just making a few API calls into active users who are putting APIs to work within their applications...

Getting Started With Postman Templates

04 October 2019
I am getting ready for my first API event as the Chief Evangelist for Postman—API World next week. To help prepare us, Joyce Lin (@PetuniaGray), fellow developer relations team member shared some Postman templates with me, equipping us with some of the most useful examples of using Postman she uses in her talks. I thought I was a proficient Postman collection user until I began working at Postman, where I quickly realized that I have a lot of work ahead of me to learn all the ways of doing interesting API things with Postman collections and templates. Making them perfect little portable learning objects, demonstrating how to accomplish a handful of API-driven tasks, or even more relevant workflows...

Personal API Tokens For All APIs Please

04 October 2019
I have written about this several times before, and it is something I will keep writing about until it comes true. Every API provider that employs OAuth for their APIs, show have a quick and easy, non-code way of obtaining a token for API access to your own account, and any generally available public APIs. If you need an example of this in action, log into your GitHub account,  click on your account settings, choose developer settings, and look at your personal access tokens. With personal access tokens you can create a new token, drop it into the header of any API request, and begin making calls to the GitHub API—this is how it should be for all APIs that use OAuth. No OAuth dance to just at your own resources...

API Collaboration Is The Next Killer Feature

03 October 2019
As I work my way through the features of Postman and work to bring it all into alignment with my existing storytelling around APIs, one of the areas I’ve been slowly adding to my collective API research is "collaboration". I setup collaboration.apievangelist.com a while back to help track on what different companies are up to, as I do with any other area of the API landscape. Collaboration is a pretty big tent to operate within, with many different interpretations of what it means, and a growing number of examples out there regarding how it can be done. While there are many features of Postman that get me excited, I’d say the collaboration features around Postman collections, workspaces, and the API development platform is what I wold call the next killer feature—let me explain a little more about why...

API First With Legacy APIs

03 October 2019
It is common to think API-first just applies to new green field APIs being developed. However, I’d say that it should become a priority with addressing legacy APIs as well. I’m working to evolve my tagging API to better meet my current needs for not just tagging my blog posts, curated news, organizations, links, patents, and other resources, but also begin to apply to my OpenAPI, AsyncAPI, JSON Schema, and other machine readable artifacts. I need to do a major revision on it, but first I need to better map out what I have. My tagging API has been around since 2011, and since nobody but me uses I have never created an OpenAPI, or documented it in any way, so my first move is to map out what I have...

How Often Do You Receive API Responses Or API Definitions In Emails From People?

02 October 2019
I regularly receive emails from random strangers, as well as known individuals who I am working with, that contain JSON responses from an API request, asking for some analysis, troubleshooting, or feedback on how an API works (or doesn’t). I even receive Microsoft Word or Google Docs with API responses pasted in them, attempting to articulate something how an API works, or to solicit some feedback from me. If I am going to share an API response with another user, I’m going to start with a Postman Collection, and secondarily share a link to a GitHub Gist, so the practice of emailing around is something I’m actively trying to nip in the bud with some storytelling and education...

Do You Have Visibility Into Which Teams Are Developing Your APIs?

02 October 2019
One of the biggest benefits from the evolution of the API management over the last decade was the visibility and awareness it gave us around who is using our APIs. While this is something that is playing out over and over as each mainstream company wakes up to the potential of APIs. As I get back to working with companies on their API strategy I’m beginning to realize that a similar type of awareness is beginning to play out internally, but instead of developing an awareness of who is consuming APIs, it is more about gaining visibility into who is building APIs across distributed groups and teams. Helping API leadership within organizations get a better handle on their overall API lifecycle, and begin to establish more meaningful metrics about how valuable API resources are being delivered...

API Evangelist API Industry Guide: Regions

01 October 2019
Tyk first asked to sponor this guide over a year ago, and I finally found the bandwidth this summer to move my API region research to a point where I could produce the quality of output I require for my guides. Like my other API industry guides, this is an executive summary of a single stop along the API lifecycle to think about when planning your own API strategy, but this guide is dedicated to understanding how different geographical regions are influencing how we think about APIs. This isn't something that is unique to APIs, and the multi-regional availability of applications, infrastructure, and APIs is born out of the cloud evolution--with the big three (AWS, Google, and Azure) dominating the landscape, and who are rolling out new availbility regions at a break neck pace...

API First Is Hard To Adopt Because API Deployment Is Still A Manual Step For Many

01 October 2019
One of the high level API concepts I have been championing for a couple of years now is helping API providers move from a code-first approach, to an API design first, or as I like to call it, and API define first approach. The practice of crafting an API definition, applying common API design practices, mocking, documentation, and soliciting feedback on your API before you ever begin writing any code, or publishing your API to a gateway. It is a concept that has clear benefits, and has captured the imagination of many API providers, but it is something that is easier said than done when it comes to actually pushing teams to make a complete shift to being API define / design first--leaving me thinking deeply about what is holding teams back...

REST And Hypermedia And GraphQL And gRPC And Event-Driven

01 October 2019
API folks are great at being passionate about the technologies they believe in. This is great for them, but it isn’t always great for the folks who aren’t quite as passionate and are just working to understand the API landscape and make sense of the different patterns, services, and tooling out there. One of the areas I’ve been heavily investing in as part of my API industry research over the last couple of years is to help people understand how they can invest in a diverse API toolbox, and develop the awareness they need to be successful in designing, developing, and delivering APIs at scale, for a variety of use cases. Counteracting some of the more vendor focused storytelling in the space that works to confuse, distort, and shame folks for their approach to delivering APIs—providing a more pragmatic view of how we should doing APIs...

Ensuring We Invest In Educating And Engaging With Leadership Around Our API Operations

30 September 2019
I’m working on my strategy as the Chief Evangelist at Postman. We have a kick ass developer relations team and a passionate community of users who generate tutorials and other content, and while I will be working to help rolls up my sleeves and contribute in these areas, supporting the team, but I know they have this part of the conversation covered well. To augment what is already happening, I am working to develop a voice and approach that is uniquely mine, built on what I’ve been doing as the API Evangelist, but something that can be evolved to have that unique Postman presence. One of the areas I’m including in my approach is a heavy focus on non-developers, but specifically tryiing to make content, talks, and other resources that decision makers and other business users will benefit from...

A Robust Example Of An API.json Index Cataloging Public Data APIs

30 September 2019
I crafted a pretty useful APIs.json index over the weekend. I thought it provided a pretty robust look at what APIs.json can do when it comes to providing machine readable API catalogs. This is a project I had started a couple years back, but just found some bandwidth to move forward--providing a complete APIs.json of the Socrata platform of data and APIs for city, county, state, and federal government. The APIs.json for the Socrata platform provides everything you need to get up and running with Socrata's discovery and metadata API, as well as the 200+ domains they support when it comes to providing public data access. Here is the APIs.json index in it's entirty. Note the include options, which provide references to the 200+ domains, where you will find entirely separate APIs...

API Definitions For 28,835 Data Sets Across 207 City, County, State, and Federal Data Portals

29 September 2019
My friend Taylor Barnett (@taylor_atx) over at Transposit asked if I had an OpenAPI for Socrata the other day, which triggered my memory about a whole bunch of old work I had done around Socrata that I had never got to a fully complete state and therefore never published. If you aren’t familiar with Socrata, they provide public data platform for city, county, state, federal, and other entities, making them them one of the goto place when understanding open data in the United States at scale. While you can go to the almost 200 entities that Socrata publishes data for, you can also easily discover and work with data from across all the providers via the Socrata discovery and metadata APIs...

A Postman Collection Socrata Open Data Discovery and Metadata API

29 September 2019
My friend Taylor Barnett (@taylor_atx) over at Transposit asked if I had an OpenAPI for Socrata the other day, which triggered my memory about a whole bunch of old work I had done around Socrata that I had never got to a fully complete state and therefore never published. If you aren’t familiar with Socrata, they provide public data platform for city, county, state, federal, and other entities, making them them one of the goto place when understanding open data in the United States at scale. While you can go to the almost 200 entities that Socrata publishes data for, you can also easily discover and work with data from across all the providers via the Socrata discovery and metadata APIs...

I Understand That Not Everyone Wants To Use The Command Line

26 September 2019
I like using the command line, but I get that it is intimidating for a lot of folks. I’m not 100% sure why, but at different points in my career I have embraced and distanced myself from the command line. So for me, I understand this emotion and while I have used the command line a lot over the years,  much prefer interactive documentation, client side tooling. This is one reason I was such a believer in Postman when it first came on the scene in 2012 / 2013 (if I remember correctly). It simplified the ability to make API calls, and it returned all the details you needed about what was going on behind the scenes of applications. No command line needed. I know that many folks love the command line...

How Do We Measure The Efficiency, Agility, and Velocity Of An API-Centric Way Of Doing Things?

26 September 2019
One of the benefits of doing APIs that we have always touted as API believers, is that APIs increases efficiency. We are able to move faster. Be more agile. Increased velocity of what our teams can deliver by reducing the size and scope of teams and the API infrastructure they can bring to life. It is something I’ve said over and over in my storytelling, and as I work to scrutinize the words I use in my storytelling, and work to justify the meaning behind my work, I’m looking to better understand I how I can back up this claim. The first question I ask in these situations is how do we measure whatever is in question, and quantify this change we claim is going on. So, with this, how do we measure the efficient, agility, and velocity that APIs are brining to the table...

The Developer On-boarding Use Case For Postman

26 September 2019
I am working my way through the use cases on the Postman website, getting familiar with how their customers are using the platform. They have some very straightforward use cases that they have assembled based upon actual ways in which their customers are applying the value they bring to the table. Developer on-boarding is a particular fascinating one for me because it really touches on one of the most difficult aspects of APIs—getting someone new up to speed on what is going on. Getting people to go from zero to understanding what an API does and actually making API calls is how you begin to realize the value from new users, developers, employees, or anyone you are trying to reach with your API operations...

Attacking Cumbersome API Queries With A More Organized and Coherent API Collection

25 September 2019
I’m working extra hard when it comes to creating APIs across every possible industry I can think of to help push my understanding of what Postman collections are all about, and what is possible when putting them to work. As I progress in my work I am quickly realizing how much more versatile they are than OpenAPI definitions, allowing me to do things I wanted to do with OpenAPI, but couldn’t always figure out how to make happen. Some of my dedicated readers might be getting sick of hearing me talk about Postman collections, but since most of my readers don’t follow me regularly and rely weekly updates via email, or stumble across my work as part of search engine exploration—I am going to continue cranking out the stories! While working with an API collection for the Food and Drug Administration (FDA) National Drug Code (NDC) API, I realized how Postman collections can help flatten some cumbersome API queries I encounter while on-boarding with some of less than well designed APIs out there...

Federal Government Data Sets Published As Postman Collections With Mocked API Paths And Organized in API Workspaces

25 September 2019
I have been working on creating, publishing, refining, and bringing attention to federal government datasets and API since 2012, with time spent in DC working for the Obama administration. I received a Knight Foundation Grant in 2016, and I’m super passionate about making government data more accessible and usable, so naturally I’m going to keep investing in government data while working with Postman. I am finding Postman to be an amazing platform for moving forward my government data work, empowering data stewards to do what they do best with some new tools, processes, workflows, and approaches to curating and making data available for consumption, augmentation, enrichment, and most importantly something anyone can put to work...

Simple Or Complex API Collections For Different Levels Of API Consumers

25 September 2019
I have been learning a lot about the different ways in which Postman users are using collections in my new role. One of the more interesting use cases I’m tracking on is for assisting the on-boarding of new developers. I can get behind anything that makes it easier for developers or non-developers to get up and running with an API, and some of the creative ways I’ve seen companies craft Postman collections to help reduce friction has inspired me to keep exploring and mining this aspect of putting API definitions to work in my storytelling. One of the most recent use cases I was exposed to in this area, was the crafting of complete Postman collections for more experienced developers, and more simpler ones for newer developers—reducing the cognitive load when it comes to API on-boarding...

The Caselaw API Identified As Part Of My University API Research

25 September 2019
Another API I came across while studying the API conversation at US universities was the Caselaw API over at Harvard. It was another fairly simple API that could use a Postman collection. The Caselaw Access Project API, also known as CAPAPI, serves all official US court cases published in books from 1658 to 2018. The collection includes over six million cases scanned from the Harvard Law Library shelves. Providing for a pretty rich target for adding to my API search index, a process that requires me creating a Postman collection, which provides me with an executable API definition for each API I’m tracking on.Unlike many other APIs that I profile the Caselaw API is actually pretty well documented, but even the best documented API will benefit from their being a complete Postman collection present for developers to get up and running with a single click...

I Did Not Fully Understand What A Postman Collection Was All About

25 September 2019
I have been using Postman collections for a couple of years now. I have been auto-generating them from my central database alongside OpenAPI 3.0, and previously Swagger 2.0, as part of my regular work profiling APIs. I have imported and used many different collection in my Postman API development environment. I assumed I fully grasped what they are all about. I mean I am the API Evangelist, all I need to do is play with something a little bit, and the API utility of it will become evident to me within minutes. I know my stuff. Right? Not exactly. Apparently I was pretty tainted from my usage, adoption, and evangelism of OpenAPI, and I didn’t fully see how Postman collections can be used to define APIs, and act as an executable unit of representation for an API...

Adding Twilio's Referral Program As An API Building Block

24 September 2019
I am always on the hunt for interesting new building blocks for how we can all operate our APIs, and the most mature API providers out there are usually where I can find the most innovative ones. This week’s interesting find is out of the API pioneer Twilio, with their new referral program. Providing a way that Twilio users can invite a friend to become a Twilio user, which isn’t anything that groundbreaking, as most SaaS and API platforms offer this, but with Twilio’s referral program you get $10.00 to apply to your Twilio account for each referral you make. They made the Twilio referral program pretty straightforward, which is nice because many affiliate related solutions can be pretty cumbersome—it goes something like this: You get a personal referral link that you can share with your networks Users sign up with your link, upgrade, then receive $10 to spend with Twilio For each person you refer who signs up for Twilio and upgrades, you get $10 in your Twilio account As Twilio says on their announcement, “depending on the country where you’re sending… that’s over 1250 SMS messages… or 1,000 free voice minutes...

Looking For Data Standards By Industry

24 September 2019
I am working to expand the vocabulary I use to search for new APIs. I already have a pretty extensive set of keywords and phrases I have from mining the world of APIs over the last nine years, but I wanted to get more formal about how I find new and interesting APIs across as many industries as I possibly can. To help me in my effort I adopted the North American Industry Classification System (NAICS) as the official vocabulary I use for searching and organizing the businesses, organizations, tooling, APIs, and datasets I'm profiling as part of my research. Helping me standardize how I uncover new APIs, keeping my vocabulary in alignment with government agencies like Censuse and Labor, but also industry organizations, and the companies that operate within each business sector...

Enabler Mock Data APIs Alongside Other APIs Within My Collections

24 September 2019
I was demonstrating to to someone how you can document the Food and Drug Administration (FDA) National Drug Code (NDC) API using Postman and I found a way to enrich real world APIs by publishing mocked data APIs alongside the primary APIs within the same Postman Collection. The URL structure of the FDA DNC API (acronym congestion) is pretty simple https://api.fda.gov/drug/ndc.json?search=brand_name:"xanax"&limit=100, and it is an open API so you can jus take that URL and see a response without putting in an API keys or tokens. The API provides a suite of keywords you can query as part of the search parameter, with the only two I’m focused on being “brand_name” and “active_ingredients”, providing fairly straightforward querying capabilities, but there are some gaps in their documentation approach...

API Industry Guide: API Definitions

24 September 2019
This is a guide to the world of API definitions--introducing you to what the machine and human readable schema and API specification formats are used for when it comes to defining API-driven capabilities. Formats like JSON Schema, OpenAPI, AsyncAPI, and Postman Collections are changing how we define our APIs, and then use definitions to engage with developers throughout the API life cycle. This API definitions guide is the result of almost 10 years of research and participation in the evolution of API definitions as part of community development, conferences, and the API efforts behind the specifications themselves. I've worked to distill my research on API definitions down into a short guide that business as well as technical individuals can follow...

Making An API Request To Update Examples In My API Documentation And Power My API Mocks

24 September 2019
As I was working to improve upon a couple of the API collections I’m building, and trying to assess at what constitutes a “complete enough” or “robust enough” collection, I noticed how the process within Postman is iterative, outcome based, and driven from actual requests and responses. Meaning a complete enough Postman collection is relative to the outcomes I’m looking for—things like documentation and mock APIs. To be able to achieve robust API documentation and mocks I simply need to add my API request, successfully make a call to my API defined, and save the response as part of my API collection. Then, once I’m ready, all I need to do to update my API documentation and generation API mocks is to hit publish for each of these desired outcomes...

Exploring API Conversations At Over 2000 US Universities

23 September 2019
I am looking at API adoption across universities, and after creating a simple world university API from a CSV I found on GitHub listing all of the worlds universities, I wanted to spend more time understanding how universities are talking about APIs (or not).  I have been studying universities APIs for a number of years now, having worked with BYU, UC Berkeley, and other universities on their API strategies. Similar to how I am expanding my industry vocabulary for searching for APIs, I am also getting more formal about how I search for APIs on campus by searching specifically using the university's name, as well as begin crawling the domains for each of the universities that I have in my index—getting more personal with some of the universities and what they are building...

The Harvard Art Museum API

23 September 2019
I was working my way through a bunch of new university related APIs that I discovered after adding a list of US universities to my API search vocabulary. While I come across university APIs in my regular harvesting of possible APIs using GitHub and Bing APIs, I wanted to be able to search these channels for university related terms, but also have the domains for all of the universities so I could also spider their sites looking for some of the common API signals I am looking for. I identified a couple hundred new APIs, but I wanted to cherry pick a handful of them for profiling using Postman, and showcasing here on the site. One of the APIs I wanted to showcase is the Harvard Art Museums API is a a web service designed for developers who wish to explore and integrate the museums’ collections in their projects, providing direct access to the data that powers the museums' website and many other aspects of the museum operations...

An Open Source Sitemap API For Every Domain

23 September 2019
I invest a lot of resources into spidering domains. I spend probably about $50.00 to $75.00 a month in compute resources to scrape domains I have targeted as part of my API research. This is something that will increase 3x in the next year as I expand my API search and discovery efforts. While it is very valuable to use GitHub and Bing API to uncover new and interesting domains, they don’t always give me very meaningful indexes of what each site contains. I prefer actually spidering the site and looking for meaningful words from my vocabulary like Swagger, OpenAPI, Documentation, etc. All the words the help me understand whether there is really an API there or just a blog post mentioning an API, or other ephemeral reference of API...

Looking For APIs By Industry

23 September 2019
I am working to expand the vocabulary I use to search for new APIs. I already have a pretty extensive set of keywords and phrases I have from mining the world of APIs over the last nine years, but I wanted to get more formal about how I find new and interesting APIs across as many industries as I possibly can. To help me in my effort I adopted the North American Industry Classification System (NAICS) as the official vocabulary I use for searching and organizing the businesses, organizations, tooling, APIs, and datasets I'm profiling as part of my research. Helping me standardize how I uncover new APIs, keeping my vocabulary in alignment with government agencies like Censuse and Labor, but also industry organizations, and the companies that operate within each business sector...

Remixing APIs Using Mock APIs In Postman Collections

23 September 2019
I had found the NAICS API the other day, but after I got using it I realized that there had been a newer release of the NAICS standard in 2017, which had occurred since the API was published. I also didn’t much care for the schema of the responses for the NAICS API—while it was complete, it wasn’t very applicable to what I was publishing. To simplify things, I took a stab redesigning the JSON response, taking what I feel is better advantage of the NAICS structure and layering the JSON along with the NAICS schema. This 2017 collection doesn’t completely replace the 2012 version, as the older version still has its place, but it does provide a more up to date look at the current business sector landscape...

Making An API Request To Update Examples In My API Documentation And Power My API Mocks

23 September 2019
As I was working to improve upon a couple of the API collections I’m defining, and define what constitutes a “complete enough” or “robust enough” collection, I noticed how the process within Postman is iterative, outcome based, and driven from actual requests and responses. Meaning a complete enough Postman collection is relative to the outcomes I’m looking for—things like documentation and mock APIs. To be able to achieve robust API documentation and mocks I simply need to add my API request, successfully make a call to my API defined, and save the response as part of my API collection. Then, once I’m ready, all I need to do to update my API documentation and generate API mocks is to hit publish for each of these desired outcomes...

A North American Industry Classification System (NAICS) API

20 September 2019
I am continually working to improve the vocabulary I use to search for APIs, and as part of my most recent investment I found myself forced to decide which industry classification I would be using, where I eventually settled on using the North American Industry Classification System (NAICS) because that is what the Census has adopted. There are other classification system like the Industry Classification Benchmark, Global Industry Classification Standard, International Standard Industrial Classification, Standard Industrial Classification, and the Thomson Reuters Business Classification, but I settled in on NAICS because I’ve worked with the folks over at Census on API strategy and ensuring my narrative dovetails with theirs is important to me...

Going Outside The API Echo Chamber With Your API Services And Tooling

20 September 2019
You ever feel like you just preach to the choir when evangelizing your API tool or service? I do. All the time! While crafting stories for the blog I am constantly burying topics that I find super interesting but realize the “normals” I’m interested in reaching just aren’t going to care. Of course, I don’t always focus on this audience but I’d say I prefer a 60% normals to 40% geek focus in my storytelling. With this in mind I’m investing some more energy in getting out of the echo chamber with my storytelling and spending more time at healthcare, financial, energy, automobile, home improvement, and other conferences catering to specific industries and verticals, rather than just hanging with my API pals at the same old events...

Publishing Your Early Canary (Beta) APIs In Their Own API Workspace

20 September 2019
Providing early access to your APIs is nothing new. It is something that all API providers should do whether they are publishing their APIs publicly or keeping them private for internal or partner use. However, I feel that the concept of API workspaces introduced by Postman provides you with an opportunity to segment off your APIs using different collections and make them available to an invite only audience. Realizing the concept of API workspaces allows you to easily create a working area dedicated to providing trusted users have access to early versions of your latest APIs. Leveraging the Postman platform as a conduit for engaging with your developers, and getting feedback on the designs and functionality of your APIs before they ever are generally released to the public...

Some Questions To Ask When Quantifying Your Organizational API Maturity

19 September 2019
The government agencies, institutions, organizations, and companies that I talk to on a regular basis always express their desire to get a handle on how to consistently deliver APIs across the API lifecycle, and ask me to help quantity their overall API maturity. They are looking for honest answers on how mature their approach is compared to other API providers , and companies that operate within the same business sector that they do. To help folks self-analyze, as well as help guide conversations I am having with them on the ground, I’ve drafted a short list of questions you can ask of your operations.I have broken down my questions into six separate areas of the API lifecycle which go a long ways towards defining how mature a company is, asking some of the questions that I am commonly asking new companies I am engaging with in workshops, consulting, and now working with Postman...

JSON Schema, Examples, And Postman Collections For 600 Schema.org Objects

19 September 2019
I wanted a ready to go supply of JSON examples from a variety of industries for me to use in my storytelling. No better place to begin with a project like this than with Schema.org, who provides a schema for just about anything you can think of. Karate Studio API anyone? I already had some scripts setup for creating Swagger 2.0 files from Schema.org, so I got to work retrofitting my Schema.org index to produce JSON Schema representations for each of the 600 objects in the index. Providing me with wealth of schema to choose from when I am defining new APIs, and telling stories about how APIs can make an impact across many different industries. After generating JSON Schema for 600 Schema.org objects, I worked to generate an example JSON for each of the objects, so I can demonstrate the schema as well as what it will look like while in use...

Publishing My FHIR API Collection As Documentation And Making Available In The Postman Network

19 September 2019
I had generated a Postman Collection for the Fast Healthcare Interoperability Resources (FHIR) the other day. Making a simple, easy to use, executable representation of any FHIR compliant API. I wanted to get intimate with the healthcare API standard so that I can better contribute specification and conversation, but I also wanted to use the specification to map out what industry level API contracts can be using Postman. Over time the Postman collection will evolve, and become more robust to contain the pieces of the puzzle that help move it from being an API definition to an API contract.After creating the collection I have now published my FHIR API Postman Collection as documentation and to the Postman API Network...

Business Users Do Not Search For API Solutions, They Just Search For Solutions

18 September 2019
As I craft stories for my blog I am always working to reach as wide possible audience as I can. It is one of the reasons I write so many stories, because the process helps me refine how I say things, and the words that I use. The process is a double edge sword because I want to reach my more technical audience by using very precise and meaningful terms, but I also want to reach out to a more business focused audience by using other more general and meaningful terms. This is a tough balance to find across any single post, so I tend to mix things up across posts, going down the technical rabbit hole on some, while keeping things high level for my business users on others. Keeping the site reaching as many folks as possible...

Being The Source Of API Truth At Your Organization

18 September 2019
When doing web services and API inventory at enterprise organizations I always come across one or two individuals or groups who are the keepers of the APIs, schema, and related knowledge and truth within the organization. It is the new version of the database keepers within large organizations, but instead of it just being just about data, it is about access to all types of resources, including data, content, algorithms, network, and other infrastructure elements. Being the API knowledgebase, directory, and source of truth within an organization takes a lot of work, but it is something that will pay off down the road when it comes to actually getting things done within an organization.I have had a database of APIs since 2011, but it has mostly been for my discovery only...

Is This The Offer API You Were Needing?

18 September 2019
Going from an idea for an API, to something you can actually share with another team member or stakeholder is historically something that can take hours, days or even weeks. Even if you manage to convey your idea to another or team member, you can’t always guarantee they’ll understand the API design as intended. The best way to convey your thoughts is to mock and document your API as if it was a real API, letting your intended audience actually review the documentation, make actual calls to the API, and provide feedback on each individual request, or even begin changing the design and implementation as part of their feedback.I wanted to see how easy it was to take a new idea for an API and make it something that can be easily shared and worked with using Postman...

Creating A Postman Collection For The Fast Healthcare Interoperability Resources (FHIR) Specification

18 September 2019
I have been working on healthcare APIs in government for over five years now, providing feedback regularly to the Blue Button API effort over at Health and Human Service (HHS), including having them speak at APIStrat last year in Nashville, and me speaking at the White House as part of the Blue Button 2.0 summit. I’m always looking for more ways that I can contribute to the healthcare API ecosystem, especially when it comes to investing in the Fast Healthcare Interoperability Resources (FHIR) specification. Now that I have bandwidth to invest in healthcare APIs again, I wanted to get my mind thinking about the potential of the FHIR specification, and find ways to help move the conversation forward...

Postman Has Documentation And Executable Collection For Their Own API

18 September 2019
A true test of any API service provider is whether or not they have an API. It is one of the most critical tests I have for any company who is selling a service to API providers. If you are sell services to people who provide APIs, and do not have your own API, I’m immediately skeptical about how you are playing the game. Postman passes a lot of quality and ethical tests I have, but the fact that they eat their own food, and has documentation and a machine readable Postman Collection demonstrates they get it.I’m looking to sync my API catalog a series of my Postman workspaces—ensuring that if an API in my catalog has an OpenAPI, it also has an up to date Postman Collection...

What Are You Doing With Postman?

17 September 2019
I am now immersed in all things Postman. After a week at Postman, attending POSTCON, and listening to how API developers are putting the API development environment, I have realized what a Swiss army knife the platform is. I get the core functionality of the application very well, and have used for several years. However, I only lightly understood the mocking, testing, monitors, runners, documentation, and other key features. I also was introduced to how pre and post scripts reduce friction, and the versatility, portability, and share-ability of Postman Collections. I’m beyond ecstatic to be studying and evangelizing all things Postman, and get to spend full time thinking deeply about how it can be applied across the API lifecycle...

I Will Be At The API Specifications Conference In Vancouver Next Month

17 September 2019
I’m happy to have the time in my new role to make it up to the API Specifications Conference next month. It really is the most important API conference out there, not just because it used to be my baby APIStrat, but because it is about the bedrock of the API sector—API definitions. As the API sector continues to go mainstream it is becoming increasingly important that we continue to standardize how we deliver APIs, and develop a common vocabulary for everything API. The discussions we will be having at the API Specification Conference will impact every stop along the API lifecycle, making it the most important API event out there in my opinion. Looking through the ASC program schedule I am seeing coverage of the entire API toolbox, covering REST ,Hypermedia, GraphQL, gRPC, and event-driven APIs, with representation for JSON Schema, JSON-LD, OData, OpenAPI, RAML, API Blueprint, and AsyncAPI...

It Is Hard To Not Just Get To Work Coding My API

17 September 2019
I need a couple of generic APIs for some storytelling and workshop materials. Just some basic example of web API in action managing some common everyday resources like notes, products, and company information. As a developer, I have to admit that it is hard to not just get to work sling’n code to bring an API to life. I’m a full blown API-first believer, and I still struggle with wanting to roll up my sleeves and being code first. As a developer, it is what we do, and it isn’t going to be easy to change behavior, but I find that I need to stop being my own worst enemy, and stop ignoring the benefits of being API-first and invest what in what I need to practice what I preach...

API-First Development

17 September 2019
This is part of my on-boarding work as Chief Evangelist with Postman. Part of my work to understand how Postman users are putting the platform to work is to process earch one of their use cases in a narrative format. The process helps these things stick in my mind, and since they are all driven by actual feedback and stories from their users, it populates my brain with relevant talking points when I'm engaging with customers. API-first is a philosophy and way of life that involves beginning every software capability as an API before you ever begin developer any user interface, or any other element. API-first ensures that all organizational capabilities are defined as simple, intuitive, well-designed API interfaces that can be used and reused across many different applications and systems...

API Workspace and Environment Management

15 September 2019
I have hundreds of collections within my Postman, but I’ve never done much collaboration with others in there until now. I find myself getting more organized with the Postman collections for API Evangelist, because I’m doing more coordination and sharing with the collections I maintain, but I’m also preparing to ramp up as Chief Evangelist for Postman. The process has highlighted for me the importance of API workspaces and environments along with our API definitions. These are two killer features of Postman which I think are concepts that should be ubiquitous across the API sector, and of course is a conversation that Postman will continue to play an increasingly important role...

The Stops Along The API Lifecycle That Postman Services

15 September 2019
I’m currently processing the common Postman use cases, and overlaying what the platform offers in context of historically what I’ve called my API lifecycle research. I plan on brining my vision more in alignment with Postman’s approach because I want to be telling consistent API lifecycle stories across API Evangelist and Postman, but also have things be in sync when I”m out speaking in public. I spent some time going through the Postman website and application and documented all of the stops along the API lifecycle they service, and then I took that and mapped it to the vocabulary I’ve been using to describe these areas as part of my own API lifecycle research...

She Asked “What Now” After Seeing Me Put Together My NASA API Collection

15 September 2019
I thoroughly enjoy engaging with my wife when it comes to APIs. She has been along for the entire API Evangelist ride, and she has absorbed more about APIs from listening to me talk about APIs than almost anyone else in the industry. While she tunes me out most of the time, she does listen and engage regularly, providing me with a pretty valuable sounding board to bounce ideas and concepts off from time to time. I’m cautious about how often I tap this resource, but when the time is right I will introduce her to an API concept I’m working with to see what she has to say. Yesterday was one of these days, and I took advantage of an opportunity to show her a Postman Collection I had made of several NASA APIs...

Giving A Postman Collection To Your Sales Team

15 September 2019
EasyPost spoke at the Postman User Conference (POSTCON) last week, and while they shared a number of very interesting stories, one that really stuck with me was about how they create Postman Collections for use by their non-technical sales teams. They put some of the common API driven tasks that a sales person would need to execute in the course of their daily work into each collection, and provided environments so that they didn’t have to mess around with authentication. Making for a pretty compelling tale of non-developers putting APIs to work, which is kind of the holy grail of API consumption—empowering average business users to realize the potential of APIs.I am going to be creating several proof of concepts to see if I can create Postman Collections that are valuable enough, and simple enough to be executed by a non-technical user...

Creating A NASA API Postman Collection And Environment

15 September 2019
This is a story derived from work to help develop a Postman Collection that could be used by the International Space Apps Challenge, establishing a machine readable definition for all the NASA APIs available at https://api.nasa.gov/ that can be used by participations in the challenge, helping developers quickly get up to speed with the valuable APIs NASA provides. The International Space Apps Challenge is in need of sponsors and participants to help make the event a success--please visit http://www.spaceappschallenge.org, or on Twitter at @SpaceApps to get involved.I met Katelyn Hertel (@Katers_Potaters) from the International Space Apps Challenge at POSTCON, and we got to talking about the interesting APIs NASA has, and how we can use Postman to make things easier for the developers who are participating in the global challenge...

I Preemptively Apologize For The Flood Of Postman Storytelling You Are About To Endure

15 September 2019
As some of you may have heard, I joined Postman as their Chief Evangelist last week. What does this mean? It means I will be telling a LOT of stories about my journey with the Postman team. Abhinav and team understand who I am and what I do, so not a whole lot will change, but like many phases of the last decade, my stories will be heavily focused on what I’m doing with Postman. If you know my style, you know it won’t be the usual product marketing storytelling you will find on an API service provider blog, it will be relevant stories about what I’m doing and seeing as I do my research. Postman gets the value of me doing my research, and the importance of it remaining generic enough that you can apply outside the Postman ecosystem, but because Postman is such a versatile Swiss army knife af an API development environment (ADE), much of my storytelling will involve Postman...

I Am Joining Postman As Their Chief Evangelist

12 September 2019
I am determined to continue taking my career to the next level. I’ve done well doing API Evangelist over the years, but I feel like I’ve gone as far as I can all by my lonesome. To level things up I feel I need more than just my words. I need some meaningful tooling, and collaboration with people who are building interesting and meaningful things with APIs to get to the place I envision in my minds eye. There are just a handful of startups out there who have both captured my API imagination, are making a meaningful impact on the API sector, and share my ethical view of the API sector, and one of them is Postman. I’ve supported Postman since they emerged on the scene, and as of today, I am joining their team as their Chief Evangelist...

AsyncAPI Version 2.0 Is Ready For Use

11 September 2019
The latest major version of the event-driven API specification format AsyncAPI is ready for production. The AsyncAPI community has been working hard in recent months to hammer out the next generation specification for helping us all better define a common definition for our event-driven APIs so that we can use across the API lifecycle. AsyncAPI is a sister specification to OpenAPI (fka Swagger), and while you can describe HTTP APIs using the format, it excels at helping us define our event-driven API infrastructure, and bring all the same documentation, mocking, testing, and other critical stops along an API lifecycle we will need to be successful.I’m going to be playing around with a couple implementations using AsyncAPI 2...

API Management For An Event-Driven API Landscape

11 September 2019
I’ve talked recently about a second coming of API management, which in my opinion is a wave that has several fronts. One of those fronts I see rolling out is in the area of event-driven API infrastructure. API management for request and response API infrastructure is pretty well defined, but the same concepts applied to event-driven infrastructure represents a pretty significant opportunity within this second evolution. Something that will span HTTP 1.1, HTTP/2, and TCP API implementations, providing the essential API management building blocks we might take for granted with HTTP 1.1 implementations, but as API providers expand their API toolbox to possess a variety of implementation patterns, they are beginning to look for consistent management capabilities across all their APIs...

Discovering The Confluent Schema Registry

10 September 2019
While spending time doing some research into schema management tooling I came across the Confluents Schema Registry. The schema management solutions is one of the first formal tools I’ve come across that is specifically designed for helping folks get their schema house in order when it comes to APIs. I’m sure there are others out there, but this was the first solution I've documented that addresses this in an API context as well as having an API, providing some of the critical features needed to make sense of the crazy schema mess enterprise organizations find themselves in.Here is the language from the Confluent website describing what the registry is all about: Confluent Schema Registry provides a RESTful interface for developers to define standard schemas for their events, share them across the organization and safely evolve them in a way that is backward compatible and future proof...

The API Reality In Our Heads Versus The Reality On The Ground

10 September 2019
I am spending some time grounding my views of the API landscape. Working my through all of my beliefs, and systematically blowing them to bits to see how they hold up against the stress of reality on the ground. This is something I’ve become very good at when it comes to my personal beliefs in recent years, and something I’ve been working to transfer to my professional world to help me keep a grip on what is going on. There are a number of reason why I fall prey to things that are not real in this game, and I’m pretty aware of the shady things that occur in the business world, but when it comes to technology I find the stories it whispers in my ear prove to be particularly enchanting and seem to go from whisper to truth at a velocity I don’t always understand...

Continue Pushing The API Documentation Conversation Forward

09 September 2019
I am been finally seeing the investment across the API sector I wanted to see when it comes to API documentation. There are multiple API definition driven API documentation offerings available on the market now. Both open source and high quality commercial services. A couple years after Swagger UI made it’s splash I began lobbing for more investment in open source API documentation tooling, and after four years I’m starting to see it beginning to happen. However, let’s not rest on laurels and make sure we keep investing and building on the momentum that we have established, and continue making API documentation more valuable to developers, but also to business users who are interested in putting API resources to work...

Bridging Grand Visions of an API Lifecycle With People on the Ground Being Successful In Their Work

09 September 2019
While my work as the API Evangelist can burn me out some of the time, I generally find it intellectually challenging. The work takes me from industry to industry, country to country, and to the highest levels of technology, and down to the work that goes on across development teams within companies. APIs are everywhere. Really, they are. They are impacting each one of our personal and professional lives, and this is one of the things that keeps me coming back doing what I do. The diversity of API implementations, and levels at which I can engage with the industry keeps me interested, continuously learning and producing.I enjoy thinking about the API space from the 250K level. It is interesting to study what is, what has been, and where things might be going when it comes to APIs...

API Evangelist Does Not Run On GitHub Anymore

06 September 2019
I migrated the main API Evangelist site off of GitHub the other day. The moved followed the migration of 100+ network sites of my API research a couple of weeks back. While I still have a handful of definitions and tooling published to GitHub, the migration of my main site signals a pretty huge shift in how I operate the site. I’ve operated the site 100% on GitHub since 2014, using YAML as the backend data store, and Jekyll to publish the pages, blogs, and data-driven pages. I have always done this to keep the site as open and accessible as I possibly can, sharing all of the data behind what I was doing However, in 2019, due to increased GitHub API rate limits, Jekyll build timeout limits, and shifts in the purpose of API Evangelist, I don’t see the value in me working to keep things open and available on GitHub anymore...

Where Do You Like Your API Complexity?

06 September 2019
I prefer my API complexity at the path, query, then schema levels of my API design—specifically in that order. I don’t mind a huge number of individual API calls to get the job done because I just script away this aspect of API complexity. However, I do fully understand that many folks prefer their complexity at the query and schema levels over having lots of individual paths. I find that developers love to rant about imperative API complexity, and in my experience the folks who don’t like path level API complexity are also some of the most vocal types of folks who are very confident that their way is the right way, when in reality, there is no right way—just the way YOUR consumers will want or need to access the API resources you are serving up...

API Management Should Not Just Limit Me, It Should Allow Me To Scale

06 September 2019
I do a lot of thinking about API management. After almost a decade of contemplating how we manage our API infrastructure, I feel it is still the most important stop along the API lifecycle. I don’t care how well designed, deployed, documented, and supported your APIs are, if you aren’t tuned in using API management, you aren’t going to be successful. API management provides you with the tools to you need to define and understand how your consumers will put your API resources to work. After almost 15 years of evolution, API management hasn’t changed too much, but there is one core capability I’d like to see evolve, expanding upon the often go to feature of API rate limiting...

The Different Ways API Providers Use The OpenAPI Servers Collection

05 September 2019
I was looking through the OpenAPI definitions I have harvested via some automated scripts I have running, and I came across an API definition that had a variety of URLs available for their APIs, making this part of the definition something I want to study more, identifying the common patterns in use. I harvest a growing number of OpenAPI definitions and Postman Collections to help me stay in tune with who the interesting API providers are, and documenting what the common building blocks of APIs are, helping shine a light on the useful practices that exist across API providers within many different industries. The OpenAPI server collection is beeing used to help automate switching between a variety of locations, and is most commonly used to differentiate between the different stages of an API server, as see I this example: This is just the most common usage of the OpenAPI server collection out there...

Controlling The Conversation Around Your Mobile Application APIs

03 September 2019
I have seen it play out over and over since I began monitoring the API conversation. Companies who launch APIs to power a mobile application but refuse to, or are unaware of how they should be controlling the conversation around public API infrastructure. The most common reason for this is that companies do not view the APIs behind their mobile applications as public APIs, and that somehow because they are buried within their mobile application, that they are safe from hackers. Completely clueless of the fact that anyone can run any mobile application through a proxy and reverse engineer the API infrastructure behind any mobile application.Mobile application platforms that do not control the conversation around their public APIs are the ones who end up having security incidents down the road...

Benefits Of Treating My API Infrastructure As API-First

26 August 2019
Most API providers I speak with see the value of consistently delivering API infrastructure to power desktop, web, mobile, device, and network applications. Less than 10% of these providers see the API infrastructure that powers their APIs, and ultimately their applications as APIs. Meaning, these providers do not view every stop along the API lifecycle as a set of APIs, ensuring that your API definitions, design, mocking, deployment, management, monitoring, testing, orchestration, security, and documentation all have APIs, and are able to be governed programmatically. Mostly it is because they are just getting started on their API journey and / or they just don’t have the bandwidth to be able to step back and look holistically at what they are trying to accomplish...

Doing A Diff Between Available Web, Mobile and Public APIs

22 August 2019
I spend a lot of time running web and mobile applications through a proxy to reverse engineer their APIs. I generally use Charles Proxy for routing my desktop, web, and mobile traffic through, which then automatically saves a JSON dump of sessions every five minutes, and syncs with Dropbox via my shared folders. From there I have a schedule service that will look in the shared Dropbox folder every hour, sift through the Charles Proxy JSON dump, and look for JSON, XML, CSV, and other common machine readable formats—which are then converted into OpenAPI definitions. Allowing me to reverse engineer desktop, web, and mobile applications as I use them, and map the API surface area for these targeted applications...

An API Policy Domain Specialist At Twitter

22 August 2019
There are some jobs on the Internet I apply for no matter what my current situation is, and an API policy domain specialist at Twitter was one of them that popped up recently. I applied for the job within the first couple of hours after it came out, but haven’t heard from them. I can speculate on the reasons why, but I think a story about the job posting itself is actually more interesting, so I’ll focus there. It is the first time I’ve seen a job posting for this role, but I think it will eventually become a required role in the future for any company with a public API—-that is, if companies want avoid the trouble Twitter is going through right now, which again, is making Twitter the poster child for how to do APIs both right and wrong...

Multiple Overlapping API Life Cycle(s)

21 August 2019
One of the toughest parts about teaching people about APIs is that there are many different views of what the API life cycle can be depending on who you are, and what your intentions are. As an advocate or evangelist for a single API you are speaking externally to the API consumption life cycle, but internally you are focused on the API delivery life cycle. As an API Evangelist for many APIs, targeting providers, consumers, and anyone else who comes along, I find it a constant challenge to properly speak to my intended audience. One problematic part of my storytelling I regularly see emerge is that I speak of a single API life cycle, where in reality there are many overlapping life cycles. So, to help me think through all of this I wanted to explore what these overlapping tracks might be—coming up with four distinct iterations of overlapping API building blocks...

Human Empathy Is One Of My Most Important API Outreach Tools

20 August 2019
I am an empathic human being. It is one of my top strengths, as well as one of my top weaknesses. It is also one of the most important tools in my API toolbox. Being able to understand the API experience from the position of different people throughout the world of APIs is a cornerstone of the API Evangelist brand. Personally, I find APIs themselves to be empathy triggering, and something that has regularly forced me out of my silos, then allowing me t put myself in the shoes of my consumers. Something that when realized in a perpetual fashion can become a pretty powerful force for dialing in the services you offer, and establish, maintain, and strengthen connections with other people within the community...

The API Conferences I Am Tracking On For The Fall

20 August 2019
As we approach the fall it is time to begin thinking about the conference season, and what the most relevant API conferences are. I haven’t been doing any events this year, but staying in tune with the conference circuit has always been important to my work. Who knows, maybe I will be spend some more time investing in API related events after taking a break for six month. When it comes to API events and conferences, here is what I am tracking on.

A Second Wave of API Management is Going On

19 August 2019
I fully surfed the first wave of API management. API Evangelist began by researching what Mashery, Apigee, and 3Scale had set into motion. API Evangelist continued to has exist through funding from 3Scale, Mulesoft, WSO2, and continues to exist because of the support of next generation providers like Tyk. I intimately understand what API management is, and why it is valuable to both API providers and consumers. API management is so relevant as infrastructure it is now baked into the AWS, Azure, and Google Clouds. However, if you listen to technological winds blowing out there, you will mostly hear that the age of API management is over with, but in reality it is just getting started. The folks telling these tales are purely seeing the landscape from an investment standpoint, and not from an actual boots on the ground within mainstream enterprise perspective—something that is going to burn them from an investment standpoint, because they are going to miss out on the second wave of API management that is going on...

Postman Collection As A Single Quantifiable, Shareable, Executable Unit Of Representation For Any Digital Capability

19 August 2019
In my world API definitions are more valuable than code. Code is regularly thrown away and rewritten. API definitions hold the persistent detail of what an API delivers, and contain all of the proprietary value when they are properly matured. OpenAPI has definitely risen to the top when it comes to which API definition formats you should be using, however, Postman Collections have one critical ingredient that makes them ultimately more usable, sharable, and meaningful to developers—-environmental context. This small but important difference is what makes Postman Collections so valuable as a single quantifiable, shareable, executable unit of representation for any digital capability. Like OpenAPI, Postman Collections describe the surface area of a web API, but they have that added layer to describe the environment you are running in, which makes it much more of a run-time and execute-time experience...

Four Phases Of Internal API Evangelism

16 August 2019
General evangelism around what APIs are, as well as more precise advocacy around specific APIs or groups of API resources takes a lot of work, and repetition. Even as a seasoned API evangelist I can never assume my audience will receive and understand what it is that I am evangelizing, and I regularly find myself having to reassess the impact (or lack of) that I’m making, retool, refresh, and repeat my messaging to get the coverage and saturation I’m looking for. After a decade of doing this, I cannot tell which is more difficult, internal or external public evangelism, but I do find that after almost 10 years, I’m still learning from each audience I engage with—-proving to me that no single evangelism strategy will ever reliably work, and I need a robust, constantly evolving toolbox if I am going to be successful...

Seeing API Consumers As Just The Other Ones

16 August 2019
As API providers, it can be easy to find ourselves in a very distant position from the consumers of our APIs. In recent weeks I have been studying the impacts of behavioral approaches to putting technology to work, something that has led me to the work of Max Meyer, and his Psychology of the Other-One (1921). I haven’t read his book yet, but have finished other works citing his work on how to “properly” study how animals (including humans) behave. While the psychological impact of all of this interests me, I’m most interested in how this perspective has amplified and driven how we use technology, and specifically how APIs can be used to create or bridge the divide between us (API providers) and our (API consumers)...

An API Platform Reliability Engineer At Stripe

15 August 2019
I find that the most interesting and telling API building blocks come out of the companies who are furthest along in their API journey, and have made the conscious effort to heavily invest in their platforms. I try to regularly visit API platforms who are doing the most interesting work on a regular basis, because I am almost always able to find some gem of an approach that I can showcase here on the blog. This weeks gem is from API rockstar Stripe, and their posting for a reliability engineer for their API platform. Here is a summary from their job posting: As a Reliability Engineer, you’ll help lead an active area of high impact by defining and building proactive ways to further hone the reliability of our API...

An Observable Regulatory Provider Or Industry API Management Gateway

15 August 2019
I wrote a separate piece on an API gateway specification standard recently, merging several areas of my research and riffing on a recent tweet from Sukanya Santhanam (@SukanyaSanthan1). I had all these building blocks laying around as part of my research on API gateways, but also from the other areas of the API lifecycle that I track on. Her tweet happened to coincide with other thoughts I had simmering, so I wanted to jump on the opportunity to publish some posts, and see if I could slow jam a conversation in this area. Now, after I defined what I’d consider to be a core API gateway set of building blocks, I wanted to take another crack at refining my vision for how we make it more observable and something that could be used as a tech sector regulatory framework...

A Look At Behavioral API Patents

05 August 2019
I have been studying uses of behavioral technology lately. Riffing off my partner in crimes work on the subject, but putting my own spin on it, and adding APIs (of course) into the mix. Applying on of my classic techniques, I figured I’d start with a patent search for “behavioral application programming interfaces”. I find patents to be a “wonderful” source of inspiration and understanding when it comes to what is going on with technology. Here are the top results for my patent search, with title, abstract, and a link to understand more about each patent. User-defined coverage of media-player devices on online social networks In one embodiment, a method includes detecting, by a media-player device including multiple antennas, a client system of a user is within a wireless communication range of the media-player device...

Some Of The API Gateway Building Blocks

05 August 2019
The inspiration for this post wasn’t fully mine, I’m borrowing and building upon what Sukanya Santhanam (@SukanyaSanthan1) tweeted out the other day. It is a good idea, and something that should be open sourced and moved forward. I’ve been studying with API management since 2010, and using gateways for over 15 years. I’ve watched gateways evolve, and partnered regularly with API management and gateway providers (Shout out to Tyk). Modern API gateways aren’t your grandfather’s SOA tooling, they’ve definitely gone through several iterations. While I still prefer hand rolling and forging my APIs out back in my woodshed on an anvil, I find myself working with a lot of different API gateways lately...

Didn’t We Already Do That?

02 August 2019
When you are in the API game you hear this phrase a lot, “didn’t we already do that?”. It is a common belief system that because something was already done, that it means it will not work ever again. When you are operate solely in a computational world, you tend to see things as 1s and 0s, and if something was tried and “didn’t work”, there is no resetting of that boolean switch for some reason. We excel at believing things are done, without ever unpacking why something failed, or how the context may have changed. One of the things I’m going to do over the next couple months is go through the entire SOA toolbox and take accounting of everything we threw away, and evaluate what the possible reasoning were behind it—-good and bad...

Reverse Engineering Mobile APIs To Show A Company Their Public APIs

02 August 2019
One story I tell a lot when talking to folks about APIs, is how you can reverse engineer a mobile phone to map out the APIs being used. As the narrative goes, many companies that I talk with claim they do not have any public APIs when first engage with them. Then I ask them, “Do you have any mobile applications?”. To which the answer is almost always, “Yes!”. Having anticipated this regular conversation, if I am looking to engage with a company in the area of API consulting, I will have made the time to reverse engineer their application to produce a set of OpenAPI definitions that I can then share with them, showing that they indeed have public APIs. The process isn’t difficult, and I’ve written about this several times...

About Giving Away API Knowledge For Free

01 August 2019
I’m in the business of providing access to the API knowledge accumulated over the last decade. Despite what many people claim, I do not know everything about APIs, but after a decade I have picked up a few things along the way. Historically, I have really enjoyed sharing my knowledge with people, but I’m increasingly becoming weary of sharing to openly because of the nature of how business gets conducted online. Specifically, that there are endless waves of folks who want to tap what I know without giving anything in return, who work at companies who enjoy a lot of resources. I know people have read the startup handbook, which tells them to reach out to people who know and get their view, but when everyone does this, and doesn’t give anything in return, it is, well…I guess business as usual? Right? ;-( Taking a sampling from the usual week in my inbox, I’ll get a handful of requests reflecting these personas: Analysts / Consultants - Other analysts reaching out to share information, and get my take on what I’m seeing...

The Future Of APIs Will Be In The Browser

01 August 2019
I have been playing with the new browser reporting API lately, and while it isn’t widely supported, it does work in Chrome, and soon Firefox. I won’t go into too much technical detail, but the API provides an interesting look at reporting on APIs usage in the browser. Offering a unique view into the shadows of what is happening behind the curtain in our browser when we are using common web applications each day. I have been proxying my web traffic for a long time to produce a snapshot at the domains who are operating beneath the covers, but it is interesting for browsers to begin baking in a look at the domains who are violating, generating errors, and other shenanigans. As I’m contemplating the API discovery universe I can’t help but think of the how “API innovation” is occurring within the browser...

The Challenges Of API Discovery Conversations Being Purely Technical

31 July 2019
Ironically one of the biggest challenges facing API discovery on the web, as well as within the enterprise, is that most conversations focus purely on the technical, rather than the human and often business implications of finding and putting APIs to work. The biggest movement in the realm of API discovery in the last couple years has been part of the service mesh evolution of API infrastructure, and how your gateways “discover” and understand the health of APIs or microservices that provide vital services to applications and other systems. Don’t get me wrong, this is super critical, but it is more about satisfying a technical need, which is also being fueled by an investment wave-—it won’t contribute to much to the overall API discovery and search conversation because of it’s limited view of the landscape...

Differences Between API Observability Over Monitoring, Testing, Reliability, and Performance

31 July 2019
I’ve been watching the API observability coming out of Stripe, as well as Honeycomb for a couple years now. Then observability of systems is not a new concept, but it is one that progressive API providers have embraced to help articulate the overall health and reliability of their systems. In control theory, observability is a measure of how well internal states of a system can be inferred from knowledge of its external outputs. Everyone (except me) focuses only on the modern approaches for monitoring, testing, performance, status, and other common API infrastructure building blocks to define observability. I insist on adding the layers of transparency and communication, which I feel are the critical aspects of observability—-I mean if you aren’t transparent and communicative about your monitoring, testing, performance, and status, does it really matter? I work to define observability as a handful of key API building blocks that every API provider should be investing in: Monitoring - Actively monitoring ALL of your APIs to ensure they are up and running...

Peer API Design Review Sessions

30 July 2019
Public APIs have always benefitted from something that internal APIs do not always received—-feedback from other people. While the whole public API thing didn’t play out as I originally imagined, there is still a lot of benefit in letting other see, and provide open feedback on your API. It is painful for many developers to receive feedback on their API, and it is something that can be even more painful when it is done publicly. This is why so many of us shy away from establishing feedback loops around our APIs. It is hard work to properly design, develop, and then articulate our API vision to an external audience. It is something I understand well, but still suffer from when it comes to properly accessioning peer review and feedback on my API designs...

API For Processing Common Logging Formats And Generating OpenAPI Definitions

30 July 2019
I’ve invested a lot of time in the last six months into various research, scripts, and tooling to help me with finding APIs within the enterprise. This work is not part my current role, but as a side project to help me get into the mindset of how to help the enterprise understand where their APIs are, and what APIs they are using. Almost every enterprise group I have consulted for has trouble keeping tabs on what APIs are being consumed across the enterprise, and I’m keen on helping understand what the best ways are to help them get their API houses in order. While there are many ways to trace out how APIs are being consumed across the enterprise, I want to start with some of the basics, or the low hanging when it came to API logging within the enterprise...

API Storytelling Within The Enterprise

28 July 2019
Storytelling is important. Storytelling within the enterprise is hard. Reaching folks on the open web is hard work to, but there is usually an audience that will eventually tune in, and over time you can develop and cultivate that audience. The tools you have at your disposal within the enterprise are much more prescribed and often times dictated–even controlled. I also find that they aren’t always as effective as they are made out to be, with the perception being one thing, and the reach, engagement, and noise being then much harder realities you face when trying to get a message out. Email might seem like a good idea, and is definitely a critical tool when reaching specific individuals or groups, but as a general company wide thing, it quickly becomes exponentially ineffective with each person you add on as CC...

APIs and Browser Bookmarklets

24 July 2019
I have quite a few API driven bookmarklets I use to profile APIs. I recently quit using Google Chrome, so I needed to migrate all of them to Firefox. I saw this work as an opportunity to better define and organize them, as they had accumulated over the years without any sort of strategy. When I need some new functionality in my browser I would create a new API, and craft a bookmarklet that would accomplish whatever I needed. I wish I had more browser add-on development skills, something I regular try to invest in, but I find that bookmarklets are the next best thing when it comes to browser and API interactions. There are a number of tasks I am looking to accomplish when I’m browsing the web pages of an API provider...

Absolutism Around API Tools Increases Friction And Failure

24 July 2019
I know you believe your tools are the best. I mean, from your vantage point, they are. I also know that when you are building a new API tool, your investors want you to position your tooling as the best. The one solution to rule them all. They want you to work hard to make your tools the best, but also make sure and demonize other tooling as being inferior, out of date, and something the dinosaurs use. I know this absolute belief in your tooling feels good and right, but you are actually creating friction for your users, and potentially failure or at least conflict within their teams. Absolutism, along with divide and conquer strategies for evangelizing API tooling works for great short term financial strategies, but doesn’t do much to help us on the ground actually developing, managing, and sustaining APIs...

The Higher Level Business Politics That I Am Not Good At Seeing In The API Space

23 July 2019
I have built successful startups. I’m good at the technology of delivering new solutions. I am decent at understanding and delivering much of business side of bringing new technological solutions to market. What I’m not good at is the higher level business politics that occur. These are the invisible forces behind businesses that I’m good at seeing, playing in, and almost always catch me off guard, too late, or just simply piss me off that they are going on behind the scenes. Unfortunately it is in this realm where most of the money is to be made doing APIs, resulting in me being written out of numerous successful API efforts, because I’m not up to speed on what is going on. Startups are great vehicles for higher level economic strategies...

API Provider And Consumer Developer Portals

23 July 2019
I’ve been studying API developer portals for almost a decade. I’ve visited the landing pages, portals, websites, and other incarnations from thousands of API providers. I have an intimate understanding of what is needed for API providers to attract, support, and empower API consumers. One area I’m deficient in, and I also think it reflects a wider deficiency in the API space, is regarding how to you make an API portal service both API providers and API consumers. Providing a single portal within the enterprise where everyone can come and understand how to deliver or consume an API. There are plenty of examples out there now when it comes to publishing an API portal for your consumers, but only a few that show you how to publish an API...

The Role Having Awareness Of Your API Traffic Plays In API Security

22 July 2019
One of the biggest reasons we adopt new technology, and justify the development of new technology, is we do not want to do the heavy lifting when it comes to what we already have in place. A common illness when it comes to API security that I’ve been battling since 2015 is that you will have API security addressed once you adopted an API management solution. Your APIs require API keys, and thus they are secure. No further work necessary. The unwillingness or lack of knowledge regarding what is needed next, leaves a vacuum for new technology providers to come in and sell you the solution for what is next, when you should be doing more work to use the tools you already have. When it comes to API management, most vendors sold it as purely a security solution, and when companies implement it they become secure...

Happy Path API Testing Bias

22 July 2019
I see a lot of happy path bias when it comes to the development of APIs, but specifically when it comes to crafting testing to ensure APIs are delivering as expected. Happy path is a term used in testing to describe the desired outputs a developer and product owner is looking for. Making the not so happy path being about testing for outcomes that a developer and product owner is not wanting to occur. When it comes to API development most developers and product owners are only interested in the happy path, and will almost always cut corners, minimize the investment in, or completely lack an imagination when it comes to less than happy path API testing. There are many reasons why someone will have a bias towards the happy path when developing an API...

What Makes You Think Your GraphQL Consumers Will Want To Do The Work

18 July 2019
Data work is grueling work. I’ve been working with databases since my first job developing student information databases in 1988 (don’t tell my wife). I’ve worked with Cobol, Foxpro, SQL Server, Filemaker, Access, MySQL, PostGres, and now Aurora databases over the last 30 years. I like data. I can even trick myself into doing massive data and schema refinement tasks on a regular basis. It is still grueling work that I rarely look forward to doing. Every company I’ve worked for has a big data problem. Data is not easy work, and the more data you accumulate, the more this work grows out of control. Getting teams of people to agree upon what needs to happen when it comes to schema and data storage, and actually execute upon the work in a timely, cost effective, and efficient way is almost always an impossible task...

What Is An Application?

18 July 2019
I have struggled asking this question in many discussions I’ve had around the world, at technology conferences, on consulting projects, and in the back rooms of dimly lit bars. What is an application? You get ten different answers if you ask this question to ten different people. I’d say the most common response is to reference the applications on a mobile device. These are the relevant. Most accessible. The most active and visible form of application in our modern life. Older programmers see them as desktop applications, where younger programmers see them as web applications, with varying grades of server applications in between. If you operate at the network layer, you’ve undoubtedly bastardized the term to mean several different things...

Paying for API Access

17 July 2019
APIs that I can’t pay for more access grinds my gears. I am looking at you GitHub, Twitter, Facebook, and a few others. I spend $250.00 to $1500.00 a month on my Amazon bill, depending on what I’m looking to get done. I know I’m not the target audience for all of these platforms, but I’m guessing there is a lot more money on the table than is being acknowledged. I’m guessing that the reason companies don’t cater to this, is that there are larger buckets of money involved in what they are chasing behind the scenes. Regardless, there isn’t enough money coming my way to keep my mouth shut, so I will keep bitching about this one alongside the inaccessible pricing tiers startups like to employ as well...

The Many Ways In Which APIs Are Taken Away

17 July 2019
APIs are notorious for going away. There are so many APIs that disappear I really stopped tracking on it as a data point. I used keep track of APIs that were shuttered so that I could play a role in the waves of disgruntled pitchfork mobs rising up in their wake–it used to be a great way to build up your Hacker News points! But, after riding the wave a couple hundred waves of APIs shuttering, you begin to not really not give a shit anymore—-growing numb to it all. API deprecation grew so frequent, I wondered why anyone would make the claim that once you start an API you have to maintain it forever. Nope, you can shut down anytime. Clearly. In the real world, APIs going away is a fact of life, but rarely a boolean value, or black and white...

Hoping For More Investment In API Design Tooling

16 July 2019
I was conducting an accounting of my API design toolbox, and realized it hasn’t changed much lately. It is still a very manual suite of tooling, and sometimes services, that help me craft my APIs. There are some areas I am actively investing in when it comes to API design, but honestly there really isn’t that much new out there to use. To help me remember how we got here, I wanted to take a quick walk through the history of API design, and check in on what is currently available when it comes to investing in your API design process. API design has historically meant REST. Many folks still see it this way. While there has been plenty of books and articles on API design for over a decade, I attribute the birth of API design to Jakub and Z at Apiary (https://apiary...

Imperative, Declarative, and Workflow APIs

16 July 2019
At every turn in my API work I come across folks who claim that declarative APIs solutions are superior to imperative ones. They want comprehensive, single implementation, do it all their way approaches, over granular, multiple implementation API calls that are well defined by the platform. Declarative calls allow you to define a single JSON or YAML declaration that can then be consumed to accomplish many things, abstracting away the complexity of doing those many things, and just getting it done. Imperative API interfaces require many individual API calls to tweak each and every knob or dial on the system, but is something that is often viewed as more cumbersome from a seasoned integrator, but for newer, and lower level integrators a well designed imperative API can be an important lifeline...

What Is An API Contract?

15 July 2019
I am big on regularly interrogating what I mean when I use certain phrases. I’ve caught myself repeating and reusing many hollow, empty, and meaningless phrases over my decade as the API Evangelist. One of these phrases is, “an API contract”. I use it a lot. I hear it a lot. What exactly do we mean by it? What is an API contract, and how is it different or similar to our beliefs and understanding around other types of contracts? Is it truth, or is just a way to convince people that what we are doing is just as legitimate as what came before? Maybe it is even more legitimate, like in a blockchain kind of way? It is an irreversible, unbreakable, digital contract think bro! If I was to break down what I mean when I say API contract, I’d start with being able to establish to a shared articulation of what an API does...

My Primary API Search Engines

12 July 2019
I am building out several prototypes for the moving parts of an API search engine I want to build, pushing my usage of APIs.json and OpenAPI, but also trying to improve how I define, store, index, and retrieve valuable data about thousands of APIs through a simple search interface. I’m breaking out the actual indexing and search into their own areas, with rating system being another separate dimension, but even before I get there I have to actually develop the primary engines for my search prototypes, feeding the indexes with fresh signals of where APIs exist across the online landscape. There isn’t an adequate search engine out there, so I’m determined to jumpstart the conversation with an API search engine of my own...

Taking A Fresh Look At The Nuance Of API Search

11 July 2019
I have a mess of APIs.json and OpenAPI definitions I need to make sense of. Something that I could easily fire up an ElasticSearch instance, point at my API “data lake”, and begin defining facets and angles for making sense of what is in there. I’ve done this with other datasets, but I think this round I’m going to go a more manual route. Take my time to actually understand the nuance of API search over other types of search, take a fresh look at how I define and store API definitions, but also how I search across a large volume of data to find exactly the API I am looking for. I may end up going back to a more industrial grade solution in the end, but I am guessing I will at least learn a lot along the way...

Navigating API Rate Limit Differences Between Platforms

10 July 2019
I always find an API providers business model to be very telling about the company’s overall strategy when it comes to APIs. I’m currently navigating the difference between two big API providers, trying to balance my needs spread across very different approaches to offering up API resources. I’m working to evolve and refine my API search algorithms and I find myself having to do a significant amount of work due to the differences between GitHub and Microsoft Search. Ironically, they are both owned by the same company, but we all know their business models are seeking alignment as we speak, and I suspect my challenges with GitHub API is probably a result of this alignment...

The JSON Schema Tooling In My Life

10 July 2019
I am always pushing for more schema order in my life. I spend way too much time talking about APIs, when a significant portion of the API foundation is schema. I don’t have as many tools to help me make sense of my schema, and to improve them as definitions of meaningful objects. I don’t have the ability to properly manage and contain the growing number of schema objects that pop up in my world on a daily basis, and this is a problem. There is no reason I should be making schema objects available to other consumers if I do not have a full handle on what schema objects exist, let alone a full awareness of everything that has been defined when it comes to the role that each schema object plays in my operations...

The Details Of My API Rating Formula

09 July 2019
Last week I put some thoughts down about the basics of my API rating system. This week I want to go through each of those basics, and try to flesh out the details of how I would gather the actual data needed to rank API providers. This is a task I’ve been through with several different companies, only to be abandoned, and then operated on my own for about three years, only to abandon once I ran low on resources. I’m working to invest more cycles into actually defining my API rating in a transparent and organic way, then applying it in a way that allows me to continue evolving, while also using to make sense of the APIs I am rapidly indexing. First, I want to look at the API-centric elements I will be considering when looking at a company, organization, institution, government agency, or other entity, and trying to establish some sort of simple rating for how well they are doing APIs...

Thinking Differently When Approaching OpenAPI Diffs And Considering How To Layer Each Potential Change

08 July 2019
I have a lot of OpenAPI definitions, covering about 2,000 separate entities. For each entity, I often have multiple OpenAPIs, and I am finding more all the time. One significant challenge I have in all of this centers around establishing a master “truth” OpenAPI, or series of definitive OpenAPIs for each entity. I can never be sure that I have a complete definition of any given API, so I want to keep vacuuming up any OpenAPI, Swagger, Postman, or other artifact I can, and compare it with the “truth” copy” I have on indexed. Perpetually layering the additions and changes I come across while scouring the Internet for signs of API life. This perpetual update of API definitions in my index isn’t easy, and any tool that I develop to assist me will be in need constant refinement and evolution to be able to make sense of the API fragments I’m finding across the web...

Why The Open Data Movement Has Not Delivered As Expected

05 July 2019
I was having a discussion with my friends working on API policy in Europe about API discovery, and the topic of failed open data portals came up. Something that is a regular recurring undercurrent I have to navigate in the world of APIs. Open data is a subset of the API movement, and something I have first-hand experience in, building many open data portals, contributing to city, county, state, and federal open data efforts, and most notably riding the open data wave into the White House and working on open data efforts for the Obama administration. Today, there are plenty of open data portals. The growth in the number of portals hasn’t decreased, but I’d say the popularity, utility, and publicity around open data efforts has not lived up to the hype...

API Interoperability is a Myth

03 July 2019
There are a number of concepts we cling to in the world of APIs. I’ve been guilting of inventing, popularizing, and spreading many myths in my almost decade as the API Evangelist. One of them that I’d like to debunk and be more realistic about is when it comes to API interoperability. When you are focused on just the technology of APIs, as well as maybe the low-level business of APIs, you are an API interoperability believer. Of course everyone wants API interoperability, and that all APIs should work seamlessly together. However, if you at all begin operating at the higher levels of the business of APIs, and spend any amount of time studying the politics of why and how we do APIs at scale, you will understand that API interoperability is a myth...

Your API and Schema Is That Complex Because You Have Not Done The Hard Work To Simplify

02 July 2019
I find myself looking at a number of my more complex API designs, and saying to myself, “this isn’t complicated because it is hard, it is complicated because I did not spend the time required to simplify it appropriately”. There are many factors contributing to this reality, but I find that more often than not it is because I’m over-engineering something, and I am caught up in the moment focusing on a purely computation approach, and not considering the wider human, business, and other less binary aspects of delivering APIs. While I am definitely my own worst enemy in many API deliver scenarios, I’d say there are a wide range of factors that are influencing how well, or poorly that I design my API resources, with just a handful of them being: Domain - I just do not have the domain knowledge required to get the job done properly...

The Basics of My API Rating Formula

01 July 2019
I have been working on various approaches to rating APIs since about 2012. I have different types of algorithms, even having invested in operating one from about 2013 through 2016, which I used to rank my daily intake of API news. Helping me define what the cream on top of each industry being impacted by APIs, while also not losing site of interesting newcomers to the space. I have also had numerous companies and VCs approach me about establishing a formal API rating system—many of whom concluded they could do fairly easily and went off to try, then failed, and gave up. Rating the quality of APIs is subjective and very hard. When it comes to rating APIs I have a number of algorithms to help me, but I wanted to step back and think of it from a more simpler human vantage point, and after establishing a new overall relationship with the API industry...

The Complexity of API Discovery

01 July 2019
I can’t get API discovery out of my mind. Partly because I am investing significant cycles in this area at work, but it is also something have been thinking about for so long, that it is difficult to move on. It remains one of the most complex, challenging, and un-addressed aspects of the way the web is working (or not working) online today. I feel pretty strongly that there hasn’t been investment in the area of API discovery because most technology companies providing and consuming APIs prefer things be un-discoverable, for a variety of conscious and un-conscious reasons behind these belief systems.
 What API Discovery Means? Depends On Who You Are… One of the reasons that API discovery does not evolve in any significant ways is because there is not any real clarity on what API discovery is...

Why Schema.org Does Not See More Adoption Across The API Landscape

25 June 2019
I’m a big fan of Schema.org. A while back I generated an OpenAPI 2.0 (fka Swagger) definition for each one and published to GitHub. I’m currently cleaning up the project, publishing them as OpenAPI 3.0 files, and relaunching the site around it. As I was doing this work, I found myself thinking more about why Schema.org isn’t the goto schema solution for all API providers. It is a challenge that is multi-layered like an onion, and probably just as stinky, and will no doubt leave you crying. First, I think tooling makes a big difference when it comes to why API providers haven’t adopted Schema.org by default across their APIs. If more API design and development tooling would allow for the creation of new APIs using Schema...

Avoiding Complexity and Just Deploying YAML, JSON, and CSV APIs Using GitHub or GitLab

24 June 2019
I find that a significant portion of I should be doing when defining, designing, developing, and delivering an API is all of avoiding complexity. Every step away along the API journey I am faced with opportunities to introduce complexity, forcing me to constantly question and say no to architectural design decisions. Even after crafting some pretty crafty APIs in my day, I keep coming back to JSON or YAML within Git, as the most sensible API architectural decision I can make. Git, with JSON and YAML stored within a repository, fronted with a Jekyll front-end does much of what I need. The challenge with selling this concept to others is that it is a static publish approach to APIs, instead of a dynamic pull of relevant data...

Organizing My APIs Using OpenAPI Tags

19 June 2019
I like my OpenAPI tags. Honestly, I like tags in general. Almost every API resource I design ends up having some sort of tagging layer. Too help me organize my world, I have a centralized tagging vocabulary that I use across my JSON Schema, OpenAPI, and AsyncAPI, to help me group, organize, filter, publish, and maintain my catalog of API and schema resources. The tag object for the OpenAPI specification is pretty basic, allowing you to add tags for an entire API contract, as well as apply them to each individual API method. Tooling, such as API documentation uses these tags to group your API resources, allowing you to break down your resources into logical bounded contexts. It is a pretty basic way of defining tags, that can go a long ways depending on how creative you want to get...

Doing The Hard Work To Define APIs

17 June 2019
Two years later, I am still working to define the API driven marketplace that is my digital self. Understanding how I generate revenue from my brand (vomits in mouth a little bit), but also fight off the surveillance capitalists from mining and extracting value from my digital existence. It takes a lot of hard work to define the APIs you depend on to do business, and quantify the digital bits that you are transacting on the open web, amongst partners, and unknowingly with 3rd parties. As an individual, I find this to be a full time job, and within the enterprise, it is something that everyone will have to own a piece of, which in reality, is something that is easier said than done. Convincing enterprise leadership of the need to be aware of every enterprise capability being defined at the network, system, or application level is a challenge, but doable...

There Is No Single Right Way To Do APIs

16 June 2019
My time working in the API sector has been filled with a lot of lessons. I researched hard, paid attention, and found a number of surprising realities emerge across the API landscape. The majority of surprises have been in the shadows caused by my computational belief scaffolding I’ve been erecting since the early 1980s. A world where there has to be absolutes, known knowns, things are black and white, or more appropriately 1 or 0. If I studied all APIs, I’d find some sort of formula for doing APIs that is superior to everyone else’s approach to doing APIs. I was the API Evangelist man–I could nail down the one right way to do APIs. (Did I mention that I’m a white male autodidact?) I was wrong...

API Definitions Are Important

12 June 2019
I found myself scrolling down the home page of API Evangelist and thinking about what topic(s) I thought were still the most relevant in my mind after not writing about APIs for the last six months. Hands down it is API definitions. These machine and human readable artifacts are the single most important thing for me when it comes to APIs I’m building, and putting to work for me. Having mature, machine readable API definitions for all API that you depend on, is essential. It also takes a lot of hard work to make happen. It is why I went API define first a long time ago, defining my APIs before I ever get to work designing, mocking, developing, and deploying my APIs. Right now, I’m heavily dependent on my: JSON Schema - Essential for defining all objects being used across API contracts...

API Evangelist Is Open For Business

10 June 2019
After six months of silence I've decided to fire API Evangelist back up again. I finally reached a place where I feel like I can separate out the things that caused me to step back in the first place. Mostly, I have a paycheck now, some health insurance, and I don't have to pretend I give a shit about APIs, startups, venture capital, and the enterprise. I'm being paid well to do an API job. I can pay my rent. I can go to the doctor when my health takes a hit. My basic needs are met. Beyond that, I'm really over having to care about building an API community, making change with APIs, and counteracting all of the negative effects of APIs in the wild. I can focus on exactly what interests me about technology, and contribute to the 3% of the API universe that isn't doing yawnworthy, half-assed, or straight up shady shit...

2010 | 2011 | 2012 | 2013 | 2014 | 2015 | 2016 | 2017 | 2018 | 2019 | Archive