The API Evangelist Blog

API Evangelist

A Portable 23andMe API Sandbox

17 Dec 2019

I was creating a Postman collection for the 23andMe API. The 23andMe API is still available, despite the company pulling back somewhat when it comes to accessing the DNA and genetics API. You can still get access to the API for research purposes, but you have to email their business development group and convince them of the merits of your research before you’ll get access to the data. It is pretty common for companies to have valuable data like 23andMe does, and there being a significant amount of concern regarding who has access to it. This is why API management exists as a fundamental building block of API operations, so you can have total control over who has access to your data, and possess detailed logs regarding what has been accessed by consumers. Requiring approval of a developer account before you get your API keys is common, pushing API developers to justify their access and establish a trusted relationship with API providers. This is something you can setup with your API management tooling or services, providing a public sign-up form, yet making each new API consumer wait to be approved before they get their API keys. Even with this security layer in place you may still want to allow API consumers to kick the tires more and see what is possible while awaiting approval for API access. One way you can accomplish this is by creating Postman collections for all the API endpoints, making sure there are one or more examples for each individual API path so that they can be mocked by any consumer using Postman. I went ahead and did this for the 23andMe API. Their documentation is still available, and there are examples for each individual path. I wanted to create a Postman collection for the API to round of my collection of API definitions, and since their documentation had examples, I thought I’d demonstrate how to create portable API sandboxes using...[Read More]


API Evangelist

Being Flexible With Authorization When It Comes To Multiple APIs Within A Single API Collection

16 Dec 2019

I am working on a Postman collection that deploys an API to AWS. I’m pulling the OpenAPI from Postman using the Postman API API (mind blown), and then publishing the API to AWS as an API using the AWS API Gateway API (mind blown again). As part of this process I also need a DynamoDB instance to use as a persistent data store behind the API, which I will create using the DynamoDB API. I need all of these capabilities organized within a single Postman collection, but because of the need to authenticate with multiple API services I will be organizing each capability by AWS service so I can set the authorization for each folder, and let each individual API request inherit from the folder, otherwise I will have to set each individual API request while working—I abstract away the variables I use across the authorization as part of a Postman environment, but I still want to logically think through how I can apply authorization across services. When defining Postman collections you can apply the authorization at the collection, folder, or request levels. This allows you to be more thoughtful of how authenticate across multiple APIs within a single Postman collection. This Postman collection is going to end up being what I’d consider to be a workflow collection, meaning it will walk through each step for the deployment of an API to AWS using Postman, so eventually it most likely will just be a series of individual API requests which can be run manually by a user, or automated with a Postman runner or monitor. However, as I am architecting my collection I don’t want to have to define the authorization for each individual request—I just want them to inherit authorizations, so I am just going to add a folder for each service. This gives me the ability to set authorization for Postman at the header level for an individual request, which I will move...[Read More]


API Evangelist

API Observability Is More Than Just Testing And Monitoring

16 Dec 2019

API observability is something I have written about for a while now after learning about it from Stripe. It is a phrase that has grown popular in API testing, monitoring, and performance circles. Borrowed from the physical world of control systems, observability is a measure of how well internal states of a system can be inferred from knowledge of its external outputs. I am all about getting on API observability train when it comes to monitoring of our systems, but if you’ve read my work you know I am all about expanding the definition to not just include the technical, but also the business and politics of API operations. One of the key aspects of observability is using the outputs or exhaust from the existing services and tooling used to operate your system. To help increase API observability within the enterprise I am always on the hunt for what the existing services and tooling that are in place so that I can better understand what the existing outputs are. If a service or tool is already in place within the enterprise, and we can tap into existing outputs, the chances for successfully changing behavior significantly increases. One tool that is ubiquitous across enterprise organizations is Postman, which provides a whole wealth of opportunity when it comes to tapping into the existing outputs to provide more observability into what is going on across the API life cycle. 90% of the Postman usage within the enterprise I come across occurs in isolation. One developer working with internal and external APIs within Postman. This occurs hundreds, or thousands over within medium and large enterprise organizations. Developers are profiling APIs, building requests, and saving them into collections with very little communication, coordination, and sharing of API awareness across teams. While it represents a pretty concerning trend across enterprise organizations where leadership has such little visibility into what teams are working on, it also represents a pretty significant opportunity for leadership to take...[Read More]


API Evangelist

Believing The Technology Startup Hype And Refusing See Anything Else

14 Dec 2019

I’ve been in numerous discussions with defenders of the Instructure Canvas platform after posting the Instructure LMS data points. These folks are blindly and passionately defending Instructure as a force for good, founded by good people, and being offended that I would see beyond the static representation of the startup they are demanding that everyone see and believe. I find it endlessly fascinating how we as a society continue to believe the storytelling around startups, and receive the marketing they put out as some sort of truth that will play out forever into the future. Even more dangerously these people don’t just believe, they actively police the front-line of critics who are shining a light on what is really going on, doing the bidding of not just startups, and their investors, but the capitalist machine. First, let me quickly disarm some of the standard tactics folks will use to come back at me on this piece. No, I am not anti-startup. I work for one, and have worked for many others. No, I am not anti-investor, I know lots of investors, advise them regularly, and derive most of my income from venture capital. This does not mean I am always walking the line and curbing my criticism of the bad that perpetuated by startups and investors across the landscape. People who feel the need to blindly defend technology is one of the reasons why there are so many bad actors on the stage, and why people are able to get away with the shenanigans they are pulling. Critics and whistleblowers are one of the forces that helps keep exploitative companies in the shadows, and minimize the damage they cause. I’m not saying all critique is constructive or helpful, but I’m saying that if you are actively pushing back on the critics and not listening to what they are saying, you are most likely part of the problem. To recap for those who are just jumping in--Instructure,...[Read More]


API Evangelist

Remember That An Application Is Not Just About Someone Building A Web or Mobile Application With Your API

13 Dec 2019

I encounter regular waves of API providers who are discouraged with the traffic to their API portal as well as the number of developers who are actually building something on top of their API. Many suffer from the hangover of “if you build it they will come” syndrome. Believing that if they just publish their APIs that developers will just show up and build amazing things. While many of us evangelists and advocates have over-promised amazing outcomes when it comes to publishing APIs, many of us in the trenches have long been honest about the hard work it takes to make your APIs something developers will want to use. Just publishing your APIs to a developer portal is not enough. Having a well designed and documented API is not enough. Making enough noise so that people find your API is a full time job, and ideally it is done by a whole team of people—study how Twilio has done it if you need a working example. Also, you have to regularly re-evaluate what the possibilities are when it comes to building or developing “applications”. This isn’t the API ecosystem of a decade ago where we focused on building just widgets and mobile applications. There are many more ways in which people can put your APIs to work in 2019, and you should be making time to understand what those possibilities are. The chance that some new developer will randomly find your API and build the next killer mobile application is pretty slim, and the real world implementations are probably going be much more mundane and granular. The important thing to remember about the word “application” is it does not necessary mean a web, mobile, or device application—it can simply mean “applying” your API.  Which in a world of integration platform as a service (iPads), bots, voice, and other use cases, applying your API could mean many different things. Don’t expect that all of your API...[Read More]


API Evangelist

The Postman Business Model Is In Alignment With Enterprise Objectives

12 Dec 2019

One of the things that became very clear during my conversations with folks at AWS re:Invent last week is that Postman’s revenue model is in alignment with what is needed within the enterprise. To help explain, let’s answer the question I got over and over at re:Invent—how does Postman make money? Steady waves of folks would show up at our booth in the re:Invent expo hall, and usually after a couple minutes of talking about their FREE usage of Postman, and how ubiquitous the tool is at their organization, they would inquire about our pro and enterprise offerings—which is all about helping enterprise organizations get more organized when it comes to doing APIs. The Postman Pro and Enterprise offerings are all about scaled usage of the platform, which includes the number of collections, users, teams, workspaces, and the collaboration, automation, and orchestration across them. All the core Postman features are free, and will remain free—developers love Postman because of its utility, and we do not intend to mess with that.  Paying for Postman means you are getting more organized about how you manage users, collections, environments, teams, and workspaces, as well as using more monitors, runners, mocks, and documentation. While more usage doesn’t always mean an organizations is doing things in a more logical fashion, but Postman enterprise features center around the organized governance of users, teams, workspaces, collections, and environments, steering enterprise customers towards optimizing how things get done. Having observability into all of your teams delivering and consuming APIs is the most important thing you can be investing in as part of your enterprise operations—the Postman enterprise tier is centered around charging for collaboration, automation, and scaling your teams using a tool they already are using, which increases observability across your API operations. This is why I am working for Postman. I am regularly conflicted about how the companies I rely upon tier their pricing and scale the business side of what they...[Read More]


API Evangelist

Focusing On Digital API Capabilities Over Just Doing APIs

12 Dec 2019

As I work on creating more useful Postman collections I am distilling my API definitions down to the small possible unit as I possibly can. While I have many robust reference Postman collections and OpenAPIs, I am enjoying creating Postman collections that accomplish just a single ting—representing each digital capability that I have. Currently my digital capabilities are spread across a number of servers, GitHub repositories, and Postman workspaces. If I use one of the APIs in my long list of API providers it is pretty common that I use less than 5% of the API paths from each individual providers. So, other than for sharing as part of my API Evangelist research, why do I need to wade through entire reference API collections to get at the one or two capabilities I need to actually use. I’m slowly working through the stack of APIs that I use, pulling out the different capabilities I put to work as part of my API Evangelist work, defining as single Postman collections that I list on my GitHub capabilities page. I have published two Twitter API capabilities I have defined, which I will be expanding on pretty quickly, helping document all of the essential API calls I make to the Twitter platform. Twitter Tweet Search A basic search for Tweets on Twitter by query. Twitter Account Status Doing a lookup on users and returning only the fields that describe their status. I have probably another 50 individual Twitter platform capabilities I am putting to work across my platform. I am going to list them all out here, and then begin documenting how I put each of these capabilities to work. Then I’m going to evaluate whether there is any opportunity for me to scale each capabilities using Postman monitors, helping me automate the orchestration of Twitter data across my operations. Next, I got to work defining a handful of GitHub capabilities I put to use on a regular...[Read More]


API Evangelist

Automatically Generate OpenAPI For Your APIs Just By Using Them

12 Dec 2019

I am a big fan of tools that just augment our normal existence then make our lives easier without having to do much additional work. One of the tools that fits into this category is Optic, an open source tool that will generate OpenAPI definitions from your proxied traffic. A while back I developed my own script for doing this by processing Charles Proxy files synced with Dropbox, but I never evolved it beyond Swagger when OpenAPI 3.0 was released. So I was pleased to talk with the Optic team at API World in San Jose a while back. Like many notes in my notebook, my thoughts on Optic got buried by the constant flow of conversations and ideas coming in on a daily basis, but a Tweet from them the other day reminded me that I wanted to showcase and talk a little more about what they are up to and why Optic is important to the API sector. Optic will take your browser, CLI, and Postman API traffic and automatically generate an OpenAPI based upon your API calls that are routed through the Optic proxy. Helping us automate the generation of machine readable API contracts which can then be used across our API operations.  The generation of OpenAPI from the exhaust of our existing work is valuable, but what also grabs my attention is that Optic helps handle the diffs between each OpenAPI generating, which can be used to help you detect changes in APIs that are already in use. As I said, I have had this capability for a while now, and it is something you can do within Postman—turning on a proxy and generating a Postman collection. But, having as a standalone open source open source component that produces OpenAPI contracts as a standalone service is pretty critical for helping us make sense of our API exhaust at scale. Optic’s core feature is generating OpenAPIs and managing the diff between each...[Read More]


API Evangelist

We Will Not Convince Everyone To Go API Design First

11 Dec 2019

I believe in going API first. I think it provides a positive step for development teams. I think it is one that makes sense for most enterprise organizations. But if I have learned anything in the last decade of working with APIs is that I rarely get what I want, and people don’t always do what is right and what will make sense. I have gotten a lot of pushback from developers, API providers, and service providers regarding the notion that code first API delivery is bad, as well as the idea that API design first is good. For me, the real challenge here isn’t about selling folks on one approach or the other, it is more about injecting more stakeholders and communication into the process earlier on in the evolution of APIs, rather than waiting until they are baked into production before iterating upon the design of the interface. There are a lot of existing folks who are trained to deliver code across the enterprise landscape. I’ve heard repeatedly from folks that they are a programmer, and not a templater, artifactor, or API designer. I get it. We have a lot of momentum occurring based upon the way things have been historically, and I don’t doubt that it will be difficult to change our behavior. The challenge here lies around understanding how much of the pushback on API design first is purely about being resistant to change over there being multiple ways to tackle the deliver of an API. I feel pretty confident about there being multiple ways to actually deliver an API, and I don’t care if you are mocking it, delivering via a gateway, with a framework, or hand pounding your artisan APIs on the forge in the workshop. I just care that there is as much light on the overall process, as many stakeholders as possible involved, and there is a feedback loop around what the design of the APIs should...[Read More]


API Evangelist

My Thoughts ON Amazon EventBridge Schema Registry And Discovery

10 Dec 2019

My friend Fran Méndez (@fmvilas) over at AsyncAPI asked me to share my opinions on Amazon’s EventBridge schema registry and discovery which is in preview. Something that is looking to be a pretty critical add-on to Amazon EventBridge, which provides a serverless event bus that connects application data from your own apps, SaaS, and AWS services. Event-driven approaches to APIs are growing in popularity for a number of reasons, and is something that is only increasing the need for us to get our schema house in order, resulting in solutions like the schema registry for EventBridge being pretty valuable to general API operations. I haven’t taken EventBridge for a test drive, so all of my thoughts are purely superficial, but at first glance it looks like something that can have a meaningful impact on how people are making sense of the schema we have floating around, but I think there will be some key elements that will make or break a solution like the schema registry, something Amazon is already thinking about with their code generation from the schema registry. Here are some of the initial thoughts I am having as I read through the announcements and documentation around EventBridge and the schema registry. JSON Schema Generation - The auto publishing, diff’ing, versioning, discovery, and evolving of JSON Schema representations for all schema in use will be pretty critical in making the registry tangible. Protocol Buffers - There will need to be easy generation and conversion of Protocol Buffers as part of the process. I don’t see that EventBridge supports gRPC or Protocol Buffers, but it was a thought I was having./ AsyncAPI Generation - The schema catalog should automatically generate and version AsyncAPI specifications for all the schema, and ultimately channels and topics being defined as part of EventBridge. Tagging - Being able to tag schema, organize them, and discover based upon an evolving taxonomy that helps make sense of the expanding schema landscape will...[Read More]


API Evangelist

Abstracting Away API Response Complexity With Postman Visualizer

10 Dec 2019

I was creating a Postman collection for validating the status of Twitter users, where I was looking to extract a subset of data from the very verbose Twitter API response for a Tweet Lookup. There is a lot of data contained within a single Tweet JSON response, and all I was looking for was just a handful of the fields. I thought this would be a great opportunity to show off the new Postman visualizer, where you can display the API response for each request however you want. To get started I crafted an API request for the Twitter lookup API path, allowing me to pass in up to 100 Twitter user handles, and return a JSON response for all the Twitter users I want to check in on the status of—leveraging Postman to authorize and see the details of the API response. This res[omse has the data I need, but looking through the entire of the JSON response is a lot more than I can ask of many of the people I will be sharing the collection with. I’m going to be sharing it with mostly non-developers, hoping to provide them them with a quick way to check the status of various Twitter users, and wading through the JSON is unacceptable, so I used the new Postman visualizer to render an HTML list of only the data I wanted. The Postman visualizer allows me to pull only the fields I need and publish as HTML to the visualizer tab. Providing a more human readable view of the Twitter Lookup API response, making the Twitter API more accessible by developers and non-developers who are looking for a quick way to validate the status of one or many Twitter users. To make this happen, all I did was add a test script to the API request, adding a little JavaScript which takes the JSON response, loop through each user being returned and retrieve only the fields...[Read More]


API Evangelist

Validating Twitter Users Using The Twitter API Without Writing Code

09 Dec 2019

I was asked on Twitter if I had any code for pulling the status of Twitter users. Since I am the API Evangelist, and the Chief Postman at Twitter I tend to prefer sharing of Postman collections rather than actual language specific code. It is easy for me to craft a single Postman request that accomplishes a specific purpose, then share as a template in the Postman API network, than it is to write code. Plus, any user can then execute on their own within their own local Postman client. To satisfy this request, and demonstrate how Postman collections work, I created one for looking up the status of a list of any Twitter handle, verifying the state of each individual Twitter user—providing only the basic information you need to validate one or many different Twitter accounts. Before you can use this API collection you will have to download the Postman applications, then setup your own Twitter application so that you can make calls to the Twitter API--do not worry, it is painless, and something even a non-developer can do. When filling out the form, all you need is to give your app a name, description, website URL, and tell them how it will be used. You can ignore the rest of the fields. Once the application is added you can obtain your access tokens by clicking on the keys and tokens tab. The first time you create your application you will have regenerate your access token and access token secret, and then you will need all four tokens to authenticate (Don't worry those aren't my real tokens). Once you have your own tokens, go back to your Postman application and click on the Twitter Lookup Postman collection, and edit its details. Once the edit window pops up select the Authorization tab, then select to use OAuth 1.0 and add your auth data to request headers from the dropdown boxes, then add your own ,...[Read More]


API Evangelist

Twitter API Authorization Using Postman

09 Dec 2019

I just created a new Postman collection for validating Twitter users via the Twitter API. As part of the Postman collection documentation and tutorial I included the steps for authorizing with the Twitter API. This is something that can easily be a hurdle for developer, and will definitely run most non-developers off. In reality, setting up your own Twitter API application, then copying your API tokens and use them in a Postman collection is something anyone can accomplish. This is an authorization workflow that I will be referencing in many different Twitter API tutorials and stories on the blog, so I wanted to have as a standalone URL that I could easily share with anyone. Before you can make any call to the Twitter API you will need to have four application tokens you can only obtain via your own Twitter developer account. The first step of this process is to setup a Twitter developer account which is different than your regular account, and can be done via the Twitter developer portal. Once you have a Twitter developer account you can visit the application listing page, and choose to create a new application in the top corner, and manage any existing application you have already added in the past. Allowing you to manage the details of your access to the Twitter API. While creating an application there are a number of details you will need to consider, but to jumpstart your API Integration all you will need is the name, description, website URL, and tell Twitter how this app will be used. You can always edit these settings at any point in the future, so do not worry too much about them when getting started. Once you have created your Twitter application you can visit the keys and tokens tab to obtain your consumer API keys as well as the access token and access token secret. Providing the four tokens you will need to actually authorize...[Read More]


API Evangelist

A Postman Meetup This Tuesday In Seattle

09 Dec 2019

I am all recovered from being at AWS re:Invent all week in Las Vegas, and gearing up for a Postman meetup in Seattle this Tuesday. I am stoked to be doing ane vent on my home turf, but I am aslo pretty happy with the lineup. I am going to be opening things off with a quick look at Postman collections, but then I have Tableau and NGINX giving some talks, and then a quick closing with a look at the Postman visualizer--here is the lineup for Tuesday nights goings on. Postman API Collections Kin Lane (@kinlane), Chief Evangelist @ Postman You save your Postman requests as collections each day, but have you learned about all the ways in which collections can be applied? Let’s move beyond just reference collections for every endpoint in your API and making collections reflect the real world business use cases your APIs solve. Pushing your Postman collections to me more intuitive and useful for your developers, helping on-board them with the possibilities while also documenting what your APIs can do, providing portable, shareable, machine readable, and executable representations of what your APIs deliver. How Tableau uses Postman to enable developers Geraldine Zanolli a.k.a Gigi (@illonage) Developer Advocate @ Tableau Tableau , well-known in the Business Intelligence industry for building great data visualizations, also offers a set of APIs and Developer Tools that allow developers to integrate, customize, automate, and extend Tableau to fit the specific needs of their organization. Learn how Tableau uses Postman to give developers an interface to do their first API request. The NGINX API Gateway Liam Crilly (@liamcrilly), Director of Product Management @ NGINX APIs are changing the way we build applications and changing the way we expose data, both inside and outside our organizations. But what is the most efficient and effective way to deliver these APIs? That’s the job of the API gateway. In this session, we will look at different deployment patterns for...[Read More]


API Evangelist

We Will Not Discuss APIs Without A Postman Collection

02 Dec 2019

I heard a story this morning while having breakfast with someone at the Venetian before I made my way to the re:Invent registration counter which reminded me of the now infamous secret to Amazon’s API success myth story. I can’t mention the company involved because they are pretty confident they’d never get approval to tell this story publicly, but as I so often do, I still feel it is worth telling even in an anonymous way. Internal groups at this company were having such a problem around coherently discussing the details of APIs between internal groups, that they made a rule that they will not talk with other teams about any API without there being a Postman collection present (ha, Postman mediator) to facilitate the conversation. There has been several stories on this blog about the problems with emailing API responses between teams, and sending Microsoft Word documents with XML or JSON responses embedded in them. If you work within the enterprise you know that this is a common way to share API responses, and get guidance, ask questions, and generally discuss the details of each API being put to use. Imagine if all of this was banned, and if you had a question about the details of making an API request or parsing the response, it was mandatory to provide a Postman collection of each API request and response in question. Ensuring that ALL the details of the request with a real-life example of the response was present before any discussion would commence. Talk about a game changer when it comes to making sure people were on the same page when it came to discussing some very abstract concepts. Ensuring team members are all on the same page when it comes to what an API is, let alone the endless number of details regarding query parameters, headers, authentication and other details takes a lot of work. Even if all stakeholders in a conversation are...[Read More]


API Evangelist

Mock AWS Services Using Postman Collections With Examples

02 Dec 2019

As I create each of the 50+ Postman collections for AWS services I am always striving for establishing as complete of a collection I as possibly can—this includes having examples for each API request being defined. This is something that is easier said than done, as there are many different ways in which you can setup your AWS infrastructure, and work with your infrastructure using AWS APIs, but nonetheless, I still strive for ensuring there is an example saved as part of each Postman collection. While this helps me better define each request, there are numerous benefits from having API examples, and one of the most beneficial of these is being able to generate mock APIs from the AWS Postman collections I’m publishing. Taking a look at the Postman collection I have published for Amazon DynamoDB, I have managed to save examples for each of the API requests documented as part of the AWS reference Postman collection. This makes it so anyone can run the Postman collection within their own Postman platform account, and then generate a mock server for the Amazon DynamoDB API. Allowing developers to develop against the API without actually having to use a live AWS account, have the proper infrastructure and permissions setup, making it quicker and easier to jumpstart the development of desktop, web, and mobile applications. Allowing developers to publish their own mock servers for AWS services, and save time and money when it comes to your AWS budget. I can envision developing AWS Postman collections that are complete with examples derived from specific AWS infrastructure deployments. Tailoring a specific setup and configuration, then making API requests to the AWS APIs needed for orchestrating against these existing infrastructure configurations, and saving the examples return from each API response. Essentially taking a snapshot of an existing AWS setup across multiple services, then making that snapshot available as a mocked set of AWS APIs that return the responses developers are needing...[Read More]


API Evangelist

gRPCs Potentially Fatal Weakness

02 Dec 2019

I was reading an article on Microsofts DevBlog about gRPC vs HTTP APIs. It makes the usual arguments of how gRPC compares with HTTP APIs. While the arguments for gRPC are definitely compelling, I find the weaknesses of gRPC in this moment in time even more interesting, for two reasons, 1) they are something we can overcome with the right tooling and services, and 2) they reflect our challenge between the human and machine readablity of all of this, which many of us technologists really suck at, leaving me concerned whether or not we will be able to get this right—as I think we underestimated this characteristic of HTTP APIs, and have missed the full potential of this opportunity even as we are faced with this next step. Here is what was said the blog post, highlighting two distinct weaknesses of gRPC, but which I view as more about systemic illnesses in the wider view of the API landscape, and our inability to understand the important role that humans play in all of this: Limited browser support gRPC has excellent cross-platform support! gRPC implementations are available for every programming language in common usage today. However one place you can’t call a gRPC service from is a browser. gRPC heavily uses HTTP/2 features and no browser provides the level of control required over web requests to support a gRPC client. For example, browsers do not allow a caller to require that HTTP/2 be used, or provide access to underlying HTTP/2 frames. gRPC-Web is an additional technology from the gRPC team that provides limited gRPC support in the browser. gRPC-Web consists of two parts: a JavaScript client that supports all modern browsers, and a gRPC-Web proxy on the server. The gRPC-Web client calls the proxy and the proxy will forward on the gRPC requests to the gRPC server. Not all of gRPC’s features are supported by gRPC-Web. Client and bidirectional streaming isn’t supported, and there is limited support...[Read More]


API Evangelist

I Am Heading To Vegas For AWS re:Invent

01 Dec 2019

I’m sitting in the Seattle airport waiting for my flight to Las Vegas. I’m heading to AWS re:Invent, spending the entire week talking everything APIs with the masses at the flagship conference. It is my 3rd time in Vegas for re:Invent, but my first time exhibiting with such a strong brand—Postman. Like years before, I will be there to talk to as many people as I can about how they are delivering APIs, and learning about the challenges they face when consuming APIs. However, this year I won’t just be there as a representative for API Evangelist—this year I am there to help also talk about the role Postman plays in the delivery and consumption of APIs. To get fired up for the conference I’ve spent the last couple of weeks developing Postman collections for as many AWS APIs as I could—I had set 25 services as my target, and managed to a little more than 50 separate services defines as reference Postman collections. I learned a lot throughout the process, assisting me in loading up a whole lot of details about common AWS API infrastructure into my brain, helping me prime my brain for conversations I will be having at re:Invent. Helping not just think deeply about AWS services, but also how Postman can be used to work with AWS APIs. These Postman reference collections are just the foundation for my API understanding, API conversations, and other ways of considering how AWS APIs impact how we deliver applications in the cloud. While the AWS Postman collections help jumpstart anyones usage of AWS, I’m also looking at how to use them to actually define, deploy, manage, and evolve APIs that operate on AWS. AWS APIs have long fascinated me, and have played a significant role in my evolution as the API Evangelist, In 2020 I’m still keen on learning from AWS as an API pioneer, but I am more interested in learning how we can...[Read More]


API Evangelist

I Am Happy I Chose The Term Evangelism

27 Nov 2019

There is always lot of discussion around the proper term to use for describing what it is we all do when it comes to getting the word out about our APIs. Some of use use the word evangelism, while others prefer to use advocacy, relations, or being an ambassador or champion. Sometimes it is focused on APIs, but other times it is focused on developers or other aspect of what we are looking to highlight. While there are many “announced” reasons why we evangelize, advocate, and champion, the real honest reason is always that we want to bring attention to our products and services. Sure, in some cases we are interested in educating and supporting developers, but really all of this is about bringing attention to whatever we are peddling—me included. I didn’t grow up religious—the opposite actually. I never went to a church ceremony until I was an adult. So the term evangelism doesn’t carry a lot of baggage for me. However, I do fully understand that it does for many other people. Even though I didn’t go to church, I did grow up around enough people who were very religious to understand the meaning evangelism can bring to the table. Early on in doing API Evangelism I felt somewhat bad for using this term, and felt like I was bringing a whole lot of unnecessary meaning and baggage to the table as I was trying to “enlighten” folks of the API potential. Now, after a decade of doing this, I’m happy I chose the term evangelism, because I feel it best represents what it is I do in this technology obsessed world we have created for ourselves.  Technology is the new religion for many people. You know what two of the fastest growing areas of APIs are? Blockchain and churches. When you have so many people blindly believing in technology, it begins to look and smell a lot like religion. When you embark...[Read More]


API Evangelist

Bulk Updating My Postman Collections Using The Postman API

27 Nov 2019

I had recently pulled all of the AWS Postman collections I have created and spread across Postman workspaces. After creating over 50 AWS Postman collections I learned some things along the way, and realized I needed to update my variable for the baseURL of each API, but I had already created all my collections, and to update these variables manually would take me hours, if not days. So I got to work writing a script that would pull the latest JSON for each collection, conduct a find and replace on the replacing it with a service specific base url that went something like this , then write back using the Postman API. This is something that would take me many hours to update across 50+ collections and nearly 1000 individual requests, but is something that I could accomplish in less than an hour with the Postman API. Once again, when I can’t get what I need to quickly in the Postman UI, I can quickly get things done using the Postman API. This is how it should be. I don’t expect that the Postman UI keep pace with all of my needs. I like Postman as it is, and carefully plodding forward adding features that make sense to as wide of an audience as possible. I always know that I can get at what I need through the API, and automate the changes I need. In this case, I’m able to rapidly make updates at scale across many different API collections, relying on Postman to help me manage API definitions manually through the interface and in many different automated ways via their API. I am still getting my bearings when it comes to managing the variables I use across my many Postman collections. I am rapidly iterating upon how I name my variables for maximum flexibility within Postman environments, and where I apply them within my Postman collections. This is something that requires a lot...[Read More]


API Evangelist

So You Wanna Build An iPaaS Solution

26 Nov 2019

I’m getting more emails and DMs from startups doing what I’d consider to be integration platform as a service (iPaaS) solutions. These are services that help developers or business users integrate using multiple APIs. Think IFTTT or Zapier. I’ve seen many waves of them come, and I’ve seen many waves of them go away. I’m always optimistic that someone will come along and make one that reflects my open API philosophy and still can make revenue to support itself. So far, Zapier is the closest one we have, and I”m sure there are others, but honestly I’ve grown weary of test driving new ones, and I am not as up to speed as I should be on what’s out there.  When it comes to iPaaS providers the bar is pretty high to convince me that I should be test driving your solution, and why I should support you in the long run. This is partly from just having supported so many services over the years, only to have them eventually go away. It is also because of new problems for consumers being introduced into the mix because of the abstracting away of the complexities of APIs, rather than joining forces to educate and fixes these complexities amongst API providers. I’m always willing to talk with new iPaaS providers that come along, but I have a few requirements I like to put out there which usually filters the people who end up reaching out and engage from those who do not. Due Diligence - Make sure you are testing driving and reviewing as many existing iPaaS platforms as you possibly can, because there are a lot of them, and the more you kick the tires on, the more robust and valuable your solution will be. API Definitions - Your solution needs to be API definition driven, adopting OpenAPI, Postman collections, and existing formats for defining each of the APIs you are integrating with, as well as...[Read More]


API Evangelist

Pulling All My Postman Collections Using The Postman API

26 Nov 2019

I needed access to all of the AWS Postman collections I am building. The problem is they are distributed across multiple different workspaces. I had organized over 50 AWS Postman collections based upon the resource they were making available. Now I just wanted a list of all of them, and report on what I have done. It sounded like a good idea to group them by resource at first, but now that I needed to work with all of them in a single list, I’m thinking maybe not. So I got to work pulling all of my collections from the Postman API and filtering out any collection that wasn’t from AWS. I find it easy to get caught up in what features are available to me via the interface of the services and tooling I use, letting the UI define what is possible. This is why I only use services and tooling that have APIs if I can help it—as the API is always the relief valve for allowing me to get done what I need. In this case, while very robust, I couldn’t get everything I needed done with the Postman UI in the time period required, so I switched to the API, and was able to programmatically get at the data I needed. Allowing me to pull all of my collections from across workspaces, then organize and generate exactly the list of collections I needed for a specific report I’m working on. While talking with folks about Postman I regularly encounter individuals who speak about the limitations in the product, stating they couldn’t use it to accomplish something because it didn’t do this or that. Without ever considering that they could accomplish it via the API. Personally, I am impressed at how thoughtful Postman has been about adding new features, helping minimize the complexity and bloat of the platform. This is why I expect platforms to have APIs, so that I can get...[Read More]


API Evangelist

Is it an Amazon or AWS Branded Service

26 Nov 2019

I’m working on 50+ AWS Postman collections at the moment, as well as crafting Postman environments for use across them. I’ve encountered some namespace challenges in this work, and I was needing to establish a naming convention for the key / value pairs I’m using within my Postman environments. To help establish the namespaces I am just taking the display name for each of the APIs I am profiling, but one thing I’m noticing is that there are two different names in use across APIs, being either AWS or Amazon—with no rhyme or reason why a service is labeled one way or the other.  Looking down the list of all the services they have, I would say that AWS is more prominent than Amazon as the beginning namespace for each service. I’m just curious if there is any guidance or rhyme or reason to the naming of services launched under AWS. At first it feels like I’m being too pedantic, but from a branding, and even programmatically across services, it seems like having a common naming convention for services would make sense. Like my thoughts on the API design consistency across AWS APIs, I’m not trying to shame AWS, I am just trying to learn from what is happening, and share what I find with other API providers. I regularly use Amazon as an example to learn from in my API storytelling, which unfortunately sets them up for constructive criticism as well--I am sure they can handle. ;-) For my environment variable challenge I am simply going to prefix my variables with aws as the service namespace. I’m just standardizing for shortness, ease of use, and distinguishing AWS APIs from the other API providers I’m profiling. I was more interested in just pausing and thinking about why this occurs, and work to think more deeply about how we name our APIs. For me, the lessons around naming our APIs is more about pushing us to...[Read More]


API Evangelist

Where O Where Is My API Key

25 Nov 2019

Finding your API key for an API provider can be a real pain in the ass. Depending on the account it can be buried deep within your settings, or possibly out in the back 40 in another separate developer account. I’m not even talking about OAuth here, I am just talking about obtaining one or more API keys to access the valuable API resources you desire from a free service, or even from a service you are paying for. There is no standard for how to create, define, storage, and access API keys. It has been something that API providers have helped standardize somewhat (I guess?), but ultimately there is no unified way for me to access all the API keys I use across the thousands of API I use — yes, I do use thousands of APIs, because I am the API Evangelist. Why can’t API keys be easier to find, and exist as a default part of our platform accounts. They shouldn’t be this hard to generate, find, and put to use. I keep coming back to my CloudFlare DNS application experience on this subject. Next to some of the actions I can take in the CloudFlare UI is a link to the API call to make the same action, complete with my API keys to make the calls. I don’t have to do anything else other than use the application to find the keys. Can you imagine if every UI element in every application had the underlying API call available right next to it with API keys? Can you imagine if every API call came back with a link in the response to where I can take the same action in the UI? Maybe I have a different view of the world than others, but this seems like it should be common place in the tech sector. I’m afraid many folks have seen APIs as some technical thing over there for too...[Read More]


API Evangelist

API Design Consistency Across Amazon Web Services

25 Nov 2019

I have been crafting Postman collections for as many AWS APIs as I can before re:Invent. As I work my way through the different APIs I”m reminded of the difficulties involved in API consistency and governance at large enterprise organizations. While most AWS APIs employ a pretty formulaic XML RPC design, there are variations within how these RPC APIs work, but there are also several outliers of other more RESTful and even full blown hypermedia APIs present. Making for a pretty wild mix of API resources to put to work, something that has been abstracted away as part of their SDKs, but is painfully present when directly integrating with APIs across multiple services. From the lay of the land I’m guessing AWS had instituted their primary XML RPC approach, and baked that into governance law across the organization in early days. Over the years, after significant growth, some groups were able to publish APIs outside of this pattern, resulting in the patchwork quilt of services that are present. The most notable and ironic deviation from this pattern is the API for the AWS API Gateway, which employs a RESTful approach using the HAL media type. Which personally, I would prefer as the dominate pattern across all the service, but sadly it is the more legacy XML RPC pattern that dominates. I get it, you can’t go changing the AWS S3 or EC2 APIs now, they are known for their stability, but I still think there are some important API design and governance lessons present in the valuable cloud API stack. The first lesson in all of this I’d say is that we need to make sure and establish your API design governance early on and socialize across all teams—even new ones. The second lesson I’d say is to make sure and review your API design governance regularly to make sure you aren’t missing any healthier patterns that may have come along. You don’t want to...[Read More]


API Evangelist

API Copyright: Directories

25 Nov 2019

I am gearing up for API copyright heading to the Supreme Court, having another look at whether or not the naming and ordering of your API interface is copyrightable, as well as whether or not reimplementation of it can be considered fair use. To help strengthen my arguments that API should not be copyrightable I wanted to work through my thoughts about how APIs are similar to other existing concepts that are not copyrightable. One of the newer concepts I”m working with to help strengthen my argument that copyright does not apply to APIs involves the directory, and shining a light on the fact that APIs are just a directory of our digital resources. As with all of my API storytelling, I am focused exclusively on web API. Occasionally you’l hear me talking about language and platform SDK APIs, browser APIs, and other variations, but the majority of what I mean when I say API is done via public DNS over HTTP, HTTP/2, and sometimes TCP. All of these APIs are just a directory of Uniform Resource Identifiers (URIs) of corporate and institutional digital assets. Modern APIs most often leverage DNS, providing a machine readable listing of resources that are available within a specific domain. The domain and the resulting API directory are not creative expressions, they are an address that points to a directory of digital assets, allowing them to be found by developers for use in other applications and systems. APIs are not a form of creative expression, they are just helping companies, organizations, institutions, and government agencies make their digital resources and capabilities discoverable. I can easily make the argument that APIs are simply a directory or menu of organizational resources and capabilities. Due to the diverse nature of what an API can be, I can also easily apply the analogy that APIs are also recipes. All the above is true. As with my restaurant menu and recipe stories, people have trouble believing...[Read More]


API Evangelist

Reducing API On-Boarding Friction With API Environments

22 Nov 2019

I’m obsessed with making my Postman collections more accessible and executable to developers and non-developers. I’m really frustrated that on-boarding with APIs is still so difficult, and I’m determined to reduce friction in this area in 2020. I’m confident that Postman collections plus environments represent the next stage in API integration, automation, and orchestration, but we still have some sharp corners to round off when it comes to streamling the on-boarding of new users to each APIs being referenced within each Postman reference, workflow, capability, collaboration, walkthrough, and the numerous other types of Postman collections that are emerging across the API landscape.  I’ve been working hard to create a number of new Postman collections and even once you click on the Run in Postman button for each API collection, you still have to go signup for an account, create an OAuth application, and plugin in the OAuth details for API before you can make your first API call — this is dumb. We desperately need to redefine what an application is in the context of the API management layer for providers. As I’ve said many times before, every API provider needs to provide personal OAuth access tokens by default as part of your account like GitHub does. This should be the baseline for all APIs, but we also need more services and tooling that helps us generate and manage tokens for use across our low-code and no-code API integration solutions. I got frustrated enough recently that I just began hacking together what I am simply calling: API Evangelist Environments. It’s a pretty crude tool, but it represents a pretty good start. It helps establish a base OAuth application for a handful of common APIs, allowing anyone to click and generate a token which can be used to make API calls. If you put your Postman API key in the text box, it will also generate a Postman environment and place it in your Postman account....[Read More]


API Evangelist

Developing An API Environment Naming Strategy

22 Nov 2019

I’m creating more Postman environments lately. I’m realizing the potential for using environments as a pivotal layer in defining and working with Postman collections. Environments are the missing ingredient from OpenAPI, and provide a powerful way to abstract away key value pairs, including keys and tokens from the Postman collections, allowing me to apply the same Postman collection over and over but in different contexts. As I’m pushing the boundaries of working with API environments I’m being pushed to think more deeply about how I name my variables so that they stay in sync with Postman collections, but more specifically work seamlessly across many different types of Postman collections. An example of this shift has emerged while I am crafting Postman collections for AWS APIs, and was defining a base environment for each collection with a handful of key / value pairs which I will need to actually fire up a collection and begin making calls to each AWS API I am targeting with each Postman collection. baseURL - The baseURL for use across all the requests I have organized into collections. accessKey - One half of the keys needed for authenticating against any AWS API. secretKey - The other half of the keys needed for authenticating against any AWS API. region - The region where each of the APIs I’m engaging with are operating within AWS. As I build each Postman environment I am naming each one with the same name as I am applying to the Postman reference collection I am creating for each AWS API. This works well in isolation, but the approach begins to break down as I begin crafting capability, workflow, and walk through Postman collections that will be putting multiple AWS from across multiple AWS services to work. This realization has made me aware that I am going to need to begin developing a more comprehensive and long term strategy for crafting my environments, as well as the variables I use...[Read More]


API Evangelist

API Copyright: Restaurant Menu

22 Nov 2019

I am gearing up for API copyright heading to the Supreme Court, having another look at whether or not the naming and ordering of your API interface is copyrightable, as well as whether or not reimplementation of it can be considered fair use. To help strengthen my arguments that API should not be copyrightable I wanted to work through my thoughts about how APIs are similar to other existing concepts that are not copyrightable. One of the old concepts I had worked through back in May of 2014, and was used by Google as part of their argument, was the notion that your API is just a menu for your organizational digital resources--I wanted to take a fresh look at this concept, and add it to the toolbox for when we head to DC. The restaurant menu analogy is an important one to help people who really don’t understand APIs, as well as those who do understand APIs, but don’t understand the wider world of copyright. As I’ve said before, the problem here is purely because people can’t separate the interface from the backend, from the data, content, and media that flows through them. People simply see the entire things as an API. I want to keep making the argument that your backend code, and the data, content, and media that flows through can be copyrighted and patented—I don’t care. I’m arguing that the interface to these valuable resources needs to stay open, in the public domain, and should not be subject to copyright, just like the menu of a restaurant. Your application programming interface (API) is not your application, it is the programming interface to your application. Your API is the menu to the digital resources and capabilities you possess within your company, organization, institution, or government agency. APIs are how your digital resources and capabilities are made known, accessed, and baked into your partners technological solutions. You want your APIs to be as open,...[Read More]


API Evangelist

The Missed Revenue Opportunities For The State Of California Because They Do Not Have A Business Registry API

21 Nov 2019

I was talking with OpenCorporates CEO Chris Taggart (@countculture) while in Washington DC a couple of weeks ago, reminding me of a previous conversation we had about the current state of business registry submission and search for the State of California. He had asked me a couple months ago if I knew anyone working for the State of California on opening up data, or possibly specifically with the business registry—I didn’t. Chris is wanting to talk with anyone in the know about evolving and modernizing the states approach to managing their corporate entity information. Clearly he has a desire to get better access to the data, but as our conversation in DC reminded me, he has some serious concerns about the importance of not just access to corporate data, but being able to keep up to speed what is happening at the business level in not just California, but other states as well. There are many ways in which government can’t keep up with the pace in the private sector, and corporate filings is definitely one of the more critical areas that is falling behind. Like many areas of government I’m guessing this is by design. Not because of some grand government or corporate conspiracy, but just by the the ongoing suffocation of the resources government has to get things done. I’m guessing the folks running the State of California business search are doing the best they can with the resources they have. I’m guessing that the private sector has no real motivation to lobby and compel the State of California to do any better when it comes to filing, managing, and search for business data. The result is a business registry system that barely meets the needs of everyone involved, and leaving a lot of opportunities on the table when it comes to understanding and responding to change in the way business gets done in the state. When it comes to business registry in...[Read More]


API Evangelist

Reference And Walkthrough API Documentation And Collections From ShipEngine

21 Nov 2019

One of the things I have been thoroughly enjoying as part of my work with Postman is the many different ways in which Postman collections are being work. If you’ve followed my blog over the years you know I’ve been a big supporter of OpenAPI—it has changed how we communicate about our APIs. Until I began working with Postman I viewed Postman collections as just another API definition like OpenAPI, where you can define the surface area of your APIs. My perspective began changing once I learned about Postman environments, but my world has been completely shifted once I began learning the different ways in which Postman customers are putting collections to work as part of their API operations. Reference Postman collections is the most common approach you will find in the wild, outlining all of the API paths that exist for an API, but over the last couple months I’ve seen entirely new types of collections emerge, including workflow, capability, maintenance, governance, and now walkthrough Postman collections. I saw ShipEngine tweeting out about giving a live demo of their “fancy new @getpostman docs” tonight at the #AustinAPI meetup, and after landing on the ShipEngine documentation home page I found two types of Postman collections, with supporting documentation. Providing two distinct ways of communicating around the ShipEngine APIs, helping provide one set for on-boarding new users, and another for making sure every API path is documented and accessible. First they provide ShipEngine Walkthrough, which provides collection is a guided tour through ShipEngine's most popular features, reducing the overhead for any developer looking to quickly understand what the ShipEngine API provides—highlight the following capabilities.  Create and download shipping labels  Calculate shipping costs for any package  Compare rates across UPS, FedEx, USPS and other carriers  Track packages in real-time or on-demand  Parse and validate mailing addresses for any country on Earth! Then ShipEngine provide with ShipEngine Reference, which is a collection that contains sample requests for every...[Read More]


API Evangelist

Attracting The Big Customers You Desire Requires A Steady Stream Of API Storytelling

21 Nov 2019

API storytelling is the number tool in my toolbox, and this should be the same for API providers and service providers. I know that many folks, especially the more technical folks snicker every time I write about storytelling being so important, but this is just because of a lack of awareness regarding all the influence that stories have on our personal and professional lives. One hallmark of successful API operations is always a healthy dose of storytelling via blogs, social media, GitHub and the mainstream press. One example of this out in the wild is out of Capital One, who have embraced being very transparent in how they do APIs, both internally and externally, being very active when it comes to telling stories about what they are up to, and encouraging their employees do the same. Being this vocal as a large enterprise organization isn’t easy, especially one that operates within such a highly regulated industry. As with any enterprise organization Capital One is still very reserved in many ways, and has its official communication channels and overall narrative. With that said, they have a slightly more amplified voice out of technical groups, and they give more agency to its employees, as well as outside voices like me. I’ve never had to sign an NDA as part of regular engagements with their API teams, leaving it up to me to be sensible in what I filter and what I do not. I wouldn’t say that Capital One is wildly open with their storytelling like startups I’ve worked with, but they are just one or two notches more open than many other enterprise organizations I work with, especially when it comes to the banking industry—I’d say Capital One is the most visible bank in the United States when it comes to API, and related infrastructure storytelling. After doing my video series with Capital One about two years ago I had people from competing banks reach out...[Read More]


API Evangelist

Company Specific API Workspaces

20 Nov 2019

I have many different workspaces defined within my Postman team account. I’m organizing a couple thousands APIs into different topical categories that help articulate the value they deliver. Once I’ve sufficiently profiled a company and their APIs, producing a reference Postman collection, I’ll share to, or create a workspace for each tag I have applied to each API as part of my profiling process. Depending on the company, I am looking to establish a complete (as possible) Postman reference collection, as well as some more specialized capability, workflow, and other relevant collects that are derived from, and compliment the reference APIs present, but go further towards accomplishing specific business objects with each API path available. I am currently profiling the Postman API, while also defining the capabilities present within the API that I depend on to conduct API Evangelist business. I have already added the Postman API to several other workspaces including design, mocking, documentation, testing, and client, but now I’m going to create a company specific workspace for managing my API collections for Postman. My master copy of the Postman collection which I’ve downloaded from the Postman API Network will act as the master API collection for Postman, and I will share the collection out to any relevant workspace, but I will also be creating some more specific workflow and capability collections that reflect how I use the Postman API to run API Evangelist. I’m not sure this approach will scale, but I’m purposely looking to push the number of collections and workspaces I’m managing using Postman to see where the friction is. I’m using the Postman API to help me organize and audit how I’m managing APIs at scale, so I I can adapt and pivot based upon how I’m breaking things up. If I had to manage everything through the Postman interface it would take me days to get things reorganized each time I change my strategy, but since I have the...[Read More]


API Evangelist

Azure Provides SDK Governance Guidelines

20 Nov 2019

Most companies I encounter who are doing API governance are purely focused on API design, with a handful also thinking more deeply about documentation, testing, monitoring, and other stops along the API life cycle. API governance done well involves every stop, but since most organizations are only just getting started investing in API governance, the area of API design is a sensible place to start. Defining how APIs should be designed, helping introduce consistency in how APIs are developed, reducing friction for consumers when it comes to integrating them into applications. Anytime I come across examples of API governance in the wild I try to showcase it here on the blog, and for this story I wanted to shine a light on how the Microsoft Azure team provides guidelines for how SDKs should be developed and delivered. Azure provides the following scaffolding when it comes to their guidelines, answering many of the questions teams will have when it comes to crafting consistent SDKs for APIs across any product or group: Introduction - Providing general information regarding what the SDK guidelines are for, and references the need to work with the Azure Developer Experience Architecture Board to define the right experience. Terminology - Offering a glossary of the most common terms and phrases that are in use that might not be readily known by stakeholders, providing easy to find definitions for words that will be used across guidelines API Design -  Articulating how the API surface each client library must have the most thought as it is the primary interaction that the consumer has with each service, defining the overall developer experience. Implementation - Guidance for to actually begin implementing your SDKs once you have thoughtfully define the surface area of the API for the SDK, beginning to actually craft the intended language library SDKs. Documentation - Providing details of what is required when it comes to delivering documentation to support all language client libraries, and...[Read More]


API Evangelist

The Common Building Blocks Of Evangelism

19 Nov 2019

As part of my work as the Chief Evangelist for Postman I find myself regularly talking to other devrel, advocates, and evangelists who are looking for ideas on how to expand their evangelism toolbox, and be more successful in their work. As part of these conversation I wanted to work my way through my own toolbox to see what is still relevant, and share the tools and tricks I have with other evangelists I am talking with, and hopefully also learn about a few new ones myself, as I engage with different API personalities from across the space.  Much of what I do as the API Evangelist is very formulaic and repetitive. While there is a creative storytelling element as part of these, really the more tangible, repeatable and quantifiable elements of what I do are pretty known, and do not represent any sort of secret sauce or special ability--here are the building blocks of API evangelism you will find in my toolbox. Blog Posts - Publishing a single blog post on a specific topic, process, or idea I think the community will find valuable.  Social Media Post - Publishing single Tweet, LinkedIn, Facebook, or other post to a social network for my profile(s). Questions / Answers - Publishing questions or answers to online properties, helping seed, drive, and amplify conversations. Emails - Craft a newsletter, broadcast, and personalized email involving a specific concept, narrative, or other relevant item. Meetup Talk - A 10 to 30 minute talk to a targeted audience of less than 100 people in a Meetup environment. Conference Talk - A 15 to 60 minute talk to a larger audience of 50 to 500 people in physical conference setting. Webinar Talk - A 15 to 60 minute talk on a specific subject to an online audience via web conferencing platform. Images - Creating an image that represents a specific concept for use across my evangelism activity on and offline. Video -...[Read More]


API Evangelist

API Copyright: Blank Forms

19 Nov 2019

I am gearing up for API copyright heading to the Supreme Court, having another look at whether or not the naming and ordering of your API interface is copyrightable, as well as whether or not reimplementation of it can be considered fair use. To help strengthen my arguments that API should not be copyrightable I wanted to work through my thoughts about how APIs are similar to other existing concepts that are not copyrightable. One of the new concepts I’m looking at understanding better, and add to my toolbox of API copyright arguments is the blank form, which APIs resemble in more than one way. As I was refreshing my understanding of what copyright is and isn’t I was working my way through Copyright.gov, and found this snippet about the copyrightability of forms—which I think applies pretty nicely to what APIs accomplish in a digital way. Blank forms typically contain empty fields or lined spaces as well as words or short phrases that identify the content that should be recorded in each field or space. Blank forms that are designed for recording information and do not themselves convey information are uncopyrightable. Similarly, the ideas or principles behind a blank form, the systems or methods implemented by a form, or the form’s functional layout are not protected by copyright.  A blank form may incorporate Works Not Protected by Copyright 4 images or text that is sufficiently creative to be protected by copyright. For example, bank checks may be registered if they contain pictorial decoration that is sufficiently creative. Contracts, insurance policies, and other documents with “fill-in” spaces may also be registered if there is sufficient literary authorship that is not standard or functional.  In all cases, the registration covers only the original textual or pictorial expression that the author contributed to the work, but does not cover the blank form or other uncopyrightable elements that the form may contain. Examples of blank forms include • Time...[Read More]


API Evangelist

Subway Map Visualization Postman Collection

18 Nov 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. I have been running this on Github using Jekyll, but wanted to make it something that I could keep portable and machine readable so that anyone else could run in locally or on the web.  I haven't hooked the visualization up to any specific APIs yet. I’m going to make it run from my API lifecycle training, allowing users to visualize and then explore the stops along the API life cycle they want. Then I want to see what I can do to hook it up to AWS, Google, and Azure for helping visualize API infrastructure, allowing me to map out different APIs, and organize them into lines based upon OpenAPI tags or Postman collection folders. The Subway Map visualization Postman collection is published as a template in the Postman network, and I have published supporting documentation from the collection. Once I have updated it to work with any particular API I will publish a separate template, keeping this one as my base, but then evolving it to meet different API life cycle and infrastructure needs, helping create a Subway map for navigating the complex API landscapes we are building.[Read More]


API Evangelist

Organizing EC2 API Actions As A Postman Collection

18 Nov 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. You can access the collection here, and the Postman generated API documentation for the AWS EC2 API by clicking on the image below. The Postman collection helps organize the 350+ actions into folders by resource—making them a little easier on the eyes, and to navigate, while also making every AWS EC2 action immediately executable once you publish your keys and secrets to the Postman environment that accompanies the collection. By organizing all of the individual resources into more coherent groups, it increases the chance that the resource you need will be found, and put too use. Account Attributes Describe Account Attributes (Docs) Address To Classic Restore Address To Classic (Docs) Address To VPC Move Address To VPC (Docs) Addresses Allocate Address (Docs) Associate Address (Docs) Describe Addresses (Docs) Disassociate Address (Docs) Release Address (Docs) Aggregate ID Format Describe Aggregate ID Format (Docs) Availability Zones Describe Availability Zones (Docs) BYOIP CIDR Advertise BYOIP CIDR (Docs) Deprovision BYOIP CIDR (Docs) Provision BYOIP CIDR (Docs) Withdraw BYOIP CIDR (Docs) Bundle Task Cancel Bundle Task (Docs) Capacity Reservation Cancel Capacity Reservation (Docs) Create Capacity Reservation (Docs) Modify Capacity Reservation (Docs) Capacity Reservation...[Read More]


API Evangelist

API Copyright Heading To The Supreme Court

17 Nov 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. Google API Fight November 2013 - Putting The Open In API With The API Commons November 2013 - API Commons Is More Than Just The Definition, Specification or Schema December 2013 - It's Between Copyright And Fair Use In Oracle vs Google API Case May 2014 - Where Will Your API Stand In The Oracle v Google API Copyright Debate? May 2014 - Restaurant Menus As Analogy For API Copyright August 2014 - Continuing With The API Restaurant Analogy November 2014 - My Continued Support As Signer Of Oracle v Google Amicus Brief From EFF August 2015 - What We Can Do To Make A Difference In The Wake Of Oracle v Google API Copyright Case Each time I pick up this torch I have to re-educate myself exactly what copyright is and isn’t, and build upon all my former learnings helping pour the latest batch of concrete that acts as the foundation for my belief system around API copyright, patents, trademark, and licensing. For this round, let’s once again revisit the basics, what is copyright? Copyright is the...[Read More]


API Evangelist

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

13 Nov 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. This bothers me. After over a decade of evangelizing the streamlining of API on-boarding processes, and listening to API management and other API service providers profess how they’ll reduce friction when it comes to putting APIs to work—clearly nothing has changed. Few APIs are truly open, meaning you don’t need any API keys or tokens to access, and the rest of the APIs use a mix of different authentication strategies to secure their APIs—introducing friction for developers and non-developers. This isn’t just a problem for non-developers, it is also a problem for developers, making it pretty challenging to go from learning about a new API to actually making a call to that API. Even with my experience, I find it very difficult to on-board with most APIs—this is a problem. When it comes to putting APIs to work, there are a handful of common areas where friction exist, making it difficult and in many cases impossible to actually make an API call, even once they gone through the hard work of finding an API and learning about what it does: Sign-Up - Finding where you...[Read More]


API Evangelist

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

13 Nov 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. In my opinion, the most common thing that “open API” means is open for business. It has almost nothing to do with API access, but if I was to explore what an honest real world bar for what “open API” SHOULD mean, here is a list of things I would consider. First, I’d say that being an open API is not black or white, but more many shades of gray, resulting in a laundry list of things API providers and consumers should be considering when they wield the term. Discovery - Can I find the API? Is it easy to discover and explore for any potential consumer. Portal - Is the landing page or portal for the API accessible to the public, allowing me to learn about the API. Docs - Is there complete, up to date API documentation for the API that is accessibly publicly. Paths - Do developers have access to all of the paths that are available for the API made available. Enumerators - As a developer do I have access to all enumerated values that can be used for an...[Read More]


API Evangelist

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

13 Nov 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. Most people, developer or non-developers just see a mobile application when looking at the icons available on our mobile devices. When I look at them, I just see APIs. The mobile applications are just a Hollywood facade, and it is APIs that move data and content back and forth between mobile phones and the platforms behind each application. It is APIs that broadcast our locations, access our cameras, and use our microphone and speakers. APIs are the plumbing behind the applications we depend on, but do not receive much of the conversation and attention when it comes to privacy, security, and the observability of our personal and professional data resources—this is a problem, and we need to invest more in helping educate folks about the API pipes just below the surface. Even when APIs are hidden behind mobile applications they are still public APIs. Even though these APIs may not have not be published via a public developer portal, they still use public DNS and are accessible simply by running am mobile application through a proxy. These APIs should be receiving the same amount of attention, scrutiny, and auditing as any other public API. We should be having open discussion around...[Read More]


API Evangelist

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

13 Nov 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.example.com portal to visit for every domain. I don’t think we should be getting rid of centralized API portals and catalogs for companies, but I am questioning (as I always do) the belief systems we have in place, wondering if we’ve become trapped by our own narratives along the way. I feel like many APIs I use do not need wider availability via a central API catalog and it helps to just be able to provide URLs to the API documentation, which should give me everything I need to on-board and being putting an API to work. Not all APIs are ready for prime time, and just needs sharing amongst a tighter group of shareholders, and depending on the life cycle and evolution of the API, it may or may not need publishing to central catalog. If an API possesses a dedicate URL to a landing page with the essential building blocks like sign-up, documentation, code snippets, support, TOS, and other essential building blocks, does it need to be published to a single, comprehensive API portal? I am noticing that the operation...[Read More]


API Evangelist

Thinking About Data and API Governance As Well As Observability

11 Nov 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. I learned a lot listening to these smart folks share their expertise on the world stage, and I mostly just listened and absorbed what was going on around me, occasionally sharing a bit of perspective from my view of the landscape. I have a much more technical view of the landscape, but I am captivated by the policy level discussions that were going on, which are much more closer to what I consider to be the human side of the discussion, and how laws are made to dictate what happens or doesn’t happens in countries around the globe. Coming out of the discussion I wanted to flesh out the building blocks of my technical view of the landscape, and re-evaluate them in terms of what I have heard at the event. Bringing APIs To The Data Governance Discussion This was a data governance discussion, but of course I’m going to bring the API to the table. You can’t talk data governance without talking APIs. Data is the valuable resource(s) being created, passed around, and put to use—APIs are how...[Read More]


API Evangelist

Getting You Up To Speed On API Definitions

11 Nov 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. I consider an API definition to cover a wide variety of specifications that have contributed to how data is made accessible via APIs. These definitions span the last twenty years of web service and API development, and are currently being used to define, deliver, and evolve API infrastructure that power desktop, web, mobile, device, and network applications and system to system integrations. Think of API definitions as the restaurant menus to the buffet of resources needed to power the web, mobile, and connected device world that has exploded over the last twenty years. These API definitions provide developers, and business users with the information they need to understand the capabilities that exist behind leading technology platforms like Twitter, Facebook, Google, and others. When it comes to API definitions, there are a handful of stand out specifications that should be considered when getting up to speed on the world of APIs: Web Service Description Language (WSDL) - WSDL is an XML format for describing network services as a set of endpoints operating on messages containing either document-oriented or procedure-oriented information Swagger 2.0 - Swagger was a project used to describe and document RESTful APIs that use HTTP 1.1...[Read More]


API Evangelist

A Postman Collection As Unit of Compute For The API Lifecycle

11 Nov 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.  A Postman collection doesn’t just just act as a reference for an API, it can be a reference of the API for a variety of contexts and workflows. The collection can possess a variety of API paths across a single, or multiple APIs. One Postman collection can have multiple Postman environments that represent a variety of context—possessing different authentication scenarios, and pre-populated variables that illicit different responses from each API. These reference and workflow collections, complete with environment(s) are portable and shareable units of representation of any single API, or meaningful business capabilities that exist across multiple API providers. This portable, machine readable unit of compute becomes something that can be used by both API provider and API consumer to engage in more meaningful, and automated ways across almost every stop along the API life cycle.  I spoke of how I use a Postman collection as a executable unit of compute for API discovery, and search, but other stops along the API life cycle might also include API monitoring and performance, using a reference or workflow collection to represent a specific business capability that needs monitoring to ensure the service level agreement is being met. You can see this...[Read More]


API Evangelist

What Is Behind The CLI Making A Comeback?

05 Nov 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. CLI seemed to be on equal footing with API in those days, but as the popularity of web APIs grew, the CLI didn’t seem to keep up. APIs always seemed more accessible to non-developers, and this was a significant portion of its appeal and growth beyond just the developer community. However, in recent years, CLI seems to be picking up momentum, and at first glance it feels like it is about the adoption of a CI/CD way of doing things, but I don’t want to just assume, I’d like to spend more time thinking about it, and solicit the opinion of other folks I know and trust in the space. Is CLI growth about CI/CD, or are there other factors at play here that is causing its resurgence across the API sector.Beyond the growth in CI/CD, one of the other reasons I think there is a growth in CLI usage is that more enterprise developers are on-boarding to the concept of API platforms, and looking to get access to these valuable API resources that are emerging. These...[Read More]


API Evangelist

Nobody Has API Governance Figured Out

05 Nov 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. Nobody has it nailed, everyone wants to, and everyone is very nervous about not having it all figured out.Defining what API governance means is hard work, let alone making it a reality across a large enterprise organization. API governance is not an end state, it is a perpetual approach to standardizing how APIs are delivered and consumed internally and externally across the enterprise. Due to the ever changing state of the enterprise and turnover of staff you will never realize any perfect state of API governance. Your anxiety around doing it right, doing it well, and the scope of doing it, shouldn’t get in the way of you investing in the area of API governance. However, you should let your fear of missing out light the fire under your ass when it comes to this investment, because I can almost guarantee your competitor is doing it better than you are—so get to work right now! ;-)API governance begins with conversations around what it means to your organization. It involves bringing together business and technology leadership to establish a definition of what it means, and why you are doing it. Like the rest of API governance this definition will continually...[Read More]


API Evangelist

Most API Definitions Are Just Fan Fiction

04 Nov 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.You can find professional level OpenAPI fan fictions sites like APIs.guru. As well as hundreds of little pockets of fan fiction littering GitHub, often tagged so they can be found via GitHub topics. You can find my index of API fan fiction on GitHub too. I also have scripts who crawl GitHub looking for API fan fiction, as well as API fiction, and non-fiction. I fancy myself as a curator of the stories being told and retold out there, but also someone who tells stories about the stories I hear. Think of me as the TMZ of the API sector. Ok, at this point, you are probably asking why this is relevant to you. Well, fan fiction is an important expression out of your API community. It is a positive sign that your community is crafting OpenAPI definitions and Postman collections for your API, but it might also be a cry for help, and something you should consider when considering creating your own API definitions, and making sure they are available to your community.First, fan fiction API definitions show that people care about your API—this is good. Second, it shows that people have a need for machine readable definitions of...[Read More]


API Evangelist

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

04 Nov 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.Let’s start with deployment. I use this term because of the definition, “the arrangement or distribution (of resources such as people or equipment), in preparation for battle or work”. While my view of the world has shifted in recent years, I grew up captivated by everything military, and the word deployment made sense in my brain when it comes to making resources available. After more thought, I also like it because once you deploy an API, you are responsible for it until it is no longer deployed. Even though I know this is’t the case, I like to think that a team who is responsible for deploying an API is responsible for it until it isn’t deployed anymore, much like a military unit.Similar to deployment, I like the term provide, because it makes me feel like there is a continued ownership or stewardship for the resource. If you provide an API, you have to support it, own it, and be responsible for what happens down the road. You aren’t just checking some box, and moving on, which I think represents...[Read More]


API Evangelist

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

01 Nov 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.Shit storming within an organization is where everyone is running around with their hair on fire on a regular basis. So often, it is seen as normal, and most people don’t think anything of it. It is an environment where most ideas are suppressed, and people do not share what they are thinking, acting in passive aggressive ways, or just waiting until the right moment and acting out with actual aggression. It is an environment where most people just keep their heads down and try to do the best they can with what they have, and a small handful of people get to dictate where things are headed without much feedback from other stakeholders. While this approach to delivering API infrastructure may be common, it doesn’t have to be considered normal. Some people thrive in these environments, because they are able to adapt and stay afloat amidst the chaos. In my experience these situations arise over time as part of regular waves of dysfunction, bad decision making, and re-enforced by leadership that doesn’t not reward honest feedback from their teams. Resulting in APIs that get developed in isolation, absent of nutrient delivering feedback loops, and the essential building blocks that help ensure APIs make a positive impact. Setting...[Read More]


API Evangelist

Pushing Us To Think Externally Is The Most Important API Lesson

01 Nov 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. Even if this other party is just another internal group within our organizaiton, we are now being pushed to think externally outside our group. If you are even braver and will be opening up an API for partner access, the external forces being let in will be even greater. With the publishing of public APIs, you are pushing your organization even further when it comes to thinking beyond your own echo chamber. Not every organization will actually open up and immediately change as a result of opening up to the world, but the impact will still be there, even if not consciously realized. Making for a pretty interesting mix of how API providers dip their toe in the water, wade in, or just dive straight into the deep ened of the API pool. Resulting in a diverse range of outcomes that may or may not benefit the organization or group exposing the API.For many, the sunlight entering the room once an API is exposed will be swift and painful, resulting in a backlash, and the API in question being severely limited, left idle, or completely walked away from. Most organizations had no idea what they were doing by...[Read More]


API Evangelist

Profiling The bunq Banking API

31 Oct 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." Providing me with what I need to know in 5 seconds or less, setting the tone for our relationship, and planting a seed in my mind regarding what bunq is all about. bunq's business objective is pretty clear. I don't have to hunt around, and my profiling of the Fintech platform is already off to a good start. Overview Details The bunq profiling begins with three key links, that put you on the home page for bunq, introduce you to what they are all about with their about page, or land you directly in their developer portal, letting you quickly get up to speed on what is possible when you integrate bunq into an application. Website - The website for bunq. About - The about page for bunq. Developers - The developer portal for bunq. You quickly get an idea for what bunq does across these three pages. It allowed me to immediately get up to speed on what they do, and understand the scope of investment they've made in their platform. Employing the three most common building blocks to help on-board new API consumers...[Read More]


API Evangelist

A Diverse API.json Index Example For Slack

31 Oct 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. Providing a diverse example of how you can use APIs.json as an index for your API infrastructure. Slack has an OpenAPI, AsyncAPI, and JSON Schema available on GitHub, but to round off the index I wanted to make sure there was also a Postman collection present. First off, I am painfully reminded of the irony in the name of APIs.json coupled with the fact that I'm using YAML. I prefer the readability of YAML when it comes to storytelling, Beyond this, you can see I have two separate APIs indexed, along with a set of common building blocks of the operations supporting the two APIs. Demonstrating how APIs.json doesn't copete with OpenAPI, Postman collections, or AsyncAPI, it actually compliments it and provides a way of indexing multiple types of APIs that are working in concert. I am working to update the APIs.json website, and put some more energy into the specification. You'll notice I use a lot of vendor extensions to reflect where I'd like to be going next with the API discovery format. Right now, I am just looking to showcase how it can be used as an index of...[Read More]


API Evangelist

Why Are APIs Better Than Direct ODBC / JDBC Connections?

30 Oct 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. APIs share state plus actions. — Matt Bishop (@MattBishopL3) October 28, 2019 Why do I just want to turn the key and start my car as opposed to stick two hot wires together?Abstractions help make my life easier. — Dan Moore (@mooreds) October 28, 2019 Easier instrumentation and insightful usage analytics. And also the security point mentioned above - defense in depth. — Evan Scheessele (@evansche) October 28, 2019 Better safeguards, tracking, and overall much easier to integrate with applications. Almost anything can make a web call (assuming http apis), that is for better, or worse (like IoT). — Dev Odyssey (@Dev_Odyssey) October 29, 2019 APIs shift the focus from data structure implementation to message-based system interactions — LaunchAny / James Higginbotham (@launchany) October 28, 2019 so much yes to this. services are not about providing access to data. they are about exposing ways to interact with capabilities. these things are less similar than it initially sounds like... — Erik Wilde (@dret) October 28, 2019 This is an absolutely necessary discussion, because the answer, strangely, is not self-evident at all.It is incredible how non-intuitive APIs are, even for insiders... — stankov (@stankov) October 28, 2019 Copying my RT Incase...[Read More]


API Evangelist

Managing Your API Definitions On GitHub

30 Oct 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. I recommend that other API providers do this, providing a single API definitions repository, and managing the following API definitions within the repository: OpenAPI - Publishing API definitions for HTTP 1.1 APIs. AsyncAPI - Publish API definitions for HTTP 11.1, HTTP/2, and TCP APIs. JSON Schema - Publish the schema for all objects to GitHub. Postman Collections - Publish reference and workflow Postman collections. Postman Environments - Publish the Postman environments. ALPS Profiles - Publish your ALPS profiles to your GitHub repository. If there are other API definition formats you use, publish them all to the same repository. Then wrap them all in a single APIs.json index, providing a manifest for the machine and human readable elements of your API operations. bunq provides Postman collection for their banking API, and they also provide two separate environment definitions, one for the PSD2 compliant sandbox environment, and the other for the PSD2 compliant production environment. Managing the reference definition for the API, as well as the machine readable Postman environment files for the virtualized and production environments.I am reworking my API catalog currently, where I possess almost 100,000 individual API definitions for APIs across...[Read More]


API Evangelist

API Environments Are An Essential Format For Our API Definition Toolboxes

30 Oct 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. Within the Postman platform you can define one or many Postman environments, and use them across your workspace and collections. Postman environments are simply a list of key value pairs that can be use to define variables in use across the request elements of the API calls you are making. Which can then be outputted as a simple JSON definition, and then published, shared, and used in API services and tooling. Any variable defined within an environment can be referenced as part of each request header, path, query, or body parameter, and used within pre-response scripts. Defining and standardizing the values we use across our API calls, allowing us to pre-populate values we employ, and managing the secrets we employ as part of API authentication. Allowing us to iterate upon the environments we employ, evolving and shifting how we put APIs to work with small variations and iterations in our enviornments. Once I have my environments defined, I can apply them by placing variables within each API request. Putting in headers, and , , and other within each API request. Which allows me to quickly switch environments to make different API requests without having to change...[Read More]


API Evangelist

A Dedicated Open Source Page For Your API Platform

30 Oct 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. Overview: FMA - Tag Line - Simple phrase describing open source at an organization. Mission / Purpose - Stating the purpose of doing open source. Influential Quotes - Sharing quotes with influential stakeholders. Why Open Source? - Explaining the reason why an organization is doing it. Process -- Google has robust overview of how they do open source. Core: Projects - Open source projects owned by the organization. 3rd Party - External open source project being used. Categories - Breaking projects down by simple categories. Communication: Blog - Having a blog or channel dedicated the open source efforts. GitHub - Using Github to host page, projects, and communicate. Twitter - Using Twitter as a social media communication channel. Support: Forum - Providing a forum for supporting open source efforts. Feedback - Establishing a feedback form for users take advantage of. Contributing - Providing guidelines for how the community can contribute. Talk to Expert - Offer up a way fr the community to talk with experts. Discovery Search - Ensuring there is a way to search across open source offerings. Stars - Exposing the stars for projects derived from GitHub. Forks - Exposing the number of times a projects has been forked on GitHub. Innovation: Incubator - Providing details on a project incubation program....[Read More]


API Evangelist

The PSD2 Sandbox From Banking API Provider bunq

29 Oct 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. To help jumpstart developers, bunq provides their PSD2 compliant sandbox where you can generate a pseudo certificate, and get to work developing your application on top of the bunq sandbox API.The bunq PSD2 sandbox API provides different interaction abilities based upon your role, adding another interesting dimension to the sandbox, targeting specific personas defined by the EU banking regulation: Account Information Service Provider (AISP) - With AISP you get to read account information like: legal name, IBAN, nationality, card validity data, account balance and transaction history. Payment Initiation Service Provider (PISP) - With PISP you can read account information including legal name and IBAN. You can also initiate payments. In addition to providing documentation for PSD2 service providers, bunq also provides documentation for helping service providers move to production once they have successfully developed and tested their application against the sandbox API. Providing a pretty solid look at how an API provider can operate a sandbox, but also an example of how industry API standards and regulation can be emulated within sandbox environments, helping standardize how industry compliant applications are developed.I am...[Read More]


API Evangelist

Portable No-Code Way Of Sending an SMS With Nexmo

29 Oct 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. There are other parameters you can include, and of course you have to pass in your API key and secret, but overall it is a pretty simple, straightforward API that anyone can put to work. To help me learn more about the Nexmo API while also providing a usable example that anyone can run I published a Nexmo Postman collection, as well as a Postman environment. You can import into your Postman client or use the Run in Postman button below. You will have to sign up for your own Nexmo API key, add add your key and secret to the Postman environment, but once you have you should be able to send an SMS to any number you choose. I will be creating more Postman collections for other Nexmo APIs, publishing them individually, as well as publishing a complete collection containing all of them when I am done. I want the individual Postman collections for referencing within specific stories, but I also want the entire collection for indexing all the capabilities of the telco API provider. If there are any particular Nexmo APIs you’d like to see published, please let me know, and I’m happy...[Read More]


API Evangelist

20 Open Source Landing Pages From Leading API Providers

29 Oct 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. Google Stripe Twilio Netflix Facebook Twitter LinkedIn Pinterest Dropbox Microsoft Uber Lyft Box Paypal Salesforce Shopify Adobe Hubspot Intuit Tableau These 20 API providers offer up a bunch of lessons for me when it comes to showcasing open source as part of their operations. Next I will be going through each of these pages and documenting the common building blocks in use, and assemble a master list of elements other API providers should think about when it comes to showcasing their open source offerings. Helping demonstrate that API providers aren't just about APIs, and they also actively invest in giving back with open source. I have always tracked on open source pages for the API I profile, but it hasn't really been a priority. I'm going to bump it up in priority, and eventually publish an industry guide for other API providers to use when planning their own open source showcase. I know that many of my readers would rather have a checklist they can use when planning their own efforts, and have a list of links to click on when looking for inspiration from...[Read More]


API Evangelist

The SalesForce API Could Use A Little Modernization

28 Oct 2019

I regularly find myself shining a spotlight on the SalesForce API, holding it up as an example of why APIs matter. They are the OG API pioneer, and 20 years later they are still rocking it with their APIs. With that said, their API approach is in desperate need of some modernization. I don’t want to shame the folks operating things now, they’ve done a great job, but as someone who looks at a lot of APIs, every time I have to roll up my sleeves and implement an integration with SalesForce, I find it all to be much more cumbersome than it should to be.After almost 20 years, the value is evident within the SaleSforce REST API, but there are so many other supporting APIs, SDKs, and other resources, that the core Force.com REST API seems to get lots in the shuffle. Not that my opinion matters all that much, but I wanted to take a few moments to share my views, in hopes someone at SalesForce might read this, or at the very least help other API think more deeply about how to keep their APIs modern and useful for their consumers--here are a handful of things I’d suggest the SalesForce developer community consider as they look towards the future. Information - I have integrated with SalesForce over 50 times, and even though I know what I need, I always get lost wading through the volume of information that exists within the developer portal. It takes me a click, a significant amount of scrolling, and a second click to get to the REST API documentation that I need. I get it, there is an amazing number of resources available, but I’m afraid the core value of the Force.com REST API gets lost in the shuffle. I know what I need and I get lost, I can only imagine how confusing it is for new developers. Authentication - The OAuth implementation and documentation is...[Read More]


API Evangelist

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

28 Oct 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.I know it may seem like more information is better, but most of the time developers will just need a summary of an API that is less than 50 characters, and a description that is less than 250 characters. The path, parameters, headers, body, and resulting response should tell the rest of the story. If you have to list too many parameters, enumerators, and write a chapter about what is possible with a single API path, then you probably need to spend more time refining the design of the API. I just don’t have the time to read multiple paragraphs about what each API path does, I want the design of the API request and response to tell the story for me in a standardized way that makes sense.Take the time to think about your consumers when writing your API documentation. Better yet, rely on the schema for OpenAPI, Postman collections, and other machine readable definitions to provide the constraints necessary to distill down the human readable portions of your API definitions. Both of these API definition formats provide you with a limited about of space to tell your story, and populate what is needed for publishing coherent API documentation. Pushing you to fill...[Read More]


API Evangelist

Individual API Life Cycle Stops And Operational Life Cycle Stops

28 Oct 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. It takes a lot more work to make sure that the things which can be reused and replicated across APIs are identified. It usually takes someone paying attention to the bigger picture, helping connect the dots, and lending a hand in helping developers work together and follow standards that have been set to help insure quality, consistency, along the way. Helping identify common patterns in use, documenting them, and then working to educate, disseminate, and incentivize their usage and adoption. Turning healthy practices into well-defined stops along the API life cycle, and minimizing the unique special snowflake status of each individual API we deliver.Letting API developers operate in isolation is how we end up with many different kinds of APIs, across different teams and groups. If you have ever used a large public API provider like Google, Amazon, or Azure, you’ve noticed that not all the APIs are designed the same. While there may be similarities across them, there are often little difference that can cause friction all along the way, resulting in challenges for developers when building their applications. I’m always looking for ways to help developers see the big picture beyond what they are working on,...[Read More]


API Evangelist

Embedding JSON-LD To Power API Discovery

28 Oct 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. Their API is well designed, and their developer portal is full of all the essential building blocks you need to successfully operate an API. To help make the bunq API more discoverable, bunq has embedded a set of JSON-LD references within the HTML for their website, providing Schema.org representations for their business. This JSON-LD snippet isn’t focused particularly on their API, but it does designate bunq as a BankorCreditUnion, and provides some additional context about their business. If I were bunq, I’d consider adding Schema.org representations for as many of their API resources as they can. Providing more machine readable context about the potential that is available within the bunq banking APIs. This is something that all API providers should consider when it comes to publishing their own company website and developer portal, helping make the resources you offer more discoverable by web and API search engines. In addition to publishing JSON-LD Schema.org representations for all of your API resources, I also recommend you publish one for the WebAPI object type which is currently being evolved, and additional usage always helps evolve each schema standard. I’d like to see more tooling emerge to help API...[Read More]


API Evangelist

Sometimes My Desire To Automate Is More About Laziness Than Innovation

25 Oct 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. I’ve gone down the automation road many of time only to establish pretty quickly that something isn’t even possible, or that the quality of the results would be much below what I could deliver if I just rolled up my sleeves and did it manually. Over the years I’ve learned to step away from the allure of automation, but it is still something that I still find myself thinking about way too much, simmering on some automation scheme, procrastinating about how much work something is, where if I just did the task manually, I could get done in half the time.As I dig into my API-driven automation fantasies I usually return pretty quickly with a realization that things are more about me being lazy or a procrastinator. I hate to admit it, but I think a significant portion of my belief in technology in my desire to get out of some work, avoid a mundane task, and accomplish some meaningless thing that I’ve convinced myself is important, when it probably is not. Often times...[Read More]


API Evangelist

Some API Evangelism Metrics

21 Oct 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.Much of the content I produce for API Evangelist is pretty spontaneous, however it has always followed the path of my overall API research. Using the areas of research, and the stops along the API life cycle that I’ve established over the years as a framework for the development of my storytelling. Over the years I have produced content in all of these areas, but in the future I am looking to be more deliberate and consistent in how I roll out new content, spreading things equally across the different areas of the API life cycle, but also making available in the following formats, leveraging a variety of delivery mechanisms. Short Form (Blogs) - Publishing blog posts for publishing to API Evangelist, Postman, and other locations. Long Form (White Papers) - Producing white papers that cover every area of my API life cycle research. Webinars (Video) - Participating in regular webinars addressing each stop along the API lifecycle. Tutorials (Video, Audio) - Creating a regular stream of tutorials walking users through API concepts. Conference & Meetups (Talk) - Carving out different areas of the API lifecycle to talk about in person. Workshops...[Read More]


API Evangelist

It Is Difficult To Know Where To Begin With APIs

21 Oct 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.Adding to the mix of complexities to articulate about the world of APIs, there are many different capacities in which you can engage with APIs. Opening up a handful of opportunities for developers, and non-developer individuals to roll up their sleeves and get involved. Many discussions around APIs will center on being an API provider, someone is making APIs available, or you are an API consumer, and you are putting APIs to work. The consumption of APIs is where most people start, but then learning about developing and operating APIs also dominates the conversation because of the commercial opportunity that has evolved over the last decade, making it a popular place to begin. Additionally, there are a handful of other doors we like to open when it comes to introducing people to APIsFocusing Just On Consuming APIsUsing an API is the easiest place to begin when beginning your API journey. You are more likely to find your way forward with APIs if you get started with a single API provider, or category of APIs that align with interests you already have, helping connect...[Read More]


API Evangelist

Documentation Pushes The Human Readability of Your API Definitions

21 Oct 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. API definitions are primarily used for API documentation, and secondarily used for API mocking, testing, monitoring, security, code generation, and other stops along the API life cycle. While all of these stops along the API life cycle help contribute to the maturity and robustness of your API definitions, heavy investment in API documentation will ave the greatest ROI when it comes to making an impact on our human stakeholders. Helping attract users to your APIs, on-boarding them with less friction, and help increase their adoption and integration of resources into their applications. Take the time to add summaries and descriptions to each path in your API definitions. Make sure that every request body and response has an example. Ensure that you take the time to be concise, but informative when crafting the API definitions—your API documentation will be better off for it. Make sure you aren’t hand-rolling your API documentation and are taking advantage of the wealth of OpenAPI and Postman collection driven documentation solutions. These types of API documentation just look better, and help reduce friction when on-boarding new developers, and giving existing API developers what they need when they come back to learn about new APIs, and expand their usage of existing APIs....[Read More]


API Evangelist

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

18 Oct 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.While there are people who will stop, listen, and over time internalize what I’m sharing with them, the majority of people will show no interest, avoid, and even resist what I’m putting on the table. I have to realize and accept that most of these people will never convert, and become believers. If I am going to be successful, I’m going have to find ways of herding these folks along, trick them into contributing, and I guess in some situations force them to be compliant. But do I want to do this? There has to be other more creative ways of educating folks and getting them on board. I mean, I’m write aren’t I? My solution is the logical solution? Let’s explore the possibilities: Maybe I Am Wrong - Lets start with the obvious and most painful. Maybe I’m wrong. Maybe we shouldn’t be doing APIs. Maybe my way of doing APIs isn’t right. This one gets at the very foundation of my being, my existence. Maybe these people smell something I don’t, and my suggestions for doing APIs in a particular way is a bad idea. I’m going to simmer on this one...[Read More]


API Evangelist

Well-Defined API Workflows Are Sign Of API Maturity

15 Oct 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.API workflows are all about getting us past the caveman CRUD grunts and groans we use to communicate with our API resources, and begin to actually use real words and phrases to describe a series of API calls that accomplish something with real world business values. Having a machine readable reference for all of our APIs is essential, making sure that every path is well documented and accessible by developers. However, also having a machine readable definitions for our workflows that help us articulate how the most common and valuable API workflows should occur is a sign of maturity in our APIs, our process, and how we articulate this value to developers and end-users.When crafting API workflows, the place to begin involves stitching together your own APIs to recreate the most relevant workflows that are already present in your applications. This helps you think through the business value that your APIs deliver, helping you smooth out the rough edges around how things work (or don’t). Another important aspect of this effort is to make sure that you are also weaving in partner and other 3rd party APIs as part of this workflow development, enriching and adding value to your own APIs, and expanding the reach of the business value your API workflows deliver. Exposing your...[Read More]


API Evangelist

Introductory API Concepts Are Timeless

15 Oct 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.As long as API Evangelist is operating, I will always be reworking how I tell stories that target API newbies. I always find it valuable to force myself to step back from what I know and how I articulate the vast world of APIs to folks who are just learning about APIs. It is vital to the sector that we are always educating and on-boarding new voices, and we should all be working to equip all skill levels with our API evangelism, communication, and training. Ensuring that we aren’t just leveling up in everything we do, and we continue to reach as wide as possible audience as we can with our storytelling. Forcing ourselves to re-evaluate how we articulate our API practices to others, refine our storytelling, documentation, and other resources—considering how they will be viewed by newcomers, as well as the veterans who depend on our services.Regular investment in introductory API concepts helps us stay grounded, remember how we got here, and ensure we keep the rope ladder available for others to get to the same...[Read More]


API Evangelist

Are You The API Librarian Within Your Organization?

14 Oct 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.As we’ve seen by the rise of Facebook, Twitter, and other data rich platforms, having access to relevant data at scale is where the new revenue opportunities are, which in turn has shifted where folks go for information, knowledge, and access to the power within an industry, or a specific organization. Moving databases online has changed how value is created, and power is amassed, something that web APIs has fueled, being behind almost every major shift in the technological landscape over the last 20 years. Making those who know how to discover, create, and put APIs to work part of the new class of player who gets to dictate what goes on in the web and mobile shifts in the business landscape. Elevating the relevance of those of who mind to the technical details of APIs we create and depend on within our organizations, making them the next generation of...[Read More]


API Evangelist

Most API Owners Are Just Focused On Issues

10 Oct 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.I may be able to get my stories read by API architects, designers, and developers, but if I can’t figure out how to make them more applicable in their day, I’m not going to make a difference. To help me shape my storytelling I want to better understand the challenges on the ground, and regularly document the common challenges so that I can actually craft not just stories that are relative, but also create collections and influence other Postman features that might actually reduce friction wherever I can, to help give people more room. So, what are some of the common challenges my readers face? Bugs - Every one of my readers faces a steady stream of bugs in the APIs, and applications they are in charge of. Regularly distracting them from the work that will move things forward making most feel like they are always drowning. Infrastructure Failures - When you are running large scale systems there will always be infrastructure challenges involve failures, bottlenecks, and limitations imposed by the infrastructure in place, and the impact of decisions made, or not made. Productivity Losses...[Read More]


API Evangelist

Learn to API

10 Oct 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.There is nothing stopping normal everyday folks from knowing what an API in its most basic form, and understanding that they exist behind all of the desktop, web, mobile, and device applications we use each day. There is no reason average business people can’t move data, content, and media around between the services they use each day. There are plenty of low-code or no-code solutions for putting APIs to work, and there are a growing number of baked in integrations available with the common business and consumer applications we are already using. The only thing stopping people from learning to APIs is the perceived notion that programming is out of their reach, and something that they don’t have have the capacity to understanding, which is a concept perpetuated by a specific class of technological wizards who want to keep this world for our own.It will be a regular mission of mine to craft blog posts, white papers, and tutorials that help the average business person learn to API. Working hard to reduce the complexity involved...[Read More]


API Evangelist

Making Your API Collection The Tutorial

08 Oct 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.The one thing I want to help people understand is that your Postman collection should be the tutorial. It is fine to have all the content and screenshot fluff around it, as this helps you with SEO, discovery, and other things, but everything you describe int he tutorial should be actionable in your Postman collection—this is the purpose behind collections! Postman collections excel at containing all of the detail you need to walk folks through making API calls in a portable, shareable, executable unit of representation for your API. Making it so that your audience can take the tutorial with them, play with it in their own environment, and the best thing is that it stays around in their application development environment until they remove it, providing a potentially ongoing reference for them at some point in the future—making your tutorials stickier.It takes experience to be able to craft a meaningful Postman collection, going beyond just a basic reference of your API. It isn’t something I”m very good at yet, but will spend time honing and polishing. As I...[Read More]


API Evangelist

Capital G API Governance vs Lowercase g API Governance

08 Oct 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.I have come across numerous enterprise groups who have begun putting in place capital G governance as part of an organized effort, only to encounter resistance on the ground across teams. Resistance from folks on the ground range from not understanding what is being mandated, having better ideas on what can be done, or simply just being against anything that leadership proposes. Governance is hard work, and something that can be fraught from the beginning, depending on the nature of your organization and the industry you operate in. When I first began studying the world of API governance I was pretty against the term and the concept, but over the years I’ve learned more about what t takes to do APIs at scale across large organizations and I changed my tune. I would say after about seven years, I’m slowly drifting back towards thinking governance might do more harm than good.I am a fan of organizations having API design, deployment, management, testing, and other guidance in place, helping govern how APIs are delivered. However, within large organizations I have begun to see more examples of how capital G API Governance can become at odds with...[Read More]


API Evangelist

Increasing API Adoption and Consumption

07 Oct 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. I would break these things into two distinct categories: 1) increasing your understanding of how your APIs work (or don’t), and 2) increasing your understanding of the context in which your consumers operate within. While you may be focused on how to get a users adopting a specific API endpoint, you may not be thinking about the lack of flow between each of your API endpoints, and you probably aren’t fully up to speed on your consumers workflow, and how the two do not match up. Which is more about how you define and design your APIs, and get to know your consumers, then it is about actual adoption or consumption.Reference API Design Versus Workflow API DesignWhen I talk with API providers about why people aren’t using their APIs I find the most of the time there has been little consideration for how those APIs should be used prior to them being released into production. Most APIs I come across are purely reference-based designs. Meaning they reference the resources being made available, but do not speak to how they will actually be put to use. API providers who are just beginning...[Read More]


API Evangelist

Getting API Providers To Step Up to SLOs/SLAs

07 Oct 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. Getting API Providers To Publish Well Designed APIs - Not all groups have the skills and know how to publish well designed web APIs to a shared catalog. Getting API Providers To Care About Reliability and Performance - Most providers will see the publishing of the API as checking the box, not reliably operating. Getting API Providers To Care About API Consumers - Even with APIs published and reliably operated, most providers won’t care about those who put to use. It is tough to find groups and teams who will fire on all cylinders in these areas, especially without a clear definition regarding what is required to play in this game. Since this question was asked in context of not just SLAs, but also SLOs, I...[Read More]


API Evangelist

Conducting An API Landscape Analysis

07 Oct 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. Possessing no formal strategy for how data is created, published, shared, centralized, distributed, or made available via APIs. Resulting in most organizations having no idea of where their digital assets are, and what their organizational capabilities are.My low hanging fruit process involves spidering a domain looking for CSV, JSON, and XML files, as well as identifying pages that have tables and forms on them. I’ve done this for several organizations who have paid me, a handful of others where people who work there asked me to do it, as well as for organizations that I find interesting and work to identify the API low hanging fruit for my own purposes. I use it to gain a better understanding the digital capabilities of an organizations, but it is also work that has got me in trouble after applying it to the University of Oklahoma, uncovering some spreadsheets that shouldn’t have been made public, and attracting the attention of the institution’s leadership. It all worked out, but for a little while they were considering calling the FBI on me--it all provides an important story about how we manage our digital assets, and making sure we have a comprehensive strategy for how we publish data, what should be...[Read More]


API Evangelist

API Provider On-Boarding Best Practices

07 Oct 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. Make it dead simple to signup, obtain access keys, and begin making calls on the API you make available. As technologists, we excel at over thinking things, and assuming everyone has the same view of the landscape as we do, when in reality we suck at explaining how we got here, and are notorious for leaving obstacles in our potential consumers way. Here are the main areas I invest in when it comes to reducing friction for developers when it comes to on-boarding with our APIs. Documentation - Provide modern, complete, and up to date documentation for your API powered by an API definition (OpenAPI, Postman)—do not hand-roll your own documentation. Keep your summaries, and description simple, intuitive, and informative, and as yourself how you can get out of developers way with regular refinements. Getting Started - Craft a simple yet comprehensive getting started page for your new developers, breaking everything that is needed to get up and running. This is your opportunity to regularly revisit your on-boarding process, reduce friction, remove the sharp edges, and unnecessary steps. Run In Postman - If you have an OpenAPI, generate a Postman collection, and make sure it is...[Read More]


API Evangelist

Personal API Tokens For All APIs Please

04 Oct 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.OAuth isn’t great, but its the best we got at the moment when it comes to authorization. It is also one of the biggest obstacles for many developers, and all non-developers, when it comes to putting API resources, and most egregiously their own data and content that is available via APIs, to work. I don’t have a problem with pushing developers who are building an application to leverage the standard OAuth interfaces and flow. You definitely want to build a Postman collection for them, and make signing up, and adding an application to obtain your key as frictionless as possible. But, for quickly on-boarding developers, and non-developers quickly to be able to play around, kick the tires, and understand what an API does, you should be providing personal access tokens. The personal access token topic is one of the reasons I do API Evangelist. So I can find incremental improvements in the core standards and technologies we already use, that make our lives easier—then beat the drum about why everyone should do it. This is a topic I should be publishing a story about every quarter until I see movement by providers. Helping API provider...[Read More]


API Evangelist

Getting Started With Postman Templates

04 Oct 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.You can find Postman templates in the Postman API development environment (ADE) by clicking on the big orange “New” button in the top left corner of the application—it is a tab on the popup window that comes up. You can browse by category, or you can search using a keyword. Here are three of the templates that Joyce shared with us: Visualizer Examples - This collection contains two sample templates for visualizing data returned as part of an API response, one rendering data as a table, and the other renders data as a bar graph. Intro to Writing Tests - This collection contains examples of tests that you can use to automate your testing process. Includes basic test syntax, examples of API tests, and integration tests. Working with GraphQL - This collection introduces you to the GraphQL functionality that Postman supports, demonstrating how Postman can be used for more than just working with web APIs. While playing around with Postman templates, I came across a handful of others that I think are interesting in what they deliver, but also in the way that they demonstrate how Postman templates, and the resulting collections can be used for so much more than just API reference: MOCKS: fake it till you...[Read More]


API Evangelist

API First With Legacy APIs

03 Oct 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.I got to work creating a Postman collection for my API, mapping out the surface area of the legacy version of my tagging API. I needed to understand the paths and variables I had on this API that came together over a couple of years, and has had several tweaks and adjustment since it was first conceived. Currently  it has the following resources: Tag - A single word or phrase that adds to my tag vocabulary. Children - I can relate tags to tags, allowing me to infinitely group. URLs - I can associate multiple URLs with any single tag. Images - I can add an image for each of the tags that I define. Transformation -  An index of words I transform automatically. Dictionary - An entire diction of all the words for verifying tags. I regularly apply my tags across all of my primary resources. I depend on my tags to help me organize information, and make sense of my API research. I’m going to keep the tag and children endpoints basically the same, but I’m going to change how I handle URLs and images.  I’m also looking to make some modifications on...[Read More]


API Evangelist

API Collaboration Is The Next Killer Feature

03 Oct 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. One of the things that attracted me to the potential of APIs back in 2010 when I first started doing this, was the way APIs brought me out of my shell. As a database administrator I had grown accustom to be siloed. Just leave me alone. Let me do what I do. Keep those business people at a distance. The only problem with this reality was I kept getting further and further away from the business problems I was working to solve, which resulted in some pretty catastrophic mistakes. Then I made the mistake of deciding to take management route with my career, which then resulted in the opposite problem—I was too close to the business problems, and too far away from the technical solutions. I wasn’t coding anymore. I couldn’t deliver the solutions I was needing. I realized that I needed a bridge between business and development, and APIs seemed like the solution to me. APIs force us out of our bubbles. It forces us to integrate with other internal groups, partners, or public users. The killer feature of APIs is interoperability, allowing us to have...[Read More]


API Evangelist

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

02 Oct 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.First, let’s start with the quickest, easiest, and most reusable approach to sharing API responses—sharing a Postman collection. This is the most informative and educational way to get the job done, allowing you to actually make the request you desire, save not just the response, but also the details of the request, and share with any other user. This is important, because anyone you are sharing your response with can actually re-run the request, maybe change some parameters or other values, hit save, and share not just the results, but also their changes back to the original user. Plus Postman allows you share in multiple ways, publishing documentation and a run in Postman button, via a simple link, or if the user is part of your team, you can share the collection into a workspace that the team member has access to. This is the most productive way to be sharing API responses. Do this please. Stop sharing responses via email.Next, if you are going to insist on using email, just send a link to your response. Ideally you are sharing the link to the Postman collection, but at the very least, publish the JSON response to a public or private GitHub Gist, or other platform, and only...[Read More]


API Evangelist

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

02 Oct 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.Most of the organizations that I go into do not possess any formal strategy for how APIs are brought to life. Some have API catalogs or directories where you can find APIs, but they are rarely complete, and might provide the basics of API discoverability, but provide little visibility into the teams behind them. Most of the time, APIs do not make it into the catalog until the API makes its way into a production state, leaving it pretty impossible to discover APIs that are being planned, designed, or in the process of being developed, and there isn’t any way to understand which teams are planning APIs, or beginning to work on the development of new resources. Leaving API leadership working to paint a more complete picture of what teams are working on, what processes are I place for developing APIs, and how efficient groups are when it comes to delivering critical resources.Some of the folks I am talking to are relying on the tooling they’ve adopted to provide them with some of the metrics they require to gain more visibility into how teams operate (ie. GitHub, Postman, etc.). Most...[Read More]


API Evangelist

REST And Hypermedia And GraphQL And gRPC And Event-Driven

01 Oct 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.I’ve had a front row seat for several new technologies to emerge within the API sector, and with each one there is always an aggressive group of technologists who like to employ a pretty old and tired API trope that the new technology is the future, and what already is represent the wrong, or out of date way of doing things. It is what vendors do to dethrone what came before, and try to get a foothold within markets. Playing on a popular belief that technology is perpetually moving faster than ever before, and you have to always be buying into what is next, otherwise you will miss out on the future, and be eaten alive by your competition. If a vendor, blogger, or analyst is saying that one API technology will completely replace another API technology, and the previous way is the wrong way, I recommend moving on, finding other sources of information to educate yourself and inform your organization’s overall API strategy.REST Is Where You BeginThe API haters love to bash on RESTful design practices. However, the reality...[Read More]


API Evangelist

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

01 Oct 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.Most API architectects, designers, and developers agree that if you can successfully define, design, mock, document, and engage with stakeholders before you formalize your APIs, deploying as code, and launching into production, you will be better off. By doing this, you are shortening the feedback loop with other API stakeholders regarding what they API should and shouldn’t do, and increasing efficiency, agility, while saving resources when it comes to delivering API infrastructure. The biggest challenge with this approach is that once you are ready to actually deliver an API, you still end up having to write code, a process which can potentially orphan the agreed upon API contract that was crafted as part of the API define / design first process, and thus the code then becomes the truth. Leaving most developers wondering where the benefits are when it comes to moving to an API define / design first approach. There are some API gateways that will let you take an OpenAPI, or other API definition and publish your API, and there are server-side code generation solutions for taking API definitions and producing much of the code you need to deploy, but both approaches...[Read More]


API Evangelist

API Evangelist API Industry Guide: Regions

01 Oct 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. Making it very realistic and cost effective to deliver API infrastructure in a variety geographic regions. To help API providers understand the growing importance of how geographic regions can be leveraged, I distilled down my API regions research into the follow areas, resulting in this guide that is full of considerations to share with your team when thinking about how to go global with your API operatons. Regional API Deployment - Setting the stage for the regional deployment of your APIs. Cloud Computing Fundamentals - Acknowledging the role the cloud computing providers play. Regional Service Availability - Looking at the uneven landscape of services that are available. Other Regional API Services - Moving beyond the cloud computing providers to understand regional availability. Why Deploy APIs In Multiple Regions - Looking at the reasons behind regional API deployment and availability. Multi-Region API Deployment Considerations Deployment - What you should be thinking before you deploy in multiple regions. Availability - Understanding how availability is impacted with different regions. Operations - Considering how you should be operating across various regions. Orchestration - Looking at how you can orchestrate across your regions. Revenue - Thinking...[Read More]


API Evangelist

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

30 Sep 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.While the tutorials and other technical storytelling are critical, one aspect of evangelism that isn’t always addressed by API providers and service providers is content that is accessible and relevant to business and technical leaders. Helping them understand why APIs are important, and get enough information on various stops along the API lifecycle, and other important aspects of delivering APIs reliably, ensuring they are making informed decisions when it comes building teams, crafting budgets, and other important aspects of operations that will make or break your API program. If your leadership isn’t on board with what is going on, the chances you will be able to realize the change you envision with your API effort will be drastically diminished, and you will be always struggling to stay afloat and properly invest in what is needed to find your way forward in any meaningful way.I love being down in the weeds with APIs. Making requests to existing APIs, and designing new and interesting APIs. However, I also realize the importance of me zooming out, thinking about how business leaders can be engage to make sure they are up...[Read More]


API Evangelist

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

30 Sep 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.json indexes for each domain, complete with JSON Schema, JSON examples, OpenAPI, and Postman collecitons for reach individual data set being made available--providing a pretty robust look at what APIs.json brings to the table. I will be adding more properties to each of the individual public data domain APIs.json indexes, linking to the other resources that Socrata provides--more tightly coupling APIs.json with all available resources. I am using the same approach to map out the DKAN and CKAN ecosystems, layering these dimensions of the public data universe into my master catalog of the sector. I am also going to play around with creating overall OpenAPI and Postman collections for reach individual domain, breaking individual data sets into groups defined by tags. My biggest challenge here is not all of the data sets are properly tagged, so I need to work some tagging voodoo on each my APIs.json indexes, harvesting meaningful tags from the title, description, and other meta data for the public data I've catalogued. This is timely work, as I prepare to refresh the APIs.json and API Commons websites, and underlying specifications. As I prepare for heading up to the API Specification Conference...[Read More]


API Evangelist

The Developer On-boarding Use Case For Postman

26 Sep 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. Postman has broken down the developer on-boarding use case into four easy to follow areas, breaking out some of the ways in which Postman is being used to get new users up to speed in a very hands on way, that really is the best way to learn an API in a way that will ensure it is much more sticky then just reading documentation. Their developer on-boarding use case provides what you need to quickly reach new users, and keep them engaged with the API lifecycle, allowing you to engage with developers who are actually contributing to the delivery of an API, or with consumers who will be putting it to use within their particular applications. Here are the core building blocks of how Postman is being used when it comes to developer on boarding—on both the provider and consumer side of things. 1. Understand the API - Making sense of internal or external APIs using the API browser environment. Explore the API - Being able to kick the tires and see what an APIs I all about, making sense of internal or external APIs. Import API Specification - Import a Swagger, OpenAPI, RAML and other specification and play with...[Read More]


API Evangelist

I Understand That Not Everyone Wants To Use The Command Line

26 Sep 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. I would say I don’t love it, we are more old friends that get along well, but we don’t see each other as much as we used to.I would say my biggest challenge with the command line and using cURL is that I”m just not as efficient and knowledgable as I should be in this environment. Sure, I have spent countless hours on Stack Overflow copying and pasting cURL and other commands, and I’ve even bought a couple of books. The problem is the knowledge doesn’t ever stick around in my head, and I tend to add snippets to my collection of scripts and CLI commands, but I’ve never been able to make things stick in my brain. I think it is the old 486 processor, and limited storage situation. Maybe it was the 60s. IDK. Regardless, I can empathize when folks are apprehensive about using the command line. I work hard to not make them feel stupid about it and do what I can to help them in crafting commands, teaching them whatever I can, or just introduce them to Postman.In my many years evangelizing APIs outside the echo chamber amongst the...[Read More]


API Evangelist

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

26 Sep 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.  I guess I am trying to better understand what different organizations are measuring when it comes to understanding all of this. We generally say that we can move faster, but specifically what does moving faster actually mean? I am trying to think through some of the details of what I should be measuring with each team, so that I can better articulate and visualize what exactly faster means. Which of these areas matter the most? Teams - Are we measuring the speed at which teams operation, helping them get more work done? APIs - Are we measuring the number of APIs delivered? If so, how are we quantifying the scope of each API being delivered? Applications - Are tracking the number of applications being developed? If so, how are we defining the scope of each App? Releases - Are we measuring the number of version releases? If so, are we looking at major, minor, and impact of patch? Features - Are we tracking on the number of features being delivered that actually impact the end-users? Tickets - If we are...[Read More]


API Evangelist

Simple Or Complex API Collections For Different Levels Of API Consumers

25 Sep 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.As a seasoned API veteran, when on boarding with a new API I tend to like to see the full menu being offered, but this belief system regularly leaves me drowning in a state of information overload. Some API providers have hundreds, or thousands of APIs, and depending on the quality of API design and documentation this can be both a good or a very bad thing. To help reduce this overload in their own communites I’ve been seeing some Postman customers crafting specialized on-boarding collections that help define the APIs most new developers are going to care about, pre-populated with the parameters, values, and other details that reduce the friction for them when on-boarding. Helping us get more precise in how we craft our API definitions, being more thoughtful in how we name, organize, and document our APIs using collections—rather than just dumping an overwhelming number of API paths, parameters, schema and documentation on someone.I am going to take some of the more robust API collections I have defined in my API workspaces and begin crafting a more simpler, entry level version of the same collection—with fewer endpoints, and...[Read More]


API Evangelist

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

25 Sep 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. Postman collections define the surface area of a API just like OpenAPI. I fully understood this. I also grasped that it went beyond OpenAPI in acting as more of executable representation of an API. Meaning you can populate parameter values, and use variables as part of Postman environments, creating and versioning different collections for the same API, allowing it to be executed in a variety of scenarios. What I didn’t get was how you can label and organize different scenarios and workflows into different folders, and how pre-execution, tests, and monitors can be applied against collections, folders, and that there is different levels of variable and script scoping dependent on how you structure your collections. I know us pundits like to call OpenAPI definitions API contracts, but they are void of the dynamic variables, environment, testing, and monitoring that is required to truly be a contract--this isn't so with Postman collections.I have been increasingly excited about the executable potential of Postman collections over OpenAPI’s static nature. Sure, it can be used for making actual API requests, but it doesn’t have all the nuts and bolts of making that...[Read More]


API Evangelist

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

25 Sep 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.Many APIs are born out of database backends, with very little design applied to the APIs externalizing the database tables. Because of this most APIs offer Create, Read, Update, and Delete (CRUD) functionality with the parameters reflecting the core elements of a SQL Query. In these situations, database developers assume that consumers will possess enough knowledge about the underlying schema and requiring them to fill in the blanks of what fields should be returned, and the details of the where clause determining which records will be returned. Missing the point of what APIs are all about, and workig harder to externalize the rich resources available within database tables by providing intuitive paths, parameters, and other elements that help any consumer understand what is possible. Database developers who deploy APIs make these mistakes over and over again, making many assumptions about what other developers will know and not know, introducing unecessary friction for developers...[Read More]


API Evangelist

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

24 Sep 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. Making the documenting and mocking of APIs very straightforward and logical for me. I will be stepping through my API profiling process again and writing a fresh post on how I profile the operational and API level data of the companies, organizations, institutions, and government agencies I’m covering. Have an example of each API request to not just round off the definition of an API so I have an understanding of the schema being applied is valuable, but I’m finding that making sure I have it in service of documentation, mocking, testing, and other essential stops along the lifecycle makes it more meaningful and valuable. Personally, I want the request and response for each API I’m profiling to help increase the surface area of each API I have for better search-ability. However, thinking about making it so anyone can find the API and more easily put it to use with more complete documentation is another bar to set for my profiling work—making I more valuable to my audience.Managing my profiling of APIs using Postman and specifically as Postman collections is changing I’m profiling the API sector, and how I see the API lifecycle. I’ve long...[Read More]


API Evangelist

Enabler Mock Data APIs Alongside Other APIs Within My Collections

24 Sep 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. They provide a wealth of ways (PDF, Excel, YAML) to get what fields you can filter by, but not any more information on useful and accepted values for those parameters.For what I was working on, I needed two lists of values: 1) brands, and 2) active pharmaceutical ingredients. Without them you have to kind of just bumble around until you find the right values, and slowly reverse engineer what the possibilities are. These types of gaps are common with API providers, and maybe the FDA has the values somewhere else on their website, but I can’t seem to find them. I looked for a while and then began widening my scope beyond what the FDA provides, finding brands on Wikipedia, and active pharmaceutical ingredients on another 3rd party site. These tables can quickly be converted into CSV and then JSON files, which I can then turn into mock APIs using Postman collections. All I do is create new requests for my mock endpoints, add the resulting JSON as an example, and then publish my collection as a new mock server. I can tweak my variable urls for the live and mock versions to accommodate localized versions living side...[Read More]