The API Evangelist Blog - 2018

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


Asking The Honest Questions When It Comes To Your API Journey

27 November 2018
I engage with a lot of enterprise organizations in a variety of capacities. Some are more formal consulting and workshop engagements. While others are just emails, direct messages, and random conversation in the hallways and bars around API industry events. Many conversations are free flowing, and they trust me to share my thoughts about the API space, and provide honest answers to their questions regarding their API journey. Where others express apprehension, concern, and have trouble engaging with me because they are worried about what I might say about their approach to doing APIs within their enterprise organizations. Some have even told me that they’d like to formally bring me in for discussions, but they can’t get me pass legal or their bosses–stating I have a reputation for being outspoken...

A Diverse API Toolbox Driving Hybrid Integrations Across An Event-Driven Landscape

25 November 2018
I’m heading to Vegas in the morning to spend two days in conversations with folks about APIs. I am not there for AWS re:Invent, or the Gartner thingy, but I guess in a way I am, because there are people there for those events, who want to talk to me about the API landscape. Folks looking to swap stories about enterprise API investment in possessing a diverse API toolbox for driving hybrid integrations in an event-driven landscape. I’m not giving any formal talks, but as with any engagement, I’m brushing up on the words I use to describe what I’m seeing across the space when it comes to the enterprise API lifecycle. The Core Is All About Doing Resource Based, Request And Response APIs Well I’m definitely biased, but I do not subscribe to popular notions that at some point REST, RESTful, web, and HTTP APIs will have to go away...

YAML API Management Artifacts From AWS API Gateway

23 November 2018
I’ve always been a big supporter of creating machine readable artifacts that help define the API lifecycle. While individual artifacts can originate and govern specific stops along the API lifecycle, they can also bring value when applied across other stops along the API lifecycle, and most importantly when it comes time to govern everything. The definition and evolution of individual API lifecycle artifacts is the central premise of my API discovery format APIs.json–which depends on there being machine readable elements within the index of each collection of APIs being documented, helping us map out the entire API lifecycle. OpenAPI provides us with machine readable details about the surface area of our API which can be used throughout the API lifecycle, but it lacks other details about the surface area of our API operations...

The API Journey

23 November 2018
I’ve been researching the API space full time for the last eight years, and over that time I have developed a pretty robust view of what the API landscape looks like. You can find almost 100 stops along what I consider to be the API lifecycle on the home page of API Evangelist. While not every organization has the capacity to consider all 100 of these stops, they do provide us with a wealth of knowledge generated throughout my own journey. Where I’ve been documenting what the API pioneers have been doing with their API operations, how startups leverage simple web API infrastructure, as well as how the enterprise has been waking up to the API potential in the last couple of years. Over the years I’ve tapped this research for my storytelling on the blog, and for the white papers and guides I’ve produced...

What Does The Next Chapter Of Storytelling Look Like For API Evangelist?

21 November 2018
I find myself refactoring API Evangelist again this holiday season. Over the last eight years of doing API Evangelist I’ve had to regularly adjust what I do to keep it alive and moving forward. As I close up 2018, I’m finding the landscape shifting underneath me once again, pushing me to begin considering what the next chapter of API Evangelist will look like. Pushing me to adjust my presence to better reflect my own vision of the world, but hopefully also find balance with where things are headed out there in the real world. I started API Evangelist in July of 2010 to study the business of APIs. As I was researching things in 2010 and 2011 I first developed what I consider to be the voice of the API Evangelist, which continues to be the voice I use in my storytelling here in 2018...

The Ability To Link To API Service Provider Features In My Workshops And

16 November 2018
All of my API workshops are machine readable, driven from a central YAML file that provides all the content and relevant links I need to deliver what I need during a single, or multi-day API strategy workshop. One of the common elements of my workshops are links out to relevant resource, providing access to services, tools, and other insight that supports whatever I’m covering in my workshop. There are two parts to this equation, 1) me knowing to link to something, and 2) being able to link to something that exists. A number of API services and tooling I use don’t follow web practices and do not provide any easy way to link to a feature, or other way of demonstrating the functionality that exists...

Flickr And Reconciling My History Of APIs Storytelling

06 November 2018
Flickr was one of the first APIs that I profiled back in 2010 when I started API Evangelist. Using their API as a cornerstone of my research, resulting in their API making it into my history of APIs storytelling, continuing to be a story I’ve retold hundreds of times in the conversations I’ve had over the eight years of being the API Evangelist. Now, after the second (more because of Yahoo?) acquisition, Flickr users are facing significant changes regarding the number of images we can store on the platform, and what we will be charged for using the platform–forcing me to step back, and take another look at the platform that I feel has helped significantly shape the API space as we know it...

The Impact Of Travel On Being The API Evangelist

01 November 2018
Travel is an important part of what I do. It is essential to striking up new relationships, and reenforcing old ones. It is important for me to get out of my bubble, expose myself to different perspectives, and see the world in different ways. I am extremely grateful for the ability to travel around the US, and the world the way that I do. I am also extremely aware of the impact that travel has on me being the API Evangelist–the positive, the negative, and the general shift in my tone in storytelling after roaming the world. One of the most negative impact that traveling has on my world is on my ability to complete blog posts. If you follow my work, when I’m in the right frame of mind, I can produce 5-10 blog posts across the domains I write for, on a daily basis...

What Are Your Enterprise API Capabilities?

22 October 2018
I spend a lot of time helping enterprise organizations discover their APIs. All of the organizations I talk to have trouble knowing where all of their APIs are–even the most organized of them. Development and IT groups have just been moving too fast over the last decade to know where all of their web services, and APIs are. Resulting in large organizations not fully understanding what all of their capabilities are, even if it is something they actively operate, and may drive existing web or mobile applications. Each individual API within the enterprise represents a single capability. The ability to accomplish a specific enterprise tasks that is valuable to the business. While each individual engineer might be aware of the capabilities present on their team, without group wide, and comprehensive API discovery across an organization, the extent of the enterprise capabilities is rarely known...

Join Me For A Fireside Chat At The Paris API Meetup This Wednesday

22 October 2018
I am in Europe for most of October, and while I am in Paris we thought it would be a good idea to pull together a last minute API Meetup. Romain Simiand (@RomainSimiand), the API Evangelist at PeopleDoc was gracious enough to help pull things together, and the Streamdata.io team is stepping up to help with food and drink. Pulling together a last minute gathering at PeopleDoc in Paris, and bringing me on stage to talk about the technology, business, and politics of APIs, well as about some of my recent work on API discovery, and event-driven architecture. You can find more details on the Paris API Meetup site, with directions on how to find PeopleDoc. Make sure you RSVP so that we know you are coming, and of course, please help spread the word...

I Participated In An API Workshop With The European Commission Last Week

22 October 2018
I was in Ispra, Italy last week for a two day workshop on APIs with the European Commission. The European Commission’s DG CONNECT together with the Joint Research Centre (JRC) launched a study with the purpose to gain further understanding of the current use of APIs in digital government and their added value for public services, and they invited me to participate. I was joined by Mehdi Medjaoui (@medjawii), David Berlind (@dberlind), and Mark Boyd (@mgboydcom), along with EU member states, and European cities, to help provide feedback and strategies for consideration by the commission. This European Commission study is looking at “innovative ways to improve interconnectivity of public services and reusability of public sector data, including dynamic data in real-time, safeguarding the data protection and privacy legislation in place...

API Evangelist API Lifecycle Workshop on API Design

11 October 2018
I’ve been doing more workshops on the API lifecycle within enterprise groups lately. Allowing me to refine my materials on the ground within enterprise groups, further flesh out the building blocks I recommend to API groups to help them craft their own API strategy. One area of the API lifecycle I find more groups working on these days, centers around a design-first approach to the API lifecycle. While not many groups I work with achieved a design-first approach doing APIs, almost all of them I talk to express interest in making this a reality at least within some groups, or projects. The appeal of being able to define, design, mock, and iterate upon an API contract before code gets written is very appealing to enterprise API groups, and I’m looking to help them think through this part of their API lifecycle, and work towards making API design first a reality at their organization...

API Evangelist API Lifecycle Workshop on API Discovery

11 October 2018
I’ve been doing more workshops on the API lifecycle within enterprise groups lately. Allowing me to refine my materials on the ground within enterprise groups, further flesh out the building blocks I recommend to API groups to help them craft their own API strategy. One of the first discussions I start with large enterprise groups is always in the area of API discovery, or commonly asked as, “do you know where all your APIs are?” EVERY group I’m working with these days is having challenges when it comes to easy discovery across all the digital resources they possess, and put to use on a daily basis. I’m working with a variety of companies, organizations, institutions, and government agencies when it comes to the API discovery of their digital self: Low Hanging Fruit (outline) - Understanding what resources are already on the public websites, and applications, by spidering existing domains looking for data assets that should be delivered as API resources...

A Quick Manual Way To Create An OpenAPI From A GET API Request

09 October 2018
I have numerous tools that help me create OpenAPIs from the APIs I stumble across each day. Ideally I’m crawling, scraping, harvesting, and auto-generating OpenAPIs, but inevitably the process gets a little manual. To help reduce friction in these manual processes, I try to have a variety of services, tools, and scripts I can use to make my life easier, when it comes to create a machine readable definition of an API I am using–in this scenario it is the xignite CloudAlerts API. One way I’ll create an OpenAPI from a simple GET API request, providing me with a machine readable definition of the surface area of that API, is using Postman. When you have the URL copied onto your clipboard, open up your Postman, and paste the URL with all the query parameters present...

The Layers Of Completeness For An OpenAPI Definition

09 October 2018
Everyone wants their OpenAPIs to be complete, but what that really means will depend on who you are, what your knowledge of OpenAPI is, as well as being driven by your motivation for having an OpenAPI in the first place. I wanted to take a crack at articulating a complete(enough) definition for OpenAPIs I create, based upon what I’m needing them to do. Info & Base - Give the basic information I need to understand who is behind, and where I can access the API. Paths - Provide an entry for every path that is available for an API, and should be included in this definition. Parameters - Provide a complete list of all path, query, and header parameters that can be used as part of an API...

API Evangelist And Streamdata.io API Lifecycle Workshops

08 October 2018
I have been partnering with Streamdata.io to evolve how I work with enterprise groups on their API lifecycle strategy. After working closely with the Streadata.io sales team, it became clear that many enterprise organizations weren’t quite ready for the event-driven infrastructure Streamdata.io provides. Most groups were in desperate need of stepping back and developing their own formal strategy for delivering APIs across the enterprise, before they could every scale their operations and take advantage of things being more event-driven and real time. In response, I set out to evolve my own API lifecycle research, gathered over the last eight years of studying the API space, and make it more accessible to the enterprise, as self-service short form and long form content, in-person workshops, and forkable blueprints that any enterprise can set in motion on their own...

API Developer Outreach Research For The Department of Veterans Affairs

28 September 2018
This is a write-up for research I conducted with my partner Skylight Digital. The team conducted a series of interviews with leading public and private sector API platforms regarding how they approached developer outreach, and then I wrote it up as a formal report, which the Skylight Digital team then edited and polished. We are looking to provide as much information as possible regarding how the VA, and other federal agencies should consider crafting their API outreach efforts. This is Skylight’s report for the U.S. Department of Veterans Affairs (VA) microconsulting project, “Developer Outreach.” The VA undertook this project in order to better understand how private- and public-sector organizations approach Application Programming Interface (API) developer outreach...

Having The Dedication To Lead An API Effort Forward Within A Large Enterprise

20 September 2018
I work with a lot of folks who work in large enterprise organizations, institutions, and government agencies who are moving the API conversation forward within their groups. I’m all too familiar with what it takes to move forward the API conversation within large, well established enterprise organizations. However, I am the first to admit that while I have a deep understanding of what it involves, I do not have the fortitude to actually lead an effort for the sustained amount of time it takes to actually make change. I just do not have the patience and the personality for it, and I’m eternally grateful for those that do. There are regular streams of emails in my inbox from people embedded within enterprise organizations, looking for guidance, counseling, and assistance in moving forward the API conversation at their organizations...

Understanding The Event-Driven API Infrastructure Opportunity That Exists

18 September 2018
I am at the Kong Summit in San Francisco all day tomorrow. I’m going to be speaking about research into the event-driven architectural layers I’ve been mapping out across the API space. Looking for the opportunity to augment existing APIs with push technology like webhooks, and streaming technology like SSE, as well as pipe data in an out of Kafka, fill data lakes, and train machine learning models. I’ll be sharing what I’m finding from some of the more mature API providers when it comes to their investment in event-driven infrastructure, focusing in on Twilio, SendGrid, Stripe, Slack, and GitHub. As I am profiling APIs for inclusion in my API Stack research, and in the API Gallery, I create an APIs...

Talking Healthcare APIs With The CMS Blue Button API Team At #APIStrat In

18 September 2018
We have the API evangelist from one of the most significant APIs out there today at #APIStrat in Nashville next week. Mark Scrimshire (@ekivemark), Blue Button Innovator and Developer Evangelist from NewWave Telecoms and Technologies will be on the main stage next Tuesday, September 25th 2018. Mark will be bringing his experience helping stand up the Blue Button API with the Centers for Medicare and Medicaid Services (CMS), and sharing the stories from the trenches while delivering this critical piece of health API infrastructure within the United States. I consider the Blue Button API to be one of the most significant APIs out there right now for several key factors: API Reach - An API that has potential to reach 44 million Medicare beneficiaries, which is 15 percent of the U...

Justifying My Existence In Your API Sales And Marketing Funnel

17 September 2018
I feel like I’m regularly having to advocate for my existence, and the existence of developers who are like me, within the sales and marketing funnel for many APIs. I sign up for a lot of APIs, and have the pleasure of enjoy a wide variety of on-boarding processes for APIs. Many APIs I have no problem signing up, on-boarding, and beginning to make calls, while others I have to just my existence within their API sales and marketing funnel. Don’t get me wrong, I’m not saying that I shouldn’t be expected to justify my existence, it is just that many API providers are setup to immediately discourage, create friction for, and dismiss my class of API integrator–that doesn’t fit neatly into the shiny big money integration you have defined at the bottom of your funnel...

Being Open Is More About Being Open So Someone Can Extract Value Than Open

17 September 2018
One of the most important lessons I’ve learned in the last eight years, is that when people are insistent about things being open, in both accessibility, and cost, it is often more about things remaining open for them to freely (license-free) to extract value from it, that it is ever about any shared or reciprocal value being generated. I’ve fought many a battle on the front lines of “open”, leaving me pretty skeptical when anyone is advocating for open, and forcing me to be even critical of my own positions as the API Evangelist, and the bullshit I peddle. In my opinion, ANYONE wielding the term open should be scrutinized for insights into their motivations–me included. I’ve spend eight years operating on the front line of both the open data, and the open API movements, and unless you are coming at it from the position of a government entity, or from a social justice frame of mind, you are probably wanting open so that you can extract value from whatever is being opened...

I Am Needing Some Evidence Of How APIs Can Make An Impact In Government

17 September 2018
Eric Horesnyi (@EricHoresnyi), the CEO of Streamata.io and I were on a call with a group of people who are moving forward the API conversation across Europe, with the assistance of the EU. The project has asked us to assist them in the discovery of more data and evidence of how APIs are making an impact in how government operates within the European Union, but also elsewhere in the world. Aggregating as much evidence as possible to help influence the EU API strategy, and learn from what is already being done. I’m heading to Italy next month to present to the group, and participate in conversations with other API practitioners and evangelists, so I wanted to start my usual amount of storytelling here on the blog to solicit contributions from my audience about what they are seeing...

"Sadly Stack Exchange Blocks API Calls Being Made From Any Of Amazons IP Block"

17 September 2018
I am developing an authentication and access layer for the API Gallery that I am building for Streamdata.io, while also federating it for usage as part of my API Stack research. In addition to building out these catalogs for API discovery purposes, I’m also developing a suite of tools that allow users to subscribe to different topics from popular sources like GitHub, Reddit, and Stack Overflow (Exchange). I’ve been busy adding one or two providers to my OAuth broker each week, until the other day I hit a snag with the Stack Exchange API. I thought my Stack Exchange API OAuth flow had been working, it’s been up for a few months, and I seem to remember authenticating against it before, but this weekend I began getting an error that my IP address was blocked...

Providing Minimum Viable API Documentation Blueprints To Help Guide Your API

13 September 2018
I was taking a look at the Department of Veterans Affairs (VA) API documentation for the VA Facilities API, and intending on providing some feedback on the API implementation. The API itself is pretty sound, and I don’t have any feedback without having actually integrated it into an application, but following on the heals of my previous story about how we get API developers to follow minimum viable API documentation guidance, I had lots of feedback on the overall deliver of the documentation for the VA Facilities API, helping improve on what they have there. Provide A Working Example of Minimum Viable API Documentation One of the ways that you help incentivize your API developers to deliver minimum viable API documentation across their API implementations is you do as much of the work for them as you can, and provide them with a forkable, downloadable, clonable API documentation that meets the minimum viable requirements...

Please Refer The Engineer From Your API Team To This Story

13 September 2018
I reach out to API providers on a regular basis, asking them if they have an OpenAPI or Postman Collection available behind the scenes. I am adding these machine readable API definitions to my index of APIs that I monitor, while also publishing them out to my API Stack research, the API Gallery, APIs.io, work to get them published in the Postman Network, and syndicated as part of my wider work as an OpenAPI member. However, even beyond my own personal needs for API providers to have a machine readable definition of their API, and helping them get more syndication and exposure for their API, having an definition present significantly reduces friction when on-boarding with their APIs at almost every stop along a developer’s API integration journey...

Some Ideas For API Discovery Collections That Students Can Use

10 September 2018
This is a topic I’ve wanted to set in motion for some time now. I had a new university professor city my work again as part of one of their courses recently, something that floated this concept to the top of the pile again–API discovery collections meant for just for students. Helping k-12, community college, and university students quickly understand where to find the most relevant APIs to whatever they are working on. Providing human, but also machine readable collections that can help jumpstart their API education. I use the API discovery format APIs.json to profile individual, as well as collections of APIs. I’m going to kickstart a couple of project repos, helping me flesh out a handful of interesting collections that might help students better understand the world of APIs: Social - The popular social APIs like Twitter, Facebook, Instagram, and others...

Stack Exchange Has An API That Returns The Details For All Of Your Access

10 September 2018
I’m a big fan of helpful authentication features, where API providers make it easier to manage our increasingly hellish environment, application, token, and other management duties of the average API integrator. To help me better manage my API apps, and the OAuth tokens I have in play, I am trying to document all the sensible approaches I come across while putting different APIs to work, and scouring the API landscape for stories. One example of this in action is out of the Stack Exchange API, where you can find an API endpoint for accessing the details of your OAuth tokens, and invalidate, and de-authorize them. A pretty useful API endpoint when you are integrating with APIs, and find yourself having to manage many tokens across many APIs, apps, and users...

The Path To Production For Department of Veteran Affairs (VA) API Applications

07 September 2018
This post is part of my ongoing review of the Department of Veteran Affairs (VA) developer portal and API presence, moving on to where I take a closer look at their path to production process, and provide some feedback on how the agency can continue to refine the information they provide to their new developers. Helping map out the on-boarding process for any new developer, ensuring they are fully informed about what it will take to develop an application on top of VA APIs, and move those application(s) from a developer state to a production environment, and actually serving veterans. Beginning with the VA’s base path to production template on GitHub, then pulling in some elements I found across the other APIs they have published to developer...

An API Value Generation Funnel With Metrics

07 September 2018
I’ve had several folks asking me to articulate my vision of an API centric “sales” funnel, which technically is out of my wheelhouse in the sales and marketing area, but since I do have lots opinions on what a funnel should look like for an API platform, I thought I’d take a crack at it. To help articulate what is in my head I wanted to craft a narrative, as well as a visual to accompany how I like to imagine a value generation funnel for any API platform. I envision a API-driven value generation funnel that can be tipped upside down, over and over, like an hour glass, generating value is it repeatedly pushes API activity through center, driven by a healthy ecosystem of developers, applications, and end-users putting applications to work / use...

My API Storytelling Depends On The Momentum From Regular Exercise And Practice

06 September 2018
I’ve been falling short of my normal storytelling quotas recently. I like to have at least 3 posts on API Evangelist, and two posts on Streamdata.io each day. I have been letting it slip because it was summer, but I will be getting back to my regular levels as we head into the fall. Whenever I put more coal in the writing furnace, I’m reminded of just how much momentum all of this takes, as well as the regular exercise and practice involved, allowing me to keep pace in the storytelling marathon across my blog(s). The more stories I tell, the more stories I can tell. After eight years of doing this, I’m still surprised abut what it takes to pick things back up, and regain my normal levels of storytelling...

Allowing Users To Get Their Own OAuth Tokens For Accessing An API Without The

06 September 2018
I run a lot of different applications that depend on GitHub, and use GitHub authentication as the identity and access management layer for these apps. One of the things I like the most about GitHub and how I feel it handles it’s OAuth more thoroughly than most other platforms, is how they let you get you own OAuth token under your settings > developer settings >personal access tokens. You don’t need to setup an application, and do the whole OAuth dance, you just get a token that you can use to pass along with each API call. I operate my own OAuth server which allows me to authenticate using OAuth with many leading APIs, so generating an OAuth token, and setting up a new provider isn’t too hard...

The Basics Of The VA API Feedback Loop

04 September 2018
I’m working to break down the moving parts of API efforts over at the VA, and work to provide as much relevant feedback as I possibly can. One of the components I’m wanting to think about more is the feedback loop for the VA API efforts. The feedback loop is one of the most essential aspects of doing an API, and is quickly can become one of the most debilitating, paralyzing, and nutrient starving aspects of operating an API platform if done wrong, or non-existent. However, the feedback loop is also one of the most valuable reasons for wanting to do APIs in the first place, providing the essential feedback you will need from consumers, and the entire API ecosystem to move the API forward in a meaningful way...

The Federal Agencies Who Use Their developer.[domain].gov Subdomain

04 September 2018
I was reviewing the new developer portal for the Department of Veterans Affairs (VA), and one of things I took notice of, was their use of the developer.va.gov subdomain. In my experience, the API efforts that invest in a dedicated subdomain, and specifically a developer dot subdomain, tend to more invested in what they are doing than efforts that publish to a subfolder, or subsection of their website. As I was writing this post, I had a question in arise in my mind, regarding how many other federal agencies use a dedicated subdomain for their developer programs–something I wanted to pick up later, and understand the landscape a little more. I took a list of current federal agency domains from the GSA and wrote a little script to append developer...

What Have You Done For Us Lately (API Partner Edition)

04 September 2018
I’ve been working on developing and evolving the Streamdata.io partner program, trying to move forward conversations with other service providers in the space that have existed long before I started working on things, as well as other newer relationships that I’ve helped bring in. I’m fascinated by how partner programs work, or do not work, and have invested a lot of time trying to optimize and improve how I do my own operations, and assist my partners and clients in evolving and delivering on their own partner vision. It is difficult to establish, and continue meaningful and balanced partnerships between technology service and tooling providers. Sometimes providers have enough compatibility and synergy, that they are able to hit the ground running with meaningful activities that strengthen, and build partnership momentum...

Remembering That APIs Are Used To Reduce Everything Down To A Transaction

04 September 2018
This is our regular reminder that APIs are not good, nor bad, nor neutral. They are simply a tool in our technological toolbox, and something that is often used for very dark reasons, and occasionally for good. One of the most dangerous things I’ve found about APIs is just the general thought process that goes along with them, regarding how all roads lead to reducing, and distilling things down to a single transaction. APIs, REST, microservices, and other design patterns are all about taking something from our physical world, and redefining it as something that can be transmitted back and forth using the low cost request and response infrastructure of the web. No matter what you are designing your API for, your mission is to reduce everything to a simple transaction that can be exchanged between your server, and any other system, web, mobile, device, or network application...

Why I Feel The Department Of Veterans Affairs API Effort Is So Significant

30 August 2018
I have been working on API and open data efforts at the Department of Veterans Affairs (VA) for five years now. I’m passionate about pushing forward the API conversation at the federal agency because I want to see the agency deliver on its mission to take care of veterans. My father, and my step-father were both vets, and I lived through the fallout from my step-fathers two tours in Vietnam, exposure to the VA healthcare and benefits bureaucracy, and ultimately his passing away from cancer which he acquired from to his exposure to Agent Orange. I truly want to see the VA streamline as many of its veteran facing programs as they possibly can. I’ve been evangelizing for API change and leadership at the VA since I worked there in 2013...

API Portals Designed For API Provider And API Consumers

29 August 2018
I’ve been working a couple organizations who are struggling with providing information within their API developer portal intended for API publishers, pushing their API portal beyond just being for their API consumers. Some of the folks I’ve been working with haven’t thought about their API developer portals being for both API publishers and consumers, and asked me to weigh in on the pros and cons of doing this. Helping them understand how they can continue their journey towards not just being an API platform, but also an API marketplace. Some of the conversations we were having about providing API lifecycle materials to API developers, helping them deliver APIs consistently across all stops along lifecycle, focused on creating a separate portal for API publishers, decoupling them from where the APIs would be discovered and consumed...

Understanding Where Folks Are Coming From When They Say API Management Is

29 August 2018
I am always fascinated when I get push back from people about API management, the authentication, service composition, logging, analysis, and billing layer on the world of APIs. I seem to be find more people who are skeptical that it is even necessary anymore, and that it is a relic of the past. When I first started coming across the people making these claims earlier this year I was confused, but as I’ve pondered on the subject more, I’m convinced their position is more about the world of venture capital, and investment in APIs, that it is about APIs. People who feel like you do not need to measure the value being exchanged at the API layer aren’t considering the technology or business of delivering APIs...

Helping The Federal Government Get In Tune With Their API Uptime And

28 August 2018
Nobody likes to be told that their APIs are unreliable, and unavailable on a regular basis. However, it is one of those pills that ALL APIs have to swallow, and EVERY API provider should be paying for an external monitoring service to tell us when are APIs are up or down. Having a monitoring service to tell us when our APIs are having problems, complete with a status dashboard, and history of our API's availability are essential building blocks of any API provider. If you expect consumers to use your API, and bake it into their systems and applications, you should committed to a certain level of availability, and offering a service level agreement if possible. My friends over at APImetrics monitor APIs across multiple industries, but we've been partnering to keep an eye on federal government APIs, in support of my work in DC...

Reviewing The Department Of Veterans Affairs New Developer Portal

28 August 2018
I wanted to take a moment and review the Department Of Veterans Affairs (VA) new developer portal. Spending some time considering at how far they’ve come, what they published so far, and brainstorm on what the future might hold. Let me open by saying that I am working directly and indirectly with the VA on a variety of paid projects, but I’m not being paid to write about their API effort–that is something I’ve done since I worked there in 2013. I will craft a disclosure to this effect that I put at the bottom of each story I write about the VA, but I wanted to put out there in general, as I work through my thoughts on what is happening over at the VA. The VA Has Come A Long Way I wanted to open up this review with a nod towards how far the VA has come...

Not All Companies Are Interested In The Interoperability That APIs Bring

28 August 2018
I’ve learned a lot in eight years of operating API Evangelist. One of the most important things I’ve learned to do is separate my personal belief and interest in technology from the realities of the business world. I’ve learned that not all businesses are ready for the change that doing APIs bring, and that many businesses really aren’t interested in the interoperability, portability, and observability that APIs bring to the table. Despite what I may believe, APIs in the real world often have a very different outcome. I see the potential of having a public API developer portal where you publish all the digital resources your company offers. Providing self-service registration to access these digital resources at a fair, transparent, and pay for what you use pricing model...

Trying To Define An Algorithm For My AWS API Cost Calculations Across API

28 August 2018
I am trying to develop a base base API pricing formula for determining what my hard costs are for each API I’m publishing using Amazon RDS, EC2, and AWS API Gateway. I also have some APIs I am deploying using Amazon RDS, Lambda, and AWS API Gateway, but for now I want to get a default base for determining what operating my APIs will cost me, so I can mark up and reliably generate profit on top of the APIs I’m making available to my partners. AWS has all the data for me to figure out my hard costs, I just need a formula that helps me accurately determine what my AWS bill will be per API. Math isn’t one of my strengths, so I’m going to have to break this down, and simmer on things for a while, before I will be able to come up with some sort of working formula...

Do Not Miss Internal Developer Portals: Developer Engagement Behind the

27 August 2018
We are getting closer to the 9th edition of APIStrat happening in Nashville, TN this September 24th through 26th. The schedule for the conference is up, along with the first lineup of keynote speakers, and my drumbeat of stories about the event continues here on the blog. Next up in our session lineup is “Do Not Miss Internal Developer Portals: Developer Engagement Behind the Firewall” by Kristof Van Tomme (@kvantomme), Pronovix (@pronovix) on September 25th. Here is Kristof’s abstract for the API session: While there are a lot of talks and blogposts about APIs and the importance of an APIs Developer eXperience, most are about public API products. And while a lot of the best practices for API products are also applicable to private APIs, there are significant differences in the circumstances and trade-offs they need to make...

Provide Your API Developers With A Forkable Example of API Documentation In

27 August 2018
I responded about how teams should be documenting their APIs when they have both legacy and new APIs the other day. I wanted to keep the conversation thread going with an example of one possible API documentation implementation. The best way to deliver API documentation guidance in any organization is to provide a forkable, downloadable example of whatever you are talking about. To help illustrate what I am talking about, I wanted to take one documentation solution, and publish it as a GitHub repository. I chose to go with a simple OpenAPI 3.0 defined API contract, driving a Swagger UI driven API documentation, hosted using GitHub Pages, and managed as a GitHub repository. In my story about how teams should be documenting their APIs, I provided several API definition formations, and API documentation options–for this walk-through I wanted to narrow it down to a single combination, providing the minimum(alist) viable options possible using OpenAPI 3...

How Do We Get API Developers To Follow The Minimum Viable API Documentation

27 August 2018
After providing some guidance the other day on how teams should be documenting their APIs, one of the follow up comments was: “Now we just have to figure out how to get the developers to follow the guidance!” Something that any API leadership and governance team is going to face as they work to implement new policies across their organization. You can craft the best possible guidance for API design, deployment, management, and documentation, but it doesn’t mean anyone is actually going to follow your guidance. Moving forward API governance within any organization represents the cultural frontline of API operations. Getting teams to learn about, understand, and implement sensible API practices is always easier said than done...

May Contain Nuts: The Case for API Labeling by Erik Wilde (@dret), API Academy

24 August 2018
We are getting closer to the 9th edition of APIStrat happening in Nashville, TN this September 24th through 26th. The schedule for the conference is up, along with the first lineup of keynote speakers, and my drumbeat of stories about the event continues here on the blog. Next up in our session lineup is “May Contain Nuts: The Case for API Labeling“ by Erik Wilde (@dret), API Academy (@apiacademy) on September 25th. I’ll let Erik’s bio set the stage for what he’ll be talking about at APIStrat: Erik is a frequent speaker at both industry and academia events. In his current role at the API Academy, his work revolves around API strategy, design, and management, and how to help organizations with their digital transformation...

Living In A Post Facebook, Twitter, and Instagram API World

24 August 2018
While Facebook, Twitter, and Instagram will always have a place in my history of APIs, I feel like we are entering a post Facebook, Twitter, and Instagram API world. All three platforms are going through serious evolutions, which includes tightening down the controls on API access, and shuttering of many APIs. These platforms are tightening things down for a variety of reasons, which are more about their business goals, than it is about the community. I’m not saying these APIs will go away entirely, but the era where where these API platforms ruled is coming to a close. The other day I articulated that these platform only needed us for a while, and now that they’ve grown to a certain size do not need us anymore...

How Should Teams Be Documenting Their APIs When You Have Both Legacy And New APIs?

24 August 2018
I’m continuing my work to help the Department of Veterans Affairs (VA) move forward their API strategy. One area I’m happy to help the federal agency with, is just being available to answer questions, which I also find make for great stories here on the blog–helping other federal agencies also learn along the way. One question I got from the agency recently, is regarding how the teams should be documenting their APIs, taking into consideration that many of them are supporting legacy services like SOAP. From my vantage point, minimum viable API documentation should always include a machine readable definition, and some autogenerated documentation within a portal at a known location. If it is a SOAP service, WSDL is the format...

Any Way You Want It: Extending Swagger UI for Fun and Profit by Kyle Shockey

23 August 2018
We are getting closer to the 9th edition of APIStrat happening in Nashville, TN this September 24th through 26th. The schedule for the conference is up, along with the first lineup of keynote speakers, and my drumbeat of stories about the event continues here on the blog. Next up in our session lineup is “Any Way You Want It: Extending Swagger UI for Fun and Profit” by Kyle Shockey (@kyshoc) of SmartBear Software (@SmartBear) on September 25th. Here is Kyle’s abstract for the session: Your APIs are tailored to your needs - shouldn’t your tools be as well? In this talk, we’ll explore how Swagger UI 3 makes it easier than ever to create custom functionality, and common use cases for the power that the UI’s plugin system provides...

Getting Email Updates From The API Providers I Care About Is One Way To Stay

23 August 2018
I do not like email. I do not have a good relationship with my inbox. However, it is one of those ubiquitous tools I have to use, and understand the value it can bring to my world. The goal is to not let my inbox control me too much, as my it is is often a task list that other people think they can control. With all that said, I’m finding renewed value in email newsletters, on several fronts. While I’d prefer to get updates via Atom, I’m warming up to receiving updates from API providers, and API service providers in my inbox. I am an active subscriber to the REST API Notes Newsletter, API Developer Weekly, and other relative newsletters. I’m also finding myself opening up more emails from the API providers, and service providers I’m registered with...

The Importance Of Postman API Environment Files

23 August 2018
I’m a big fan of Postman, and the power of their development environment, as well as their Postman Collection format. I think their approach to not just integrating with APIs, but also enabling the development and delivery of APIs has shifted the conversation around APIs in the last couple of years–not too many API service providers accomplish this in my experience. There are several dimensions to what Postman does that I think are pushing the API conversation forward, but one that has been capturing my attention lately are Postman Environment Files. Using Postman, you can manage many different environments used for working with APIs, and if you are a pro or enterprise customer, you can export a file that represents an environment, making each of these API definitions more portable and collaborative...

Testing and Meaningful Mocks in a Microservice System by Laura Medalia

22 August 2018
We are getting closer to the 9th edition of APIStrat happening in Nashville, TN this September 24th through 26th. The schedule for the conference is up, along with the first lineup of keynote speakers, and my drumbeat of stories about the event continues here on the blog. Next up in our session lineup is “Testing and Meaningful Mocks in a Microservice System” by Laura Medalia (@codergirl__) of Care/Of on September 25th. Here is Laura’s abstract for the session: Laura will be talking about tooling for mocking microservice endpoints in a meaningful way using Open API specifications. She will cover how to set up microservice deployments processes so that with each versioned microservice deployed a mock of the service with up to date contracts will also be deployed...

It Is Hard To Go API Define First

22 August 2018
Last year I started saying API define first, instead of API design first. In response to many of the conversations out there about designing, then mocking, and eventually deploying your APIs into a production environment. I agree that you should design and iterate before writing code, but I feel like we should be defining our APIs even before we get to the API design phase. Without the proper definitions on the table, our design phase is going to be a lot more deficient in standards, common patterns, goals, and objectives, making it important to invest some energy in defining what is happening first–then iterate on the API definitions throughout the API lifecycle, not just design. I prefer to have a handful of API definitions drafted, before I move onto to the API design phase: Title - A simple, concise title for my API...

Searching For APIs That Possess Relevant Company Information

22 August 2018
I’m evolving the search for the Streamdata.io API Gallery I’ve been working on lately. I’m looking to move the basic keywords search that searches the API name and description, as well as the API path, summary, and description using a key word or phrase, to also be about searching parameters in a meaningful way. Each of the APIs in the Streamdata.io API have an OpenAPI definition. It is how I render each of the individual API paths using Jekyll and Github Pages. These parameters give me another dimension of data in which I can index, and use as a facet in my API gallery search. I am developing different sets of vocabulary to help me search against the parameters used across APIs, with one of them being focused on company related information...

Describing Your API with OpenAPI 3.0 by Anthony Eden (@aeden), DNSimple

21 August 2018
We are getting closer to the 9th edition of APIStrat happening in Nashville, TN this September 24th through 26th. The schedule for the conference is up, along with the first lineup of keynote speakers, and my drumbeat of stories about the event continues here on the blog. Next up in our session lineup is “Describing Your API with OpenAPI 3.0” by Anthony Eden (@aeden), DNSimple (@dnsimple) on September 25th. Here is Christian’s abstract for the session: For the last 10 years, DNSimple has operated a comprehensive web API for buying, connecting, and operating domain names. After hearing about OpenAPI at APIStrat 2017, we decided to describe the DNSimple API using the OpenAPI v3 specification - this is the story of why we did it, how we did it, and where we are today...

Identifying The Different Types Of APIs

21 August 2018
APIs come in many shapes and sizes. Even when APIs may share a common resource, the likelihood that they are similar in functional, will be slim. Even after eight years of studying APIs, I still struggle with understanding the differences, and putting APIs into common buckets. Think of the differences between two image APIs like Flickr and Instagram, but then also think about the difference between Twitter and Twilio–the differences are many, and a challenge to articulate. I’m pushing forward my API Stack, and API Gallery work, and I’m needing to better organize APIs into meaningful groups that I can add to the search functionality for each of API discovery services. To help me establish a handful of new buckets, I’m thinking more critically about the different types of API functionality I’m coming across, establishing seven new buckets: General Data - You can get at data across the platform, users, and resources...

Algolia Kindly Provides A Hacker News Search API

21 August 2018
I was working on a serverless app for Streamdata.io that takes posts to Hacker News and streams them into an Amazon S3 data lake, and I came across the Algolia powered Hacker News search API. After being somewhat frustrated with the simplicity of the official Hacker News API, I was pleased to find the search kindly provided by Algolia. There is no search API available for the core Hacker News API, and the design leaves a lot to be desired, so the simplicity of Algolia’s API solution was refreshing. There is a lot of data flowing into Hacker News on a regular day, so providing a search API is pretty critical. Additionally, Algolia’s ability to deliver such a simple, usable, yet powerful API on top of a relevant data source like Hacker News demonstrates the utility of what Algolia offers as a search solution–something I wanted to take a moment to point out here on the blog...

Microserviceing Like a Unicorn With Envoy, Istio & Kubernetes With Christian

20 August 2018
We are getting closer to the 9th edition of APIStrat happening in Nashville, TN this September 24th through 26th. The schedule for the conference is up, along with the first lineup of keynote speakers, and my drumbeat of stories about the event continues here on the blog. Next up in our session lineup is “Microservice’ing Like a Unicorn With Envoy, Istio and Kubernetes” by Christian Posta (@christianposta), Red Hat @RedHat on September 25th. Here is Christian’s abstract for the session: The exciting parts of APIs, unfortunately, happen when services actually try communicating and working together to accomplish some business function. The service-mesh approach has emerged to help make service communication boring...

The Redirect URL To Confirm Selling Your API In AWS Marketplace Provides Us With A Positive

20 August 2018
I am setting up different APIs using the AWS API Gateway and then publishing them to the AWS Marketplace, as part of my work with Streamdata.io. I’m getting a feel for what the process is all about, and how small I can distill an API product to be, as part of the AWS Marketplace process. My goal is to be able to quickly define APIs using OpenAPI, then publish them to AWS API Gateway, and leverage the gateway to help me manage the entire business of the service from signup to discovery. As I was adding one of my first couple of APIs to the AWS Marketplace, and I found the instructions regarding the redirect URL for each API to be a good template. Each individual API service I’m offering will have its own subscription confirmation URL with the AWS API marketplace, with the relevant variables present I will need to scale the technical and business of delivering my APIs: AWS Marketplace Confirmation Redirect URL: https://YOUR_DEVELOPER_PORTAL_API_ID...

We Need You API Developers Until We Have Grown To A Certain Size

20 August 2018
I’m watching several fronts along the API landscape evolve right now, with large API providers shifting, shutting down, and changing how they do business with their APIs–now that they don’t need their ecosystem of developers as much. It is easy to point the finger at Facebook, Twitter, Google, and the other giants, but it really is a wider systemic, business of APIs illness that will continue to negatively impact the API universe. While this behavior is very prominent with the leading API providers right now, it is something we’ll see various waves of it’s influence on the tone of the entire API sector further on down the road. How API providers treat their consumers vary from industry to industry, and is different depending on the types of resources being made available...

Having An API Deprecation Page Like EVRYTHNG Does

20 August 2018
The API providers I talk to regularly are rarely proactive when it comes to addressing API deprecation. Most API providers aren’t thinking about shutting down any service they deliver until they’ve actually encountered the need down the road. Many just begin their API journey, assuming their APIs will be a success, and they will have to support every version forever. However, once they encounter what it will take to support older versions, they begin to change their tune, something that often comes as an unexpected surprise to consumers. Shutting down old APIs will never be easy, but the process can be made easier with a little proactive communication. One example of this practice in action can be found over at the Internet of Things provider Evrythng, with their API deprecation page...

"It Isnt Just That You Have A PDF For Your API Docs, It Is Because It Demonstrates That You Do Not Use Other APIs"

13 August 2018
I look at a lot of APIs. I can tell a lot about a company, and the people behind an API from looking at their developer portal, documentation, and other building blocks of their presence. One of the more egregious sins I feel an API provider can make when operating their API is publishing their API documentation as a PDF. This is something that was acceptable up until about 2006, but over a decade after it shows that the organization behind an API hasn’t done their homework. The crime really isn’t the fact that an API provider is using a PDF for their documentation. I’m fine with API providers publishing a PDF version of their API, to provide a portable version of it. Where a PDF version of the documentation becomes a problem is when it is the primary version of the documentation, which demonstrates that the creators don’t get out much and haven’t used many other APIs...

Bringing Discovery Within Data API Marketplaces Out Into The Open

13 August 2018
I spend time reviewing each wave of data API marketplaces as they emerge on the landscape every couple of years. There are a number of reasons why these data marketplaces exist, ranging from supporting government agencies, NGOs, or for commercial purposes. One of the most common elements of API-driven data marketplaces that frustrates me is when they don’t do the hard work to expose the meta data around the databases, datasets, spreadsheets, and the raw data they are providing access to–making it very difficult to actually discover anything of interest. You can see a couple examples of this with mLab, World Health Organization, Data.World, and others. While these platforms provide (sometimes) impressive ability to manage data stores, but they don’t always do a good job exposing the meta data of their catalogs as part of the available APIs...

I Am Speaking In Washington D.C. At The Blue Button 2.0 Developer Conference

07 August 2018
I’m heading to Washington D.C. this Monday to speak on the API life cycle as part of the Blue Button 2.0 Developer Conference. We’ll be coming together in the Eisenhower Executive Office Building, within the west wing complex of the White House, to better understand how we can, “bring together developers to learn and share insights on how we can leverage claims data to serve the Medicare population.” The gathering will hear from CMS Administrator Seema Verma and other Administrator Leadership about Blue Button 2.0 and the MyHealthEData initiative, while also hosting a series of break sessions, which I’m part of: Blue Button 2.0 and FHIR (where it’s all heading) with Mark Scrimshire and Cat Greim MyHealthEData and Interoperability with Alex Mugge and Joy Day Overview of Medicare Claims Data with Karl Davis Medicare Beneficiary User Research with Allyssa Allen Sync for Science with Josh Mandel and Andrew Bjonnes API Design with Kin Lane Registration for the gathering is now closed, but if you are a federal govy, I’m sure you can find someone to get you in...

Twice The Dose Of Vanick Digital At APIStrat in Nashville, TN Next Month

07 August 2018
We are kicking it into overdrive now that the schedule is up for APIStrat in Nashville, TN this September 24th through 26th. From now until the event at the end of September you are going to hear me talk about all the amazing speakers we have, the companies they work for, and the interesting things they are all doing with APIs. One of the perks of being a speaker or a sponsor at APIStrat–you get coverage on API Evangelist, a become part of the buzz around the 9th edition of the API Strategy & Practice Conference (APIStrat), now operated by the OpenAPI Initiative (OAI) and the Linux Foundation. Today’s post is about my friends over at the digital solutions and API management agency Vanick Digital...

Working With My OpenAPI Definitions In An API Editor Helps Stabilize Them

07 August 2018
I’m deploying three new APIs right now, using a new experimental serverless approach I’m evolving. One is a location API, another providing API access to companies, and the third involves working with patents. I will be evolving these three simple web APIs to meet the specific needs of some applications I’m building, but then I will also be selling retail and wholesale access to each API once they’ve matured enough. With all three APIs of these APIs, I began with a simple JSON schema from the data source, which I used to generate three rough OpenAPI definitions that will acts the contract seed for my three services. Once I had three separate OpenAPI contracts for the services I was delivering, I wanted to spend some time hand designing each of the APIs before I imported into AWS API Gateway, generating Lambda functions, loading in Postman, and used to support other stops along the API lifecycle...

Making Sure My API Dependencies Include Data Provenance

06 August 2018
I am publishing a new API for locations. I am tired of needing some of the same location based resources across projects, and not having a simple, standardized API I can depend on. So I got to work finding the most accurate and complete data set I could find of cities, regions, and countries. I settled on using the complete, and easy to use countries-regions-cities project by David Graham–providing a straightforward SQL script I can use as the seed for my locations API database. After crafting an API for this database using AWS API Gateway and Lambda, and working my way down my API checklist, it occurred to me that I wanted to include David Graham’s work as one of the project dependencies...

Automating Inequality (and APIs)

06 August 2018
As we prepare for APIStrat in Nashville, TN this September 24th through 26th, I asked my partner in crime Audrey Watters (@audreywatters) to write a post on the significance of Virginia Eubanks, the author of Automating Inequality: How High-Tech Tools Profile, Police, and Punish the Poor keynoting the conference–she shared this story, of why her work is so significant, and why it is important for the API community to tune in. Repeatable tasks can and should be automated – that’s an assertion that you’ll hear all the time in computing. Sometimes the rationale is efficiency – it’s cheaper, faster, “labor-saving.” Automation will free up time; it will make our lives easier. Or so we’re told...

SAP And Being Late To The API Game

06 August 2018
I’ve been having regular meetings with the SAPI API team lately, talking through their presence in the API space, and throwing out ideas for what the future might hold. This isn’t a paid engagement, it is just something I’m interested in investing in on my own, but like many other API service providers in the space, we are exploring what partnership opportunities might there might be. Last week, I wrote about their API Business Hub, which I’ll keep exploring, but first I wanted to address perceptions in the industry that SAP is a little late to the game, when it comes to going all in on APIs. For me, the SAP API journey begins in 2010, when I left my role as VP of Technology at WebEvents Global, who runs all of SAP Events...

We Need Your Help Moving The AsyncAPI Specification Forward

31 July 2018
We need your help moving the AsyncAPI specification forward. Ok, first, what is the AsyncAPI specification? “The AsyncAPI Specification is a project used to describe and document Asynchronous APIs. The AsyncAPI Specification defines a set of files required to describe such an API. These files can then be used to create utilities, such as documentation, integration and/or testing tools.” AsyncAPI is a sister specification to OpenAPI, but instead of describing the request and response HTTP API landscape, AsyncAPI is describing the message, topic, event, and streaming API landscape across the HTTP and TCP landscape. It is how we are going to continue to ensure there is machine readable descriptions of this portion of the API landscape, for use in tooling and services...

Practical SecDevOps for APIs From @42Crunch At APIStrat In Nashville This Fall

31 July 2018
We are gearing up for the next edition of APIStrat in Nashville, TN this September 24th through 26th. With the conference less than two months away, and the schedule up, I’m building momentum with my usual drumbeat about the speakers, and companies involved. So you’ll be reading a lot of stories related to APIStrat in coming weeks, where I’m looking to build awareness and attendance of the conference, but more importantly showcasing the individuals and companies who are supporting it and helping making the 9th edition of APIStrat amazing. One of innovative startups I’m partnering with right now, and who you will find speaking and sponsoring APIStrat is 42Crunch. Full disclosure, I’m regularly talking with 42Crunch regarding their road map, and I consider them an API Evangelist partner, however, this is because I find them to be one of the more progressive, and important API startups out there right now...

The Service Level Agreement (SLA) Definition For The OpenAPI Specification

27 July 2018
I’m currently learning more about SLA4OAI, an open source standard for describing SLA in APIs, which is based on the standards proposed by the OAI, adding an optional profile for defining SLA (Service Level Agreements) for APIs. “This SLA definition in a neutral vendor flavor will allow to foster innovation in the area where APIs expose and documents its SLA, API Management tools can import and measure such key metrics and composed SLAs for composed services aggregated way in a standard way.” Providing not just a needed standard for the API sector, but more importantly one that is built on top of an existing standard. SLA4OAI, provides an interesting way to define the SLA for any API, providing a set of objects that augment and can be paired with an OpenAPI definition using an x-sla vendor extension: Context - Holds the main information of the SLA context...

Kicking The Tires On The SAP API Business Hub

26 July 2018
I told the folks over at SAP that I would take a look at their API Business Hub. It isn’t paid work, just helping provide feedback on another addition to the API discovery front, something I’m pretty committed to helping push forward in any way that I can. They’ve pulled together a pretty clean, OpenAPI driven catalog of useful APIs for the enterprise, so I wanted to make sure I kick the tires and size it up alongside the other API discovery work I am doing. The SAP API Business Hub is a pretty simple and clean catalog for searching and browsing applications, integrations, as well as APIs–I am going to focus in on the API section. Which at first glance looks to have about 70 separate APIs, but then you notice each of them are just umbrellas for each API platform, and some of them contain many different API endpoints...

Thinking Deeply About Other People Using Your API Is The Most Valuable Lesson

26 July 2018
I am deploying a patent review API for a client, using data from the Patent Examination Data System (PEDS). You can download complete JSON or XML data from the United States Patent Office (USPTO), and they even have an API. So, why would I be launching yet another API? Well, because what they have is so cryptic, complex, and lacking in any schema or API design, there is value in me pushing the API conversation forward a bit by thinking deeply about how other people will potentially be using these resources–something the USPTO clearly hasn’t done. The USPTO PEDS API (that is more acronyms than you can shake a stick at) is a great example of how much database people, and developers take for granted as they operate within their little bubbles, without much concern for how the rest of the world views their work–take a look at the screenshot of thee USPTO PEDS API...

Monolithic Serverless? WTF?

26 July 2018
While writing about the discussions I’ve been having with folks around using monorepos to manage microservices, I came across this post about whether or not people should be using a single monolithic Lambda function or multiple lambda functions with the AWS API Gateway. Again, surprising me about how lazy people are, and how difficult it is for people to think about things in a decoupled way. Which I think is the reason many people will go back to doing monolithic applications, and fail at microservices, not because it technically won’t work, it is just because it will be perceived as more work, and with a lack of imagination around how to work in a distributed way, people will give up...

Avoid Being Captain Obvious When Documenting Your API

26 July 2018
I read a lot of API documentation, and help review API portals for clients, and one of the most common rookie mistakes I see made, is people pointing out the obvious, and writing a bunch of fluffy, meaningless content that gets in the way of people actually using an API. When the obvious API industry stuff is combined with the assumed elements of what a company does, you end up with a meaningless set of obstacles that slow API integration down. Here is the most common thing I read when entering an API portal: “This is an API for querying data from the [Company X] platform, to get access to JSON from our system which allows you to get data from our system into yours using the web. You will need to write code to make calls to our APIs documented here on the page below...

Discover, Profile, Quantify, Rank, And Publish New APIs To The Streamdata.io

19 July 2018
About 60% of my work these days is building upon the last five years of my API Stack research, with a focus on building out the Streamdata.io API Gallery. We are fine tuning our approach for discovering new API-driven resources from across the landscape, while also profiling, quantifying, ranking, and publishing to the Streamdata.io API Gallery, The API Stack, and potentially other locations like the Postman Network, APIs.Guru, and other API discovery destinations I am working with. Helping us make sense of the increasingly noisy API landscape, while identifying the most valuable resources, and then profiling them to help reduce friction when it comes to potentially on-boarding and streaming data from each resource...

API Governance Models In The Public and Private Sector

19 July 2018
This is a report for the Department of Veterans Affairs microconsulting project, “Governance Models in Public and Private Sector”. Providing an overview of API governance to help the VA, “understand, with the intention to adopt, best practices from the private and public sector, specifically for prioritizing APIs to build, standards to which to build APIs, and making the APIs usable by external consumers.” Pulling together several years of research conducted by industry analyst API Evangelist, as well as phone interviews with API practitioners from large enterprise organizations who are implementing API governance on the ground across the public and private sector, conducted by Skylight Digital...

For Every Competitor You Keep Out Of Your API Docs You Are Keeping Twenty New

16 July 2018
It is interesting for me to still regularly come across so many API providers who have a public API portals, but insist on keeping most of their documentation behind a login. Stating that they are concerned with competitors getting access to the design of their API and the underlying schema. Revealing some indefensible API business models, and general paranoia around doing business on the web. Something that usually is a sign for me of a business that is working really hard to maintain a competitive grip within an industry, without actually having to do the hard work of innovating and moving the conversation forward. Confident API providers know that you can put your API documentation out in the open, complete with schema, without giving away the farm...

Concern Around Working With Many Github Repositories

16 July 2018
I’m regularly fascinated with API development teams I work with expressing their concern with working with many Github repositories. With all of the complexity I watch teams embrace when it comes to frameworks, scaffolding, continuous integration, deployment, and orchestration solutions, I’m lost on why many Github repositories suddenly become such a challenge. A Github organization is a folder, and a Github repository is a folder, that you can check out locally, on your server, or work with via an API, or Git. It is a distributed file store, that you can orchestrate with programmatically, and can be as logical or illogical as you design it to be. I work really hard to keep technical complexity to a minimum in my world, but this means limiting unnecessary vendor lock-in, and tech just because it is the latest trend...

If A Search For Swagger or OpenAPI Doesnt Yield Results I Try For A Postman

16 July 2018
While profiling any company, a couple of the Google searches I will execute right away are for “[Company Name] Swagger” and “[Company Name] OpenAPI”, hoping that a provide is progressive enough to have published an OpenAPI definition–saving me hours of work understanding what their API does. I’ve added a third search to my toolbox, if these other two searches do not yield results, searching for “[Company Name] Postman”, revealing whether or not a company has published a Postman Collection for their API–another sign of a progressive, outward thinking API provider in my book. A machine readable definition for an API tells me more about what a company, organization, institution, or government agency does, than anything else I can dig up on their website, or social media profiles...

TVMaze Uses HAL For Their API Media Type

16 July 2018
One of the layers of the API universe where I come across an increased number Hypermedia APIs is in the movie, television, and entertainment space. Where having a more flowing API experience makes a lot of sense, and the extra investment in link relations will pay off. One example of this I recently came across was over at TVMaze, who has a pretty robust hypermedia API, where they opted for using HAL as their media type. Like any good hypermedia should, TVMaze begins with its root URL: http://api.tvmaze.com, and provides a robust set of endpoints from there: Search Show Search Show single search Show Lookup People search Schedule Full Schedule Shows Show main information Show episode list Episode by number Episodes by date Show seasons Season episodes Show cast Show crew Show AKA’s Show index People Person main information Person cast credits Person crew credits Updates Show updates The TVMaze API isn’t an overly complex hypermedia API...

My API Lifecycle Checklist And Scorecard

12 July 2018
I am working on delivering a handful of new APIs, which I will be turning into products. I will be prototyping, developing, and operating them in production environments for myself, and for a handful of customers. To help guide my workflow, I’ve crafted this API lifecycle definition to help direct my efforts in an ongoing lifecycle approach. Define - Define the problem and solution in a human and machine readable way. Repository - Establish a Github repository. README - Craft a README for the repository. Title - Provide title for the service. Description - Provide concise description for the service. Goals - Establish goals for the service. Schema - Organize loose, and JSON schema for the service...

Monetizing Your Device Location Data With LotaData

11 July 2018
There are a lot of people making money off of the acquisition, organization, and providing access to data in our digital world. While I quietly tune into what the data monetization trends are, I am also actively looking for interesting approaches to generating revenue from data, but specifically with an eye on revenue sharing opportunities for the owners or stewards of that data. You know as opposed to just the exploitation of people’s data, and generating of revenue without them knowing, or including them in the conversation. To help counteract this negative aspect of the data economy, I’m always looking to highlight (potentially) more positive outcomes when it comes to making money from data...

I Am Sorry, But Your Company Is Too Big For Me To Talk To

11 July 2018
It is funny work with companies, organizations, institutions, and government agencies of all shapes and sizes, and learn all the weird practices they have, and the strange belief systems they’ve established. One day I will be talking to a 3 person startup, the next day I’ll be talking with a large bank, and after that I’ll be working with a group at a massive government agency. I have to be mindful of my time, make sure I’m meeting my mission, having an impact, as well as paying my bills, but for the most part I don’t have any entrenched rules about who I will talk to, or who I will share my knowledge with. One thing I chuckle at regularly is when I come across large organizations who will gladly talk with me, and tap my knowledge, but won’t work with some of the startups I work with, or the conferences I produce, because they are “too small”...

Ping Identity Acquires ElasticBeam To Establish New API Security Solution

11 July 2018
You don’t usually find me writing about API acquisitions unless I have a relationship with the company, or there are other interesting aspects of the acquisition that makes it noteworthy. This acquisition of Elastic Beam by Ping Identity has a little of both for me, as I’ve been working with the Elastic Beam team for over a year now, and I’ve been interested in what Ping Identity is up to because of some research I am doing around open banking in the UK, and the concept of an industry level API identity and access management, as well as API management layer. All of which makes for an interesting enough mix for me to want to quantify here on the blog and load up in my brain, and share with my readers...

Using OpenAPI And JSON PATCH To Articulate Changes For Your API Road Map

10 July 2018
I’m doing a lot of thinking regarding how JSON PATCH can be applied because of my work with Streamdata.io. When you proxy an existing JSON API with Streamdata.io, after the initial response, every update sent over the wire is articulated as a JSON PATCH update, showing only what has changed. It is an efficient, and useful way to show what has changed with any JSON API response, while being very efficient about what you transmit with each API response, reducing polling, and taking advantage of HTTP caching. As I’m writing an OpenAPI diff solution, helping understand the differences between OpenAPI definitions I’m importing, and allowing me to understand what has changed over time, I can’t help but think that JSON PATCH would be a great way to articulate change of the surface area of an API over time–that is, if everyone loyally used OpenAPI as their API contract...

Long Running API Requests And Differential API Responses

10 July 2018
I am shifting my long running API operations from a PHP / EC2 based implementation to a more efficient Node.js / Lambda based solution, and I promised James Higginbotham (@launchany) that I’d share a breakdown of my process with him a month or so back. I’m running 100+, to bursts of 1000+ long running API requests for a variety of purposes, and it helps me to tell the narrative behind my code, introducing some coherence into the why and how of what I’m doing, while also sharing with others along the way. I had covered my earlier process a little bit in a story a few months ago, but as I was migrating the process, I wanted to further flesh out, and make sure I wasn’t mad. The base building block of each long running API request I am making is HTTP...

People Do Not Use Tags In Their OpenAPI Definitions

10 July 2018
I import and work with a number of OpenAPI definitions that I come across in the wild. When I come across a version 1.2, 2.0, 3.0 OpenAPI, I import them into my API monitoring system for publishing as part of my research. After the initial import of any OpenAPI definition, the first thing I look for is the consistent in the naming of paths, the availability of summary, descriptions, as well as tags. The naming conventions used is paths is all over the place, some are cleaner than others. Most have a summary, with fewer having descriptions, but I’d say about 80% of them do not have any tags available for each API path. Tags for each API path are essential to labeling the value a resource delivers...

My Moving Towards a Modern API Lifecycle From POST/CON 2018

10 July 2018
I gave a talk early in in June at POST/CON 2018 in San Francisco. The conference was a great mix of discussions reflecting the Postman community. You can find all the talks on Google, including mine about moving towards a modern AP lifecycle. You can find all the stop along what I consider to be a modern API lifecycle on the home page of API Evangelist, with links to any of my research, services, tooling, and other storytelling I’ve done in each area. Thanks again to Postman for having me out!

Using Plain Language In Your API Paths

09 July 2018
It is tough to help developers think outside of the world they operate within. Most software is still developed and managed within silos, knowing it’s inner workings will never be seen by anyone outside of the team. This mode of operation is a rich environment for poor code quality, and teams with port communication. This is one of the reasons I’ve embraced web APIs, after running software development teams since the 1990s, I’ve been put in charge of some pretty dysfunctional teams, and some pretty unwieldy legacy codebases, so once I started working out in the open using web APIs, I did’t want to go back. Web APIs aren’t the cure for all of our technology problems, but it does begin to let some sunlight in on some messed up ways of doing things...

Concerns Around Managing Many Microservice Repositories And Going With A Mono

09 July 2018
About half of the teams I work with on microservices strategy are beginning to freak out about the number repositories they have, and someone is regularly bringing up the subject of having a mono repo. Which is usually a sign for me that a group is not ready for doing the hard work involved with microservices, but also shows a lack of ability to think, act, and respond to things in a distributed way. It can be a challenge to manage many different repositories, but with a decoupled awareness of the sprawl that can exist, and some adjustments and aggregation to your strategy it can be doable, even for a small team. The most import part of sticking to multiple repositories is for the sake of the code...

Operating Your API In The Cloud Kill Zone

09 July 2018
When you operate your application within the API ecosystem of a large platform, depending on the platform, you might have to worry about the platform operator copying, and emulating what you do. Twitter has long been accused of sharecropping within their ecosystem, and other larger platforms have come out with similar features to what you can find within their API communities. Not all providers take the ideas, it is also very common for API platforms to acquire talent, features, and applications from their ecosystems–something that Twitter has done regularly. Either way, API ecosystems are the R&D, and innovation labs for many platforms, where the latest features get proven. As the technology playing field has consolidated across three major cloud providers, AWS, Azure, and Google, this R&D and innovation zone, has become more of a cloud kill zone for API providers...

I Love The API Enthusiasm Predix, But Please Publish An API Style Guide For

09 July 2018
I was profiling the volume of API from the Internet of Things platform Predix this last week. Luckily they have OpenAPI definitions for each of the APIs, something that makes my life a lot easier. As, they have a wealth of APIs available, doing an amazing amount of work when it comes to connecting devices to the Internet–I love their enthusiasm for putting out APIs. My only critical feedback for them after working my way through their API definitions, is they should invest some time to develop an API design guide, and distribute across their teams. The wild variances in definition and design of their APIs made me stumble a number of times while learning about what they do. While looking through the definitions for the Predix APIs, I found many inconsistent patterns between them, and you could tell that they had different teams (or individuals) working across the suite of APIs...

Looking For Sponsors For APIStrat 2018 In Nashville, TN This September

29 June 2018
We are building up to the 9th edition of API Strategy & Practice (APIStrat) happening in Nashville, Tennessee this September 24th through 26th. As part of the build up we are looking for sponsors to help make the event happen, bringing the API community together once again to share stories from the trenches, and discuss healthy practices that are allowing companies, organizations, institutions, and government agencies make an impact when it comes to their API operations. The 2017 edition of APIStrat in Portland, OR was a huge success, and help complete the transition of APIStrat to be part of the OpenAPI Initiative (OAI). After seven editions, and four years of operation exclusively by 3Scale and API Evangelist, the event has matured and will continue growing under the guidance of the OAI, and the community that has evolved around the OpenAPI specification...

Mayors, Governors, And Lawmakers: Tech Companies Are Getting Rich Mining Your Constituents Data

29 June 2018
It has been a fascinating and eye opening experience sitting at the intersection of tech startups and the web, mobile, and device applications they’ve built over the last decade. In 2010 I was captivated by the power of APIs to deliver resources to developers, and end-users. In 2018, I’m captivated by the power of APIs to mine end-users like they are just a resource, with the assistance of the developer class. A dominant white male class of people who are more than willing to look the other way when exploitation occurs, and make for the perfect “tools” to be exploited by the wealthy investor class. While I do not have much hope for diversity efforts in tech, or the bro culture waking up, I do have hope for city and state/provincial lawmakers to wake up to the exploitation that is going on...

GraphQL And REST Differences Explained With Burgers

29 June 2018
GraphQL folks keep on with the GraphQL vs REST narratives, rather than a REST and / or GraphQL narrative lately with a recent burger meme/narrative. Continuing to demonstrate their narrow view of the landscape, and revealing the short lived power of an adversarial approach to community building. I get why people do this, because they feel they are being clever, and that the click response from the echo chamber re-enforces it, but ultimately it is something that won’t move the conversation forward, but it does get them kudos within their community–which is what many of them live for. I’ll start with the usual disclaimer. I actually like GraphQL, and prescribe it as part of my API toolbox...

Why Is API Versioning In The Path Still The Dominant Pattern?

26 June 2018
API versioning is almost always one of the top attended discussions at conferences I help organize, and one of the first questions I get in the QA sessions at workshops I conduct. People want to understand the “right way” to version, when it my experience there is rarely ever a “right way” to version your APIs. There are commonly held practices regarding sensible ways to version your APIs, as well as dominant patterns for how you version APIs, but there isn’t any 100% solid answer to the question, despite what many folks might say. In my experience, the most commonly held approach to properly versioning your APIs (if you are going to), is to put the major and minor version in your header and / or combine it with content-type negotiation via your header...

Not Liking OpenAPI (fka Swagger) When You Have No Idea What It Does

26 June 2018
People love to hate in the API space. Ok, I guess its not exclusive to the API space, but it is a significant aspect of the community. I receive a regular amount of people hating on my work, for no reason at all. I also see people doing it to others in the API space on a regular basis. It always makes me sad to see, and have always worked to try to be as nice as I can to counteract the male negativity and competitive tone that often exists. While I feel bad for the people on the receiving end of all of this, I often times feel bad for the people on the giving end of things, as they are often not the most informed and up to speed folks, who seem to enjoy opening their mouth before they understand what is happening...

A Public Self-Service API Platform as a Competitive Advantage

26 June 2018
When it comes to providing data, content, and even ML and AI models via APIs, having a public platform will become a competitive advantage. I know that many companies see it as giving away something, especially when your resources and business model are not defensible, but in reality having a publicly available, 24/7 operational, self-service solution will give you an edge over your more proprietary approaches to making resources available on the web. Sure, your competition will be able to often get in there without friction, but so will your customers–how many customers vs. competitors do you have? I know many companies believe in the power of a sales team to be able to squeeze every last penny out of would be customers, but a sales only approach leaves a significant amount of self-service revenue on the table...

Staying Informed of API Changes Using Streamdata.io

22 June 2018
My friend James Higginbotham (@launchany) was sharing his frustration with being able to stay in tune with changes to a variety of APIs. Like me, James works to stay in tune with a variety of signals available via platforms like Twitter, Github, and other commonly used services. These platforms don’t always properly signal when things are updated, changed, or advanced, making it difficult to understand the granular changes that occur like likes, votes, edits, and other common events that occur via highly active platforms. This challenge is why the evolution towards a more event-driven approach to operating an API platform is not just more efficient, it gives users what they need. Using event-driven architectural approaches like Webhooks, and real times streams...

Do Not Try To Service All The Stops Along The API Lifecycle As An API Service

21 June 2018
One thing I see a lot from API service providers who are selling their services to the API sector, is that once they find success servicing one stop along the API lifecycle, they often want to service other additional stops. I don’t have a problem with API service providers delivering across multiple stops along the API lifecycle, however I do caution of trying to expand across too many stops, and potentially doing any of them poorly, rather than partnering with other more specialized API service providers to help you focus on what you do best. I’m a big advocate for encouraging API providers to service one to five stops along the API lifecycle well, and then partner for helping deliver the rest of the stops...

Working To Keep Programming Language Dogma At Edges Of The API Conversation

21 June 2018
I’m fascinated by the dominating power of programming languages. There are many ideological forces at play in the technology sector, but the dogma that exists within each programming language community continues to amaze me. The potential absence of programming language dogma within the world of APIs is one of the reasons I feel it has been successful, but alas, other forms of dogma tends to creep in around specific API approaches and philosophies, making API evangelism and adoption always a challenge. The absence of programming languages in the API design, management, and testing discussion is why they have been so successful. People in these disciplines have ben focused on the language agnostic aspects of just doing business with APIs...

Adding A Lead To SalesForce Using The REST API

19 June 2018
I spend a lot of time talking about the SalesForce API, using it as a reference for where the API evolution began 18 years ago, but it has been a long time since I’ve actually worked with the SalesForce API. Getting up and running with any API, especially iconic APIs that we all should be familiar with, is always an enlightening experience for me. Going from zero to understanding what is going on and actually achieving the API call(s) you want, is really what this game is all about. As part of some work I’m doing with Streamdata.io I needed to be able to add new leads into SalesForce, and I thought it would be a good time for me to get back into the saddle with the SalesForce REST API–so I volunteered to tackle the integration...

VA API Landscape Analysis and Roadmapping Project Report

18 June 2018
This report summarizes Skylight’s evaluation of the VA’s public datasets, which exist within the va.gov web domain, as well as an analysis of what types of data representatives of the Veteran community expressed would be most useful and valuable to Veterans and their supporters if made more digitally accessible and available by the VA. This report also outlines potential resources that can be turned into application programming interfaces (APIs) as part of the VA’s Lighthouse platform initiative, and actions the VA should consider to move forward successfully. Landscape analysis The purpose APIs are the next evolution in the web, and shouldn’t be thought of as the latest tech trend or vendor solution...

The Importance Of OpenAPI Tooling

18 June 2018
In my world, OpenAPI is always a primary actor, and the tooling and services that put it to work are always secondary. However, I’d say that 80% of the people I talk with are the opposite, putting OpenAPI tooling in a primary role, and the OpenAPI specification in a secondary role. This is the primary reason that many still see Swagger tooling as the value, and haven’t made the switch to the concept of OpenAPI, or understand the separation between the specification and the tooling. Another way in which you can see the importance of OpenAPI tooling is the slow migration of OpenAPI 2.0 to 3.0 users. Many folks I’ve talked to about OpenAPI 3.0 tell me that they haven’t made the jump because of the lack of tooling available for the specification...

People Still Think APIs Are About Giving Away Your Data For Free

08 June 2018
After eight years of educating people about sensible API security and management, I’m always amazed at how many people I come across who still think public web APIs are about giving away access to your data, content, and algorithms for free. I regularly come across very smart people who say they’d be doing APIs, but they depend on revenue from selling their data and content, and wouldn’t benefit from just putting it online for everyone to download for free. I wonder when we stopped thinking the web was not about giving everything away for free? It is something I’m going to have to investigate a little more. For me, it shows how much education we still have ahead of us when it comes to informing people about what APIs are, and how to properly manage them...

The Rockstar Committees We Have Assembled To Make APIStrat Nashville Rock!!

04 June 2018
It is APIStrat time again! This time it is in Nashville, Tennessee! We are in the early stages of the event, but we are getting close to the deadline of the call for papers. We’ve assembled another rockstar ensemble for this round to help us steer the event, and review talk submissions once the CFP process has closed. I just wanted to take a moment and recognize the folks who are helping out and make sure they get the recognition they deserve. First up are the six members of the APIStrat steering committee, playing different leadership roles in the conference, making sure everything gets done by September: Darrel Miller (@darrel_miller)– Workshop Chair - Microsoft Erin McKean (@emckean) – Program Chair - IBM Kin Lane (@kinlane) – Marketing Chair - API Evangelist Lorinda Brandon (@lindybrandon) – Community Chair - Capital One DevExchange Steven Willmott (@njyx) – Chair - Red Hat...

Catch Me At The DC API User Group in Washington DC This Tuesday Evening

04 June 2018
After I speak at DevNation Federal in Washington DC this Tuesday, I am going to give a similar talk at the DC API API User Group that evening. I love going to the Meetups in DC, partly because my good friend Gray Brooks runs the event, but also because I’ve been working to jumpstart API conversations in Washington DC since 2012 when I held the first DC edition of API Craft. I was on a mission to jumpstart API Craft gatherings around the country that year, and it makes me happy to see the API Meetup culture continuing to thrive in DC, where other places it has died out. At the DC API Meetup I’ll be giving a variation of my talk that I’m giving earlier that day at DevNation Federal. Talking about the technology, business, and politics of doing APIs, with an emphasis on a consistent and repeatable API lifecycle...

I Will Be Discussing The Government API Lifecycle At DevNation Federal In DC

04 June 2018
I’m kicking off a busy week of travel and talks this week in DC with a discussion about delivering microservices at federal agencies at DevNation Federal on Tuesday, June 5th, 2018. I was invited by Red Hat to come speak about the work I’m doing as API Evangelist across federal agencies. You can find me in the afternoon lineup, sharing my stories title “The Tech, Business, and Politics of APIs In Federal Government”. Focusing on information gathered as part of my research, workshops, and consulting across the public and private sector. My talk reflects my work to motivate federal agencies to do APIs over the last five years, and help pollinate the ideas and practices I gather from across the private sector, and understand which ones will work in the public sphere...

Making Connections At The API Management Layer

04 June 2018
I’ve been evaluating API management providers, and this important stop along the API lifecycle in which they serve for eight years now. It is a space that I’m very familiar with, and have enjoyed watching it mature, evolve, and become something that is more standardized, and lately more commoditized. I’ve enjoyed watching the old guard (3Scale, Apigee, and Mashery) be acquired, and API management be baked into the cloud with AWS, Azure, and Google. I’ve also had fun learning about Kong, Tyk, and the next generation API management providers as they grow and evolve, as well as some of the older players like Axway as they work to retool so that they can compete and even lead the charge in the current environment...

How Should We Be Organizing All Of Our Microservices?

31 May 2018
A question I get regularly in my API workshops is, “how should we be organizing all of our microservices?” To which I always recommend they tune into what the API Academy team is up to, and then I dance around give a long winded answer about how hard it is for me to answer that. I think in response, I’m going to start asking for a complete org chart for their operations, list of all their database schema, and a list of all their clients and the industries they are operating in. It will still be a journey for them, or me to answer that question, but maybe this response will help them understand the scope of what they are asking. I wish I could provide simple answers for folks when it came to how they should be naming, grouping, and organizing their microservices...

When The Right API Solution Is Not Always The Sensible One

31 May 2018
I conducted an API workshop at Genscape in Boston yesterday. I thoroughly enjoyed the conversation with the technical folks there, and found their pragmatic, yet educated views on APIs refreshing. I spent the day going through the usual stops along the API lifecycle, but found some of our breakout conversations during the API design section to be what has stuck with me on my train ride back to New York. Specifically the discussions around versioning, content negotiation and the overall design of paths, parameters, and potentially providing query language layers on top of APIs. After going through much of my textbook API design patterns for paths, and parameters, then working my through content negotiation and headers, we kept finding ourselves talking about what their clients were capable of...

APIStrat Nashville Call For Papers Closes At The End Of Next Week

30 May 2018
I know, time flies and we are all very busy, but have you submitted your talk for APIStrat Nashville? The call for papers closes next Friday, June 8, 2018 at 11:59 PM PST! This is the second edition of the conference being run by the OpenAPI community, and is something you aren’t going to want to miss. We are bringing together the usual API community suspects, but also working to build upon the work that is going on in the fast growing OpenAPI community. The conference continues to be its usual voice of the API community, and won’t be all about the OpenAPI specification, but it it will definitely be where you want to be showcasing any groundbreaking work you are doing around the specification...

A Microprocurement Package For API Monitoring And Testing

29 May 2018
I’m kicking off a micro-procurement project with the Department of Veterans Affairs (VA) this week. I’m going to to be conducting one of my API low hanging fruit campaigns for them, where I help them identify the best possible data sets available across their public websites for turning into APIs. The project is one of many small projects the federal agency is putting out there to begin working on their agency wide API platform they are calling Lighthouse. Laying the groundwork for better serving veterans through a robust stack of microservices that each do one thing really well, but can be used in concert to deliver the applications the agency needs to meet their mission. While not specifically a project to develop a microservice...

API Coordination And Communication Across Federal Government Agencies

29 May 2018
Most of this API stuff isn’t technical. For APIs to work at scale within a single company, a wider industry, or across government agencies, you need people who are committed to evangelism, coaching, and communication around everything that is occurring across API ecosystems. We often times get caught up in our work, and operating within our silos and forget to email, call, and just walk next door sometimes to share stories of what is going on. If you are a regular reader of my work you know how I feel about storytelling, and just how important it is to all of this working or not. Which is why I like to make sure that I showcase the storyelling of other evangelists who are working their magic, and spreading API knowledge within their domains...

API Evangelist Is Partnering With Bridge Software To Tell More API Integration

16 May 2018
I have been intrigued by the people who reached out after I published a story about my partner program. One of the companies that reached out was the API integration agency Bridge Software, who reflects the next generation of software development groups who are emerging to focus exclusively on API integration. I’ve had several calls with the Bridge Software team this week, discussing the possible ways in which we can work together. I’m regularly in need of software development resources that I can refer projects to, and I’m also interested in hearing more interesting stories about how businesses are integrating with APIs. Of course, Bridge Software is looking for more customers, which is something I can definitely help with...

Every Moment Is Potentially An API Story

16 May 2018
I was on a call for a federal government API platform project with my partner in crime Chris Cairns (@cscairns) of Skylight.Digital. We were back channeling in our Slack channel during the call, when he said, “I always imagine you participating in these things, finding topics you haven’t covered or emphasized from a certain angle, and then writing a blog post in real time.” He was right, I had taken notes on a couple of new angles regarding the testing, monitoring, and understanding performance of APIs involved with federal government projects. The single conference call resulted in about seven potential stories in my notebook. I’m guessing that only four of them will actually end up being published...

Cautiously Aware Of How APIs Can Be Used To Feed Government Privatization

15 May 2018
I’m working to define APIs at the Department of Veterans Affairs (VA) on several fronts right now. I’ve provided not just one, but two detailed reponses to their Lighthouse API platform RFIs. Additionally, I’m providing guidance to different teams who are working on a variety of projects occurring simultaneously to serve veterans who receive support from the agency. As I do this work, I am hyper aware of the privatization machinations of the current administration, and the potential for APIs to serve these desires. APIs aren’t good, bad, nor are they neutral. APIs reflect the desires of their owners, and the good or bad they can inflict is determined by their consumers. Because APIs are so abstract, and are often buried within web and mobile applications, it can be difficult to see what they are truly doing on a day to day basis...

General Services Administration (GSA) Needs Help Testing Their FedBizOpps API

15 May 2018
The General Services Administration (GSA) has an open call for help to test the new FedBizOpps API. Setting a pretty compelling precedent for releasing APIs in the federal government, slowly bringing federal agencies out of their shell, and moving the API conversation forward in government. Hopefully it will be something that other federal agencies, and other levels of government will consider as they move forward on their API journeys. It is good to see federal agencies reaching out to ask for help in making sure APIs are well designed, deliver value, and operate as expected. In my experience, most government agencies are gun-shy when it comes to seeking outside help, and accepting criticism when it comes to their work...

Opportunity For OpenAPI-Driven Open Source Testing, Performance, Security, And

15 May 2018
I’ve been on five separate government reflated projects lately where finding modular OpenAPI-driven open source tooling has been a top priority. All of these projects are microservice-focused and OpenAPI-driven, and are investing significant amounts of time looking open source tools that will help with design governance, monitoring, testing, and security, and interact with the Jenkins pipeline. Helping government agencies find success as their API journey picks up speed, and the number of APIs grows exponentially. Selling to the federal government can be a long journey in itself. They can’t always use the SaaS solutions many of us fire up to get the job done in our startup or enterprise lives...

API Lifecycle Seminars In New York City

15 May 2018
I’ve had a huge demand for putting on API seminars for a variety of enterprise groups lately. Helping bring my API 101, history, lifecycle, and governance knowledge to the table. I’ve conducted seminars in the UK and France in April, and have more in Virginia, Massachusetts, and California in May. I’ve been working with a variety of companies, institutions, and government agencies to plan even more internal seminars, which is something that is proving to be challenging for some groups who are just getting started on their API journey. While groups are keen on me coming visit to share my API knowledge, some of them are having trouble getting me through legal, get me into their payment systems, and making everyone’s schedules work...

Sports Data API Simulations From SportRadar

14 May 2018
I’m a big fan of API sandboxes, labs, and other virtualization environments. API sandboxes should be default in heavily regulated industries like banking. I also support the virtualization of schema and data used across API operations, like I am doing at the Department of Veterans Affairs (VA), with synthetic healthcare data. I’m very interested in anything that moves forward the API virtualization conversation, so I found the live sporting API simulations over at SportRadar very interesting. SportRadar’s “live simulations give you the opportunity to test your code against a simulation of live data before the preseason starts or any time! Our simulation system replays select completed games allowing you to view our API feeds as if they were happening live...

Using Jekyll To Look At Microservice API Definitions In Aggregate

14 May 2018
I’ve been evaluating microservices at scale, using their OpenAPI definitions to provide API design guidance to each team using Github. I just finished a round of work where I took 20 microservices, and evaluated each OpenAPI definition individually, and made design suggestions via an updated OpenAPI definition that I submitted as a Github issue. I was going to submit as a pull request, but I really want the API design guidance to be a suggestions, as well as a learning experience, so I didn’t want them to feel like they had to merge all my suggestions. After going through all 20 OpenAPI definitions, I took all of them and dumped them into a single local repository where I was running Jekyll via localhost...

Looking At 20 Microservices In Concert

14 May 2018
I checked out the Github repositories for twenty microservices of one of my clients recently, looking understand what is being accomplished across all these services as they work independently to accomplish a single collective objective. I’m being contracted with to help come in blindly and provide feedback on the design of the APIs being exposed across services, and help provide guidance on their API lifecycle, as well as eventually API governance when things have matured to that level. Right now we are addressing pretty fundamental definition and design issues, but eventually we’ll hopefully graduate to the next level. A complete and up to date README for each microservice is essential to understanding what is going on with a service, and a robust OpenAPI definition is critical to breaking down the details of what each API delivers...

Measuring Value Exchange Around Government Data Using API Management

14 May 2018
I’ve written about how the startup community has driven the value exchange that occurs at the API management layer down a two lane road with API monetizatin and plans. To generate the value that investors have been looking for, we have ended up with a free, pro, enterprise approach to measuring value exchanged with API integration, when in reality there is so much more going on here. Something that really becomes evident when you begin evaluating the API conversations going on across government at all levels. In conversation after conversation I have with government API folk I hear that they don’t need API management reporting, analysis, and billing features. There is a perception that government isn’t selling access to APIs, so API management measurement isn’t really needed...

API Discovery is for Internal or External Services

10 May 2018
The topic of API discovery has been picking up momentum in 2018. It is something I’ve worked on for years, but with the number of microservices emerging out there, it is something I’m seeing become a concern amongst providers. It is also something I’m seeing more potential vendor chatter, looking to provide more services and tooling to help alleviate API discovery pain. Even with all this movement, there is still a lot of education and discussion to occur on the subject to help bring people up to speed on what is API discovery. The most common view of what is API discovery, is when you need to find an API for developing an application. You have a need for a resource in your application, and you need to look across your internal and partner resources to find what you are looking for...

API Gateway As A Node And Moving Beyond Backend and Frontend

09 May 2018
The more I study where the API management, gateway, and proxy layer is headed, the less I’m seeing a front-end or a backend, I’m seeing just a node. A node that can connect to existing databases, or what is traditionally considered a backend system, but also can just as easily proxy and be a gateway to any existing API. A lot has been talked about when it comes to API gateways deploying APIs from an existing database. There has also been considerable discussion around proxying existing internal APIs or web services, so that we can deploy newer APIs. However, I don’t think there has been near as much discussion around proxying other 3rd party public APIs–which flips the backend and frontend discuss on its head for me...

1000 LB Gorilla Monolith and Microservices

09 May 2018

API Design, Either the Provider Does the Work or the Consumer Will Have To

08 May 2018
I’m always fascinated by the API design debate, and how many entrenched positions there are when it comes to the right way of doing it. Personally, I don’t see any right way of doing it, I just see many different ways to put the responsibility on the provider or the consumer shoulders, or sharing the load between them. I spend a lot of time profiling APIs, crafting OpenAPI definitions that try to capture 100% of the surface area of an API. Something that is pretty difficult to do when you aren’t the provider, and you are just working from existing static documentation. It is just hard to find every parameter and potential value, exhaustively detailing what is possible when you use an API...

Making the OpenAPI Contract Friendlier For Developers and Business

08 May 2018
I was in a conference session about an API design tool today, and someone asked if you could get at the OpenAPI definition behind the solution. They said yes, but quickly also said that the definition is boring and that you don’t want to be in there, you want to be in the interface. I get that service providers want you to focus on their interface, but we shouldn’t be burying, or abstracting away the API contract for APIs, we should always be educating people about it, an bringing it front and center in any service, tooling, or conversation. Technology folks burying or devaluing the OpenAPI definition with business users is common, but I also see technology folks doing it to each other...

Constraints Introduced By Supporting Standardized API Definitions and Schema

08 May 2018
I’ve had a few API groups contact me lately regarding the challenges they are facing when it comes to supporting organizational, or industry-wide API definitions and schema. They were eager to support common definitions and schema that have been standardized, but were getting frustrated by not being able to do everything they wanted, and having to live within the constraints introduced by the standardized definitions. Which is something that doesn’t get much discussion by those of use who are advocating for standardization of APIs and schema. Web APIs Come With Their Own Constraints We all want more developers to use our APIs. However, with more usage, comes more responsibility. Also, to get more usage our APIs need to speak to a wider audience, something that common API definitions and schema will help with...

Turning The Stack Exchange Questions API Into 25 Separate Tech Topic Streaming

07 May 2018
I’m turning different APIs into topical streams using Streamdata.io. I have been profiling hundreds of different APIs as part of my work to build out the Streamdata.io API Gallery, and as I’m creating OpenAPI definitions for each API, I’m realizing the potential for event and topical driven streams across many existing web APIs. One thing I am doing after profiling each API is that I benchmark them to see how often the data changes, applying what we are calling StreamRank to each API path. Then I try to make sure all the parameters, and even enum values for each parameter are represented for each API definition, helping me see the ENTIRE surface area of an API. Which is something that really illuminates the possibilities surrounding each API...

Doing Away With Social Logins Due To A Lack Of Trust

07 May 2018
I received an email from my CRON job API (EasyCRON) provider this morning about discontinuing the usage of social logins to their service with Gmail, Facebook, etc. Something that I think is a sign of things to come in response to the recent (and continued) bad behavior by many of the leading technology platforms. EasyCRON gave the following response for removing social logins from their service: In order to: 1) prevent any confusion that could be caused by using third party platform’s authentication API, 2) decouple from those data greedy platforms, 3) and keep our system simple, we decide to stop using third party platform’s authentication API on EasyCron. As much as I prefer one click login using my Github or Google (rarely use Facebook), I can’t argue with their logic...

GraphQL, Just Get Out Of My Way And Give Me What I Want

07 May 2018
One of the arguments I hear for why API providers should be employing GraphQL is that they should just get out of developers way, and let them build their own queries so that they can just get exactly the data that they want. As an application developer we know what we want from your API, do not have us make many different calls, to multiple endpoints–just give us one API and let us ask for exactly what we need. It is an eloquent, logical argument when you operate and live within a “known bubble”, and you know exactly what you want. Now, ask yourself, will every API consumer know what they want? Maybe in some scenarios, every API consumer will know what they want, but in most situations, developers will not have a clue what they want, need, or what an API does...

API Management In Real-Time Instead Of After The Media Shitstorm

07 May 2018
I have been studying API management for eight years now. I’ve spent a lot of time understanding the approach of leading API providers, and the services and tools put out there by API service providers from 3Scale to Tyk, and how the cloud service providers like AWS are baking API management into their clouds. API management isn’t the most exciting aspect of doing APIs, but I feel it is one of the most important elements of doing APIs, delivering on the business and politics of doing APIs, which can often make or break a platform and the applications that depend on it. Employing a common API management solution, and having a solid plan in place, takes time and investment. To do it properly takes lots of regular refinement, investment, and work...

Synthetic Healthcare Records For Your API Using Synthea

01 May 2018
I have been working on several fronts to help with API efforts at the Department of Veterans Affairs (VA) this year, and one of them is helping quantify the deployment of a lab API environment for the platform. The VA doesn’t want it called it a sandbox, so they are calling it a lab, but the idea is to provide an environment where developers can work with APIs, see data just like they would in a live environment, but not actually have access to live patient data before they can prove their applications are reviewed and meet requirements. One of the projects being used to help deliver data within this environment is called Synthea. Providing the virtualized data will be made available through VA labs API–here is the description of what they do from their website: Synthea is an open-source, synthetic patient generator that models the medical history of synthetic patients...

Facebook And Twitter Only Now Beginning To Police Their API Applications

30 April 2018
I’ve been reading about all the work Facebook and Twitter have been doing over the last couple of weeks to begin asserting more control over their API applications. I’m not talking about the deprecation of APIs, that is a separate post. I’m focusing on them reviewing applications that have access to their API, and shutting off access to the ones who are’t adding value to the platform and violating the terms of service. Doing the hard work to maintain a level of quality on the platform, which is something they should have been doing all along. I don’t want to diminish the importance of the work they are doing, but it really is something that should have been done along the way–not just when something goes wrong...

A README For Your Microservice Github Repository

30 April 2018
I have several projects right now that are needed a baseline for what is expected of microservices developers when it comes to the README for their Github repository. Each microservice should be a self-contained entity, with everything needed to operate the service within a single Github repository. Making the README the front door for the service, and something that anyone engaging with a service will depend on to help them understand what the service does, and where to get at anything needed to operate the service. Here is a general outline of the elements that should be present in a README for each microservice, providing as much of an overview as possible for each service: Title - A concise title for the service that fits the pattern identified and in use across all services...

Venture Capital Obfuscating The Opportunities For Value Exchange At The API

27 April 2018
p></p>When I talk to government agencies, non-profit organizations, or organizations doing internal APIs I regularly receive pushback about the information I share regarding API management, service composition, rate limiting, access tiers, and the other essential ingredients of the business of APIs. People tell me they aren’t selling access to their APIs, they don’t need to be measuring APIs like publicly available commercial APIs do. They don’t need a free, pro, and other tiers of access, and they won’t be invoicing their consumers like the majority of APIs I showcase from the API universe. This phenomenon is just one of the many negative side effects of venture capital, and Silicon Valley startups driving the conversation around APIs...

Existing Processes And Culture Grinding Down New API Efforts

27 April 2018
I’m always amazed what large organizations can achieve. They definitely have more resources, more momentum, and do way more than any single individual can achieve. However, as an individual actor I’m always also amazed at how large organization culture seems to always work to defend itself from change, and actively work to grind down API efforts I’m involved in. Even before I walk in the front door there are processes in place that work to ensure any effective API strategy gets ground down so that it won’t be as effective. NDAs, intellectual property, background checks, schedules, logistics, leadership buy-in, physical security, legacy incidents, software, processes all seem to begin doing their work...

Balancing Virtual API Evangelism With In-Person API Evangelism

27 April 2018
I haven’t published any stories this week on API Evangelist. I’ve been on the road in Lyon and Paris, France. Giving talks, and conducting workshops about my API lifecycle and governance work. Often times when I go on the road I try to pre-populate the blog with stories, but I’ve been so busy lately with travel and projects that I just didn’t have the time. Resulting in the blog not resembling its usual stream of API rants and stories. While this bothers me, I understand the balance between virtual API evangelism and the need to be present in-person from time to time. While I feel like I can reach more people virtually, I feel like at least 30% of the time I should be present in-person...

Delivering Large API Responses As Efficiently As Possible

20 April 2018
I’m participating in a meeting today where one of the agenda items will be discussing the different ways in which the team can deal with increasingly large API responses. I don’t feel there is a perfect response to this question, and the answer should depend on a variety of considerations, but I wanted to think through some of the possibilities, and make sure the answers were on the tip of my tongue. It helps to exercise these things regularly in my storytelling so when I need to recall them, they are just beneath the surface, ready to bring forward. Reduce Size Pagination I’d say the most common approach to send over large amounts of data is to break things down into smaller chunks, based upon rows being sent over, and paginate the responses...

Machine Readable API Regions For Use At Discovery And Runtime

19 April 2018
I wrote about Werner Vogel of Amazon’s post considering the impact of cloud regions a couple weeks back. I feel that his post captured an aspect of doing business in the cloud that isn’t discussed enough, and one that will continue to drive not just the business of APIs, but also increasingly the politics of APIs. Amidst increasing digital nationalism, and growing regulation of not just the pipes, but also platforms, understanding where your APIs are operating, and what networks you are using will become very important to doing business at a global scale. It is an area I’m adding to my list of machine readable API definitions I’d like to add to the APIs.json stack. The goal with APIs...

REST and gRPC Side by Side In New Google Endpoints Documentation

18 April 2018
Google has been really moving forward with their development, and storytelling around gRPC. Their high speed to approach to doing APIs that uses HTTP/2 as a transport, and protocol buffers (ProtoBuf) as its serialized message format. Even with all this motion forward they aren’t leaving everyone doing basic web APIs behind, and are actively supporting both approaches across all new Google APIs, as well as in their services and tooling for deploying APIs in the Google Cloud–supporting two-speed APIs side by side, across their platform. When you are using Google Cloud Endpoints to deploy and manage your APIs, you can choose to offer a more RESTful edition, as well as a more advanced gRPC edition...

OpenAPI Makes Me Feel Like I Have A Handle On What An API Does

18 April 2018
APIs are hard to talk about across large groups of people, while ensuring everyone is on the page. APIs don’t have much a visual side to them, providing a tangible reference for everyone to use by default. This is where OpenAPI comes in, helping us “see” an API, and establish a human and machine readable document that we can produce, pass around, and use as a reference to what an API does. OpenAPI makes me feel like I have a handle on what an API does, in a way that can actually have a conversation around with other people–without it, things are much fuzzier. Many folks associate OpenAPI with documentation, code generation, or some other tooling or service that uses the specification–putting their emphasis on the tangible thing, over the definition...

My Response To The VA Microconsulting Work Statement On API Landscape Analysis

17 April 2018
The Department of Veterans Affairs (VA) is listening to my advice around how to execute their API strategy and adopting a micro-approach to not just delivering services, but also to the business of moving the platform forward at the federal agency. I’ve responded to round one, and round two of the RFI’s, and now they have submitted a handful of work statements on Github, so I wanted to provide an official response, share my thoughts on each of the work statements, and actually bid for the work. First, Here is The VA Background The Lighthouse program is moving VA towards an Application Programming Interface (API) first driven digital enterprise, which will establish the next generation open management platform for Veterans and accelerate transformation in VA’s core functions, such as Health, Benefits, Burial and Memorials...

My Response To The VA Microconsulting Work Statement On API Outreach

17 April 2018
The Department of Veterans Affairs (VA) is listening to my advice around how to execute their API strategy and adopting a micro-approach to not just delivering services, but also to the business of moving the platform forward at the federal agency. I’ve responded to round one, and round two of the RFI’s, and now they have submitted a handful of work statements on Github, so I wanted to provide an official response, share my thoughts on each of the work statements, and actually bid for the work. First, Here is The VA Background The Lighthouse program is moving VA towards an Application Programming Interface (API) first driven digital enterprise, which will establish the next generation open management platform for Veterans and accelerate transformation in VA’s core functions, such as Health, Benefits, Burial and Memorials...

My GraphQL Thoughts After Almost Two Years

16 April 2018
It has been almost a year and half since I first wrote my post questioning that GraphQL folks didn’t want to do the hard work of API design, which I also clarified that I was keeping my mind open regarding the approach to delivering APIs. I’ve covered several GraphQL implementations since then, as well as my post on waiting the GraphQL assault out-to which I received a stupid amount of, “dude you just don’t get it!”, and “why you gotta be so mean?” responses. GraphQL Is A Tool In My Toolbox I’ll start with my official stance on GraphQL. It is a tool in my API toolbox. When evaluating projects, and making recommendations regarding what technology to use, it exists alongside REST, Hypermedia, gRPC, Server-Sent Events (SSE), Websockets, Kafka, and other tools...

If Github Pages Could Be Turned On By Default I Could Provide A Run On Github Button

16 April 2018
My world runs on Gitub. 100% of my public website projects run on Github Pages, and about 75% of my public web applications run on Gitub Pages. The remaining 25% of it all is my API infrastructure. However, I’m increasingly pushing my data and content APIs to run entirely on Github with Github Pages as frontend, and the Github repo as the backend, with the Github API as the transport. I’d rather be serving up static JSON and YAML from repositories, and building JavaScript web applications that run using Jekyll, than dynamic server-side web applications. It is pretty straightforward to engineer HTML, CSS, and JavaScript applications that run entirely on Github Pages, and leverage JSON and YAML stored in the underlying Github repo as the database backend, using the Github API as the API backend...

Sharing API Definition Patterns Across Teams By Default

10 April 2018
This is a story, in a series I’m doing as part of the version 3.0 release of the Stoplight.io platform. Stoplight.io is one the few API service providers I’m excited about what when it comes to what they are delivering in the API space, so I jumped at the opportunity to do some paid work for them. As I do, I’m working to make these stories about the solutions the provide, and refrain from focusing on just their product, hopefully maintaining my independent stance as the API Evangelist, and keeping some of the credibility I’ve established. One of the things I’m seeing emerge from the API providers who are further along in their API journey, is a more shared experience when it comes to not just the API design process, but in action throughout the API lifecycle...

I Will Be Speaking At The API Conference In London This Week

09 April 2018
I am hitting the road this week heading to London to speak at the API Conference. I will be giving a keynote on Thursday afternoon, and conducting an all day workshop on Friday. Both of my talks are a continuation of my API life cycle work, and pushing forward my use of a transit map to help me make sense of the API life cycle. My keynote will be covering the big picture of why I think the transit model works for making sense of complex infrastructure, and my workshop is going to get down in the weeds with it all. My keynote is titled, “Looking At The API Life Cycle Through The Lens Of A Municipal Transit System”, with the following abstract, “As we move beyond a world of using just a handful of internal and external APIs, to a reality where we operate thousands of microservices, and depend on hundreds of 3rd party APIs, modern API infrastructure begins to look as complex as a municipal transit system...

The ClosedAPI Specification

09 April 2018
You’ve heard of OpenAPI, right? It is the API specification for defining the surface area of your web API, and the schema you employ–making your public API more discoverable, and consumable in a variety of tools services. OpenAPI is the API definition for documenting your API when you are just getting started with your platform, and you are looking to maximize the availability and access of your platform API(s). After you’ve acquired all the users, content, investment, and other value, ClosedAPI is the format you will want to switch to, abandoning OpenAPI, for something a little more discreet. Collect As Much Data As You Possibly Can Early on you wanted to be defining the schema for your platform using OpenAPI, and even offering up a GraphQL layer, allowing your data model to rapidly scale, adding as may data points as you possible can...

Details Of The API Evangelist Partner Program

09 April 2018
I’ve been retooling the partner program for API Evangelist. There are many reasons for this, and you can read the full backstory I have written a narrative for these changes to the way in which I partner. I need to make a living, and my readers are expecting me to share relevant stories from across the sector on my blog. I’m also tired of meaningless partner arrangements that never go anywhere, and I’m looking to incentivize my partners to engage with me, and the API community in an impactful way. I’ve crafted a program that I think will do that. While there will still be four logo slots available for partnership, the rest of the references to API services providers and the solutions they provide will be driven by my partner program...

Crafting A Productive API Industry Partner Program

09 April 2018
I struggle with partner relationships. I’ve had a lot of partners operating API Evangelist over the years. Some good. Some not so good. And some amazing! You know who you are. It’s tough to fund what I do as the API Evangelist. It’s even harder to fund who I am as Kin Lane. I’ve revamped my approach to partnering several times now trying to find the right formula for me, my partners, and for my readers. As the partner requests pile up, and I fall short for some of my existing partners, while delivering as expected for others, it is time for me to take another crack at shaping my partner program. A Strong Streamdata.io Partnership Base A cornerstone of my new approach to partnering is based upon my relationship with Streamdata...

Nest Branding And Marketing Guidelines

05 April 2018
I’m always looking out for examples of API providers who have invested energy into formalizing process around the business and politics of API operations. I’m hoping to aggregate a variety of approaches that I can aggregate into a single blueprint that I can use in my API storytelling and consulting. The more I can help API providers standardize what they do, the better off the API sector will be, so I’m always investing in the work that API providers should be doing, but doesn’t always get prioritized. The other day while profiling the way that Nest uses Server-Sent Events (SSE) to stream activity via thermostats, cameras, and the other devices they provide, and I stumbled across their branding policies...

Seamless API Lifecycle Integration With Github, Gitlab, And BitBucket

05 April 2018
This is a story, in a series of stories that I’m doing as part of the version 3.0 release of the Stoplight.io platform. Stoplight.io is one the few API service providers I’m excited about what when it comes to what they are delivering in the API space, so I jumped at the opportunity to do some paid work for them. As I do, I’m working to make these stories about the solutions the provide, and refrain from focusing on just their product, hopefully maintaining my independent stance as the API Evangelist, and keeping some of the credibility I’ve established over the years. Github, Gitlab, and Bitbucket have taken up a central role in the delivery of the valuable API resources we are using across our web, mobile, and device-based applications...

Helping Stoplight.io Get The Word Out About Version 3.0

05 April 2018
I’ve been telling stories about what the Stoplight.io team has been building for a couple of years now. They are one of the few API service provider startups left that are doing things that interest me, and really delivering value to their API consumers. In the last couple of years, as things have consolidated, and funding cycles have shifted, there just hasn’t been the same amount of investment in interesting API solutions. So when Stoplight.io approached me to do some storytelling around their version 3.0 release, I was all in. Not just because I’m getting paid, but because they are doing interesting things, that I feel are worth talking about. I’ve always categorized Stoplight.io as an API design solution, but as they’ve iterated upon the last couple of versions, I feel they’ve managed to find their footing, and are maturing to become one of the few truly API lifecycle solutions available out there...

OpenAPI Is The Contract For Your Microservice

03 April 2018
I’ve talked about how generating an OpenAPI (fka Swagger) definition from code is still the dominate way that microservice owners are producing this artifact. This is a by-product of developers seeing it as just another JSON artifact in the pipeline, and from it being primarily used to create API documentation, often times using Swagger UI–which is also why it is still called Swagger, and not OpenAPI. I’m continuing my campaign to help the projects I’m consulting on be more successful with their overall microservices strategy by helping them better understand how they can work in concert by focus in on OpenAPI, and realizing that it is the central contract for their service. Each Service Begins With An OpenAPI Contract There is no reason that microservices should start with writing code...

Github Is Your Asynchronous Microservice Showroom

03 April 2018
When you spend time looking at a lot of microservices, across many different organizations, you really begin to get a feel for the ones who have owners / stewards that are thinking about the bigger picture. When people are just focused on what the service does, and not actually how the service will be used, the Github repos tend to be cryptic, out of sync, and don’t really tell a story about what is happening. Github is often just seen as a vehicle for the code to participate in a pipeline, and not about speaking to the rest of the humans and systems involved in the overall microservices concert that is occurring. Github Is Your Showroom Each microservices is self-contained within a Github repository, making it the showcase for the service...

An OpenAPI Service Dependency Vendor Extension

02 April 2018
I’m working on a healthcare related microservice project, and I’m looking for a way to help developers express their service dependencies within the OpenAPI or some other artifact. At this point I’m feeling like the OpenAPI is the place to articulate this, adding a vendor extension to the specification that can allow for the referencing of one or more other services any particular service is dependent on. Helping make service discovery more machine readable at discovery and runtime. To help not reinvent the wheel, I am looking at using the Schema.org Web API type including the extensions put forth by Mike Ralphson and team. I’d like the x-api-dependencies collection to adopt a standardized schema, that was flexible enough to reference different types of other services...

The API Stack Profiling Checklist

02 April 2018
I just finished a narrative around my API Stack profiling, telling the entire story around the profiling of APIs for inclusion in the stack. To help encourage folks to get involved, I wanted to help distill down the process into a single checklist that could be implemented by anyone. The Github Base Everything begins as a Github repository, and it can existing in any user or organization. Once ready, I can fork and publish as part of the API stack, or sync with an existing repository project. Create Repo - Create a single repository with the name of the API provider in plain language. Create README - Add a README for the project, articulating who the target is and the author. OpenAPI Definition Profiling the API surface area using OpenAPI, providing a definition of the request and response structure for all APIs...

My API Stack Profiling Process

02 April 2018
I am escalating conversations I’m having with folks regarding how I profile and understand APIs as part of my API Stack work. It is something I’ve been evolving for 2-3 years, as I struggle with different ways to attack and provide solutions within the area of API discovery. I want to understand what APIs exist out there as part of my industry research, but along the way I want to also help others find the APIs they are looking for, while also helping API providers get their APIs found in the first place. All of this has lead me to establish a pretty robust process for profiling API providers, and document what they are doing. As I shift my API Stack work into 2nd gear, I need to further formalize this process, articulate to partners, and execute at scale...

The OpenAPI 3.0 GUI

30 March 2018
I have been editing my OpenAPI definitions manually for some time now, as I just haven’t found a GUI editor that works well with my workflow. Swagger editor really isn’t a GUI solution, and while I enjoy services like Stoplight.io, APIMATIC, and others, I’m very picky about what I adopt within my world. One aspect of this is that I’ve been holding out for a solution that I can run 100% on Github using Github Pages. I’ve delusionally thought that someday I would craft a slick JavaScript solution that I could run using only Github Pages, but in reality I’ve never had the time to pull together. So, I just kept manually editing my OpenAPI definitions on the desktop using Atom, and publish to Github as I needed...

Obtaining A Scalable API Definition Driven API Design Workflow On Github

30 March 2018
There is a lot of talk of an API design first way of doing things when it comes to delivering microservices. I’m seeing a lot of organizations make significant strides towards truly decoupling how they deliver the APIs they depend on, and continue to streamline their API lifecycle, as well as governance. However, if you are down in the weeds, doing this work at scale, you know how truly hard it is to actualy get everything working in concert across many different teams. While I feel like I have many of the answers, actually achieving this reality, and assembling the right tools and services for the job is much harder then it is in theory. There was a question posted on API Craft recently that I think gets at the challenges we all face: We plan to use Open API 3 specification for designing API’s that are required to build our enterprise web application...

Using Postman to Explore the Triathlon API

30 March 2018
I’m taking time to showcase any API I come across who have published their OpenAPI definitions to Github like New York Times, Box, Stripe, SendGrid, Nexmo, and others have. I’m also taking the time to publish stories showcasing any API provider who similarly publish Postman Collections as part of their API documentation. Next up on my list is the Triathlon API, who provides a pretty sophisticated API stack for managing triathlons around the world, complete with a list of Postman Collections for exploring and getting up and running with their API. Much like Okta, which I wrote about last week, the Triathlon API has broken their Postman Collections into individual service collections, and provides a nice list of them for easy access...

The Impact Of Availability Zones, Regions, And API Deployment Around The Globe

29 March 2018
Werner Vogels shared a great story looking back at 10 years of compartmentalization at AWS, where he talks about the impact Amazon has made on the landscape by allowing for the deployment of resources into different cloud regions, zones, and jurisdictions. I agree with him regarding the significant impact this has had on how we deliver infrastructure, and honestly isn’t something that gets as much recognition and discussion as it should. I think this is partly due to the fact that many companies, organizations, institutions, and governments are still making their way to the cloud, and aren’t far enough in their journeys to be able to sufficiently take advantage of the different availability zones...

Sharing The APIs.json Vision Again

28 March 2018
I know many folks in the API sector don’t know about APIs.json, and if they do they often think it is yet another API definition format, competing wit OpenAPI, Postman Collections, and others. So, I want to take a moment to share the vision again, and maybe convert one or two more folks to the possibilities around having a machine readable format for the entire operations. This is where APIs.json elevates the conversation, is it isn’t just about defining an API, it is about defining API operations, looking to make things more discoverable, and executable by default. APIs.json is a JSON format, as the name implies, but admittedly a bad name, as I’ve already started created APIs.yaml editions, which defines the entire API operations, not just any single API...

A Decade Later Twitters API Plan Slowly Begins To Take Shape

28 March 2018
It’s been a long, long road for Twitter when it comes to realizing the importance of having a plan when it comes to their API management strategy. Aside from monetizing the firehose through former parter, and now acquired solution Gnip, Twitter has never had any sort of plan when it came to providing access tiers for their API. I try to revisit the Twitter developer portal a couple times a year, but I’m going to have to increase the number of visits as there seems to be more rapid shifts towards getting control over their API management layer in recent months. The API plan matrix that has emerged as part of Twitter’s pricing page provides a view of the unfolding plan for the social media platform...

Data Driven Apps At Scale Using Github And Jekyll

28 March 2018
I’ve pushed my Github driven, Jekyll fueled, application delivery process to a new levels the last couple of weeks. I’ve been investing more cycles into my API Stack work, as I build out an API Gallery for Streamdata.io. All of my work as the API Evangelist has long lived as independent Github repositories, with a JSON or YAML core that drives the static Jekyll UI for my websites, applications, and API developer portals. Designed to be independent, data and API driven micro-solutions to some related aspect of my API research. I’m just turning up the volume on what already exists. I’m taking this to the next level with my approach to API discovery. API Stack used to be a single Github repository with huge number of APIs...

OAuth Has Many Flaws But It is The Best We Have At The Moment

27 March 2018
I was enjoying the REST API Notes newsletter from my friend Matthew Reinbold (@libel_vox) today, and wanted to share my thoughts on his mention of my work while it was top of my mind. I always enjoy what Matt has to say, and regularly encourage him writing on his blog, and keep publishing his extremely thoughtful newsletter. It is important for the API sector to have many thoughtful, intelligent voices breaking down what is going on. I recommend subscribing to REST API Notes if you haven’t, you won’t regret it. Anyways, Matt replied with the following about my Facebook response: Kin Lane did a fine job identifying the mechanisms most companies already have in place to mitigate the kind of bad behavior displayed by Cambridge Analytica...

Government Has Benefitted From Lack Of Oversight At The Social API Management

27 March 2018
There are many actors who have benefitted from Facebook not properly management their API platform. Collecting so many data points, tracking so many users, and looking the other way as 3rd party developers put them to use in a variety of applications. Facebook did what is expected of them, and focused on generating advertising revenue from allowing their customers to target the many data points that are generated by the web and mobile applications developed on top of their platform. I hear a lot of complaining about this being just about democrats being upset that it was the republicans who were doing this, when in reality there are so many camps that are complicit in this game, if you are focusing in on any single camp you are probably looking to shift attention and blame from your own camp, in my opinion...

Acknowledging That Why I Do APIs Is Very Different Than Why Others Are Doing

27 March 2018
When I started doing API Evangelist in 2010 I was still very, very, very naive about why people were doing APIs. While I do not always expect everyone doing APIs to be ethical and sensible with the reasons behind doing APIs, I have been regularly surprised at how many different views there are out there regarding why we should be doing APIs in the first place. The lesson for me is to never assume that someone is doing APIs for the same reasons I am doing APIs, because rarely that will ever be the case–hopefully minimizing the chances I’ll get continue to be surprised down the road. After watching Salesforce, then Amazon, Flickr, Twitter, Facebook, and Google Maps doing APIs, I saw the potential for APIs to open up access to resources like never before...

Sharing Your API First Principles

27 March 2018
I’ve been publishing regular posts from the API design guides of API providers I’ve been studying. API providers who publish their API design guides tends to be further along in their API journey. These API providers tend to have more experience and insight, and are often worth studying further, and learning from. I’ve bee getting a wealth of valuable information from the German fashion and technology company Zalando, who has shared some pretty valuable API first principles. In a nutshell Zalando’s API First principles focuses on two areas: define APIs outside the code first using a standard specification language get early review feedback from peers and client developers By defining APIs outside the code, Zalando wants to facilitate early review feedback and also a development discipline that focus service interface design on: profound understanding of the domain and required functionality generalized business entities / resources, i...

Nexmo Manages Their OpenAPI 3.0 Definition Using Github

26 March 2018
I’m big on supporting API providers that publish their OpenAPI definitions to Github. It is important for the wider API community that ALL API definitions are machine readable, and available in a way that can be forked, and integrated into continuous integration pipelines. I’m not even talking about the benefits to the API providers when it comes to managing their own API lifecycle. I’m just focusing on the benefits to API consumers, and helping make on-boarding, integration, and keeping in sync with the road map as frictionless as possible. To help incentivize API providers doing this I’m committed to writing up stories for each API provider that publishes their OpenAPI, APIs.json, or Postman Collections to Github...

A Regulatory Framework For Facebook And Other Platforms Is Already In Place

26 March 2018
There is lots of talk this week about regulating Facebook after the Cambridge Analytica story broke. Individuals, businesses, lawmakers, and even Facebook are talking about how we begin to better regulate not just Facebook, but the entire data industry. From my perspective, as the API Evangelist, the mechanisms are already in place, they just aren’t being used to their fullest by providers, with no sufficient policy in place at the federal level to incentivize healthy behavior by API providers, data brokers, and 3rd party application developers. API Management Is Already In Place Modern API platforms, Facebook included, leverage what is called an API management layer, to help manage the applications being developed on their platforms...

Investment In API Security Will Continue To Fall Short While There Is No

21 March 2018
I have a lot of conversations with folks down in the trenches about API security, and what they are doing to be proactive when it comes to keeping their API infrastructure secure. The will and the desire amongst folks I talk to regarding API security is present. They want to do what it takes to truly understand what is needed to keep their APIs secure, but many have their hands tied because lack of resources to actually do what is needed. Every API team I know is short-handed, and doing the best they can with what they have available to them. A lack of investment in API security isn’t always intentional, it ends up just begin a reality of the priorities on the ground within the organizations they work in...

Facebooks Business Model Is Out Of Alignment With Their API Management Layer

21 March 2018
All the controls for Facebook to have done something about the Cambridge Analytics situation are already in place. The Facebook API management layer has everything needed to have prevented the type of user data abuse we’ve experienced, and honestly the user data abuse that has happens in many other applications, and will continue to occur. The cause of this behavior is rooted in Facebook’s business model, and a wider culture that is fueled by venture capital investment, and backdoor data brokering. It is just how the big data / app economy is funded, and when your business model is all based upon advertising, user engagement to generate data / signals, and being about leveraging that behavior for targeting–you are never going to reign in your API management layer...

SendGrid Managing Their OpenAPI Using Github

20 March 2018
This is a post that has been in my API notebook for quite a while. I feel it is important to keep showcasing the growing number of API providers who are not just using OpenAPI, but also managing them on Github, so I had to make the time to talk about the email API provider SendGrid managing their OpenAPI using Github. Adding to the stack of top tier API providers managing their API definitions in this way. SendGrid is managing announcements around their OpenAPI definition using Github, allowing developers to signup for email notifications around releases and breaking changes. You can use the Github repository to stay in tune with the API roadmap, and contribute feature requests, submit bug reports, and even submit a pull request with the changes you’d like to see...

Breaking Down Your Postman API Collections Into Meaningful Units Of Compute

20 March 2018
I’m fascinated with the unit of compute as defined by a microservice, OpenAPI definition, Postman Collection, or other way of quantifying an API-driven resource. Asking the question, “how big or how small is an API?”, and working to define the small unit of compute needed at runtime. I do not feel there is a perfect answer to any of these questions, but it doesn’t mean we shouldn’t be asking the questions, and packaging up our API definitions in a more meaningful way. As I was profiling APIs, and creating Postman Collections, the Okta team tweeted at me, their own approach to delivering their APIs. They tactically place Run in Postman buttons throughout their API documentation, as well as provide a complete listing of all the Postman Collections they have...

General Data Protection Regulation (GDPR) Forcing Us To Ask Questions About

19 March 2018
I’ve been learning more about the EU General Data Protection Regulation (GDPR) recently, and have been having conversation about compliance with companies in the EU, as well as the US. In short, GDPR requires anyone working with personal data to be up front about the data they collect, making sure what they do with that data is observable to end-users, and takes a privacy and security by design approach when it comes to working with all personal data. While the regulations seems heavy handed and unrealistic to many, it really reflects a healthy view of what personal data is, and what a sustainable digital future will look like. The biggest challenge with becoming GDPR compliant is the data mess most companies operate in...

Facebook, Cambridge Analytica, And Knowing What API Consumers Are Doing With Our Data

19 March 2018
I’m processing the recent announcement by Facebook to shut off the access of Cambridge Analytica to it’s valuable social data. The story emphasizes the importance of having a real time awareness and response to API consumers at the API management level, as well as the difficulty in ensuring that API consumers are doing what they should be with the data and content being made available via APIs. Access to platforms using APIs is more art than science, but there are some proven ways to help mitigate serious abuses, and identify the bad actors early on, and prevent their operation within the community. While I applaud Facebook’s response, I’m guessing they could have taken more action earlier on...

68 Stops In A Comprehensive API Strategy Transit Map

16 March 2018
I am refining my comprehensive list of stops that I highlight as part of the API lifecycle, or what I call API Transit–the stops that each of the services we deliver will have “pass through” at some point. I’m sharing this list with other team members as part of existing consulting arrangements I’m engaged in with Streamdata.io, as well as baking into my API transit work for some workshops I’m doing in April. All of these are available on the API lifecycle section of API Evangelist, but I will be pushing them to become a first class citizen on the home page of API Evangelist once again. Here are 68 potential stops I’d consider for any microservice to be exposed to, as part of a larger API transit strategy map: Definitions - From the simplest definition of what a service does, all the way to the complete OpenAPI definition for each service...

A Visual View Of API Responses Within Our Documentation

14 March 2018
Interactive API documentation is nothing new. We’ve had Swagger UI, and other incarnations for over five years now. We also have API explorers, and full API lifecycle client solutions like Postman to help us engage with APIs, and be able to quickly see responses from the APIs we are consuming. In my effort to keep pushing forward the API documentation conversation I’ve been beating the drum for more visual solutions to be baked into our interactive documentation for a while now, encouraging providers to make the responses we receive much more meaningful, and intuitive for consumers. To help drum up awareness to this aspect of API documentation I’m always on the lookout for any interesting examples of it in the wild...

LinkedIn Account Validation For New API Consumers

14 March 2018
I was on-boarding with the data marketplace Dawex the other day, and I thought their on-boarding process was interesting. It is pretty rigid, requiring users to validate themselves in multiple ways, but it provides some interesting approaches to knowing more about who your API developers are. Dawex has the basic level email and phone number validation, but they have added a 3rd dimension, validating who you are using your LinkedIn profile. After signing up, I was required to validate my email account–pretty standard stuff. Then I was asked to enter a code sent to my cell phone via SMS–not as common, but increasingly a way that platforms are using to verify you. Then I was asked to OAuth and connect my LinkedIn account to my Dawex profile...

An OpenAPI Vendor Extension For Defining Your API Audience

14 March 2018
The clothing marketplace Zalando has an interesting approach to classifying their APIs based upon who is consuming them. It isn’t just about APIs being published publicly, or privately, they actually have standardized their definition, and have established an OpenAPI vendor extension, so that the definition is machine readable and available via their OpenAPI. According to the Zalando API design guide, “each API must be classified with respect to the intended target audience supposed to consume the API, to facilitate differentiated standards on APIs for discoverability, changeability, quality of design and documentation, as well as permission granting. We differentiate the following API audience groups with clear organisational and legal boundaries...

Rules for Extending Your API With Each Version

14 March 2018
I’m spending time learning from the API design guides of other leading API providers, absorbing their healthy practices, and assimilating them into my own consulting and storytelling. One API design guide I am learning a lot from is out of the Adidas Group, which contains a wealth of wisdom regarding not just the design of your API, but also the deployment and evolution of the API resources we are publishing. One particularly interesting piece of advice I found within Adidas API design guidance were their rules for extending an API, which I think is pretty healthy advice for an API developer to think about. Any modification to an existing API MUST avoid breaking changes and MUST maintain backward compatibility...

Seeing Messy API Design Practices As An Opportunity

13 March 2018
I’m generating OpenAPI definitions for a wide variety of APIs currently, and I’m regularly stumbling on the messiness of the API design practices being deployed. When you are exposed to a large number of different APIs it is easy to get frustrated, begin ranting, and bitching about how ignorant people are of healthy, sensible API practices. This is the easy route. Making sense of it all, finding the interesting signals and patterns, and extracting where the opportunity are takes a significant amount of effort (so does biting tongue). After profiling almost 500 API providers, I have almost 25K separate API paths indexed using OpenAPI, and APIs.json. I’ve tagged each API path using its OpenAPI definition...

Google Releases a Protocol Buffer Implementation of the Fast Healthcare

13 March 2018
Google is renewing its interest in the healthcare space by releasing a protocol buffer implementation of the fast healthcare interoperability resources (FHIR) standard. Protocol buffers are “Google’s language-neutral, platform-neutral, extensible mechanism for serializing structured data – think XML, but smaller, faster, and simpler”. Its the core of the next generation of APIs at Google, often using HTTP/2 as a transport, while also living side by side with RESTful APIs, which use OpenAPI as the definition, in parallel to what protocol buffers deliver. It’s a smart move by Google. Providing a gateway for healthcare data to find its way to their data platform products like Google Cloud BigQuery, and their machine learning solutions built on Tensorflow...

Multi-Lingual Machine Learning API Deployments

13 March 2018
Machine learning API ParallelDots has a story on launching their APIs in multiple languages. Allowing them to “serve a truly global customer base with following language options for our key APIs (Sentiment Analysis, Emotion Analysis, and Keyword generator)”. Something that I think more APIs providers are going to have to think about in coming years, as the need for API resources expands around the globe. I’m tracking on the localization efforts of different API providers, and I’d say that having service availability in different regions, and multi-lingual support are the top two areas I’m seeing movement. I see two driving forces behind this, 1) the customers are demanding localization for their businesses, and 2) the governments in those countries are imposing regulations and other laws that dictate where resources can be stored and operate...

API As A Product Principles From Zalando

13 March 2018
As I’m working through the API design guides from API leaders, looking for useful practices that I can include in my own API guidance, I’m finding electronic commerce company Zalando’s API design guide full of some pretty interesting advice. I wanted to showcase the section about their API as a product principles, which I think reflects what I hear many companies striving for when they do APIs. From the Zalando API design guide principles: Zalando is transforming from an online shop into an expansive fashion platform comprising a rich set of products following a Software as a Platform (SaaP) model for our business partners. As a company we want to deliver products to our (internal and external) customers which can be consumed like a service...

The Importance Of Tags In OpenAPI Definitions For Machine Learning APIs

12 March 2018
I am profiling APIs as part of my partnership with Streamdata.io, and my continued API Stack work. As part of my work, I am creating OpenAPI, Postman Collections, and APIs.json indexes for APIs in a variety of business sectors, and as I’m finishing up the profile for ParallelDots machine learning APIs, I am struck (again) by the importance of tags within OpenAPI definitions when it comes to defining what any API does, and something that will have significant effects on the growing machine learning, and artificial intelligence space. While profiling ParallelDots, I had to generate the OpenAPI definition from the Postman Collection they provide, which was void of any tags. I went through the handful of API paths, manually adding tags for each of the machine learning resources...

Some Common API Data Types To Put To Use

12 March 2018
I’m continuing my exploration of the API design guidance published by leading API providers. This time, I am taking a look at the API design guide publish by Adidas, specifically the portion of it addressing what some of the common API types should be. Providing some API design essentials, that all of us API providers should be baking into our APIs by default. Here is the short list of default standards Adidas is supporting across their API operations: Date and Time Format - Date and Time MUST always conform to the ISO 8601 format e.g.: 2017-06-21T14:07:17Z (date time) or 2017-06-21 (date), it MUST use the UTC (without time offsets). Duration Format - Duration format MUST conform to the ISO 8601 format standard e...

Thinking About API Status Codes For Destroying Entities Using DELETE

12 March 2018
I am pulling together some API design guidance for some projects I’m consulting on, so I’m spending time reviewing the API design guides the leading API providers who have published them publicly. Learning from what they are doing across their own companies, organizations, institutions, and government agencies when it comes to sensible API governance. Today, I am learning from the British food delivery company, Deliveroo, and documenting their guidance for which HTTP status codes should be returned for any API methods that use DELETE: If it exists, it should return status: 204 No Content if the entity was successfully destroyed, 404 Not Found if the entity does not exist 410 Gone if the entity is known to have existed but no longer does...

A Machine Readable Baseline For API Providers In My API Stack Work

12 March 2018
I’m rebooting my API Stack work as part of my partnership with Streamdata.io. I’m spending a significant portion of my day profiling API providers, documenting what it is they bring to the table. Historically I’ve published the resulting APIs.json and OpenAPI definition(s) to a single Github repository driving theapistack.com. The primary folder was already getting too big, and since I’m looking at adding at least a thousand more API providers to the stack, I am going to need to shard things out a bit. To help accommodate the increased scale, I’m breaking up the API Stack into two separate Github organizations. One for individual API providers called api-stack-providers, and a second for individual topics called api-stack-topics...

Defining The Smallest Unit Possible For Use At API Runtime

09 March 2018
I’m thinking a lot about what is needed at API runtime lately. How we document and provide machine readable definitions for APIs, and how we provide authentication, pricing, and even terms of service to help reduce friction. As Mike Amundsen (@mamund) puts it, to enable “find and bind”. This goes beyond simple API on-boarding, and getting started pages, and looks to make APIs executable within a single click, allowing us to put them to use as soon as we find them. The most real world example of this in action can be found with the Run in Postman button, which won’t always deal with the business and politics of APIs at runtime, but will deal with just about everything else. Allowing API providers to publish Run in Postman Buttons, defined using a Postman Collection, which include authentication environment details, that API consumers can use to quickly fire up an API in a single click...

The Postman API Network

09 March 2018
The Postman API Network is one of the recent movements in the API discovery space I’ve been working to get around to covering. As Postman continues its expansion from being just an API client, to a full lifecycle API development solution, they’ve added a network for discovering existing APIs that you can begin using within Postman in a single click. Postman Collections make it ridiculously easy to get up and running with an API. So easy, I’m confounded why ALL APIs aren’t publishing Postman Collections with Run in Postman Buttons published in their API docs. The Postman API Network provides a catalog of APIs in over ten categories, with links to each API’s documentation. All of the APIs in the network have a Run in Postman button available as part of their documentation, which includes them in the Postman API Network...

Keeping Track Of Federal Government Open Source Projects Using The Code.gov

09 March 2018
Open source software is increasingly driving the federal government, despite the wishes of companies like Oracle. I’ve been watching an interesting project grow within the federal government to help quantify open source across the federal government called Code.gov, which “leverages the power of code sharing and collaboration to help the US Government cut down on duplicative software development and save millions of taxpayer dollars for the American people.” Something I think we can all get behind, when it comes to the collision of technology and government we are seeing play out. Code.gov allows you to browse open source projects by government agency, see the details for the project, visit the repository, and contact the project owners...

Imagine A Mock Only API Development Reality

08 March 2018
Imagine if we didn’t actually write code when we developed our APIs initially. What if the bar for putting an API into production was so high, that many APIs never actually made it to that level. I spend a lot of time mocking and prototyping APIs, but I don’t have a strict maturity model determining when I actually bring an API to life using code. I’d love it if I never actually write code for many of my API prototypes and just mocked them, and iterated upon the mocks instead of thinking they needed actually have a database backend, and code or gateway front-end. What if I only executed these stops along the API lifecycle, instead of actually writing any code: Define - Define what I want my API to do, and what types of resources will be involved...

Axway Asking for an OpenAPI of The Streamdata.io API So They Can Screenshot It

08 March 2018
We are working closely with Axway on a number of projects over here at Streamdata.io. After we got out of a meeting with their team the other day we received an email from them asking if we had an OpenAPI definition for a demo Streamdata.io market data API. They were wanting to include it in some marketing materials, and needed a screenshot of it. To be able to generate the visual they desired, they needed an OpenAPI to make it tangible enough for capturing in a screenshot and presenting as part of a larger story. This may sound like a pretty banal thing, but when you step back and realize the importance of OPenAPI when it comes to communication, and making something very abstract a tangible, visual thing, it becomes more significant...

Your Obsessive Focus On The API Resource Is Hindering Meaningful Events From

08 March 2018
I’ve been profiling a number of market data APIs as part of my work with Streamdata.io to identify valuable sources of data that could be streamed using their service. A significant portion of the APIs I come across are making it difficult for me to get at the data they have because of their views around the value of the data, intellectual property, and maintaining control over it in an API-driven world. These APIs don’t end up on the list of APIs I’m including in the profiling work, the gallery / directory, and don’t get included in any of the stories I’m telling, as a result of this tight control. The side effect of this is I end up getting repeated sales emails and phone calls asking if I am still interested in their data...

US Companies Getting Ahead Of EU Regulations

07 March 2018
I find it to be a telling sign of the culture at US companies when it comes to their response, or lack of response to EU regulations. I’ve been curating stories from the API providers that I track on when it comes to GDPR or PSD2, keeping a notebook or research that is ready when I get around to diving in deeper. The companies who are openly talking about these regulations and being proactive about responding to them, are usually the API providers who have a strong stance in the US market, and are poised to, or already expanding this reach to Europe. Companies who haven’t made any noise are probably not concerned with the European market, or just hoping the regulations fizzle out I guess? After diving into my curation notebook the first company to stand out is Auth0, with a variety of blog posts, and resources on navigating both PSD2 and GDPR...

Where Do We Start The API Conversation At Our Large Organization?

07 March 2018
It can be tough to know where to start with APIs at your large organization. Everyone is already in motion, in a variety of groups, geographic regions, serving different lines of business. The API conversation is already occurring across your organization, it is just happening in a distributed and fragmented way, without any coherent orchestration, and strategy moving it forward in unison. I’d like to sit down with your team(s), and understand what APIs look like across your organization, and help work through a first draft of your API strategy, and define how we can better orchestrate existing efforts, and begin establishing an API governance framework for bringing the API vision into focus...

Capital One DevExchange Provides An Important Banking API Blueprint

06 March 2018
When you take a look at the banking API landscape in the United States, there is one clear leader in the game–Capital One. Their DevExchange program is miles ahead of every one of their competitors, giving them a significant head start when it comes to the banking API economy. Their approach to delivering APIs meets all of my minimum requirements for any successful API platform, and even exceeds it, providing what I’d consider to be a leading example blueprint that all banking API providers should be following. The Capital One DevExchange begins as any API operation should, with a dedicated portal located at developer.[domain]: developer.capitalone.com After landing on the home page for the Capital One DevExchange you get everything you need to get up and running with the APIs they have: Getting started Authentication Documentation Errors Login Registration The Capital One DevExchange provides four main groups of public APIs currently, started with access to account information in the following areas: Retrieve account products - /deposits/account-products (GET) Retrieve account product details - /deposits/account-products/{productId} (GET) Create new account application - /deposits/account-applications (POST) Retrieve out of wallet questions - /deposits/account-applications/{applicationId}/out-of-wallet (GET) Answer out of wallet questions - /deposits/account-applications/{applicationId}/out-of-wallet (PUT) Retrieve account application details - /deposits/account-applications/{applicationId} (GET) As well as some credit card offers, showcasing the products they have available: Retrieve product listings - /credit-offers/products (GET) Retrieve card products - /credit-offers/products/cards (GET) Retrieve card products - /credit-offers/products/cards (GET) Retrieve card products by type - /credit-offers/products/cards/{cardType} (GET) Retrieve card product details - /credit-offers/products/cards/{cardType}/{productId} (GET) Which you can actually sign up for and do a pre-qualification via APIs: Create prequalification check - /credit-offers/prequalifications (POST) Create prequalification acknowledgment - /credit-offers/prequalifications/{prequalificationId} (POST) Create applicant key - /credit-offers/applicant-details POST Get access to Capital One rewards via APIs: Retrieve rewards accounts - /rewards/accounts (GET) Retrieve rewards account details - /rewards/accounts/{rewardsAccountReferenceId} (GET) And details about merchants involved in transactions: Retrieve merchant data - /merchant-insights/merchants (GET) Refresh merchant details - /merchant-insights/merchants/{merchantId} (GET) This version of the API is available in a sandbox and production environments: Sandbox You can tell Capital One is moving cautiously with their public APIs, but they are definitely further along than other banks...

Explaining API Security To Organizational Leadership

06 March 2018
I’ve been tasked with helping explain API security to senior leadership, and wanted to work through my ideas here on the blog. For this audience, I’m not going to get down into the weeds regarding the technical specification behind OAuth, and other approaches, and try to keep things high level, introducing folks to the art that is API security. The phrase API security represents a balance of concepts because APIs are by nature about providing access, while security is about controlling and sometimes limiting access, resulting in a new way of getting business done on the open web. First, What Are APIs? APIs are not the latest trend, or vendor solution, they are the next evolution in the web...

Serverless, Like Microservices Is About Understanding Our Dependencies And

05 March 2018
I am not buying into all the hype around the recent serverless evolution in compute. However, like most trends I study, I am seeing some interesting aspects of how people are doing it, and some positive outcomes for teams who are doing it sensibly. I am not going all in on serverless when it comes to deploying or integrating with APIs, but I am using it for some projects, when it makes sense. I find AWS Lambda to be a great way to get in between the AWS API Gateway and backend resources, in order to conduct a little transformation. Keeping serverless as just one of many tools in my API deployment and integration toolbox, yet never going overboard with any single solution. I put serverless into the same section of my toolbox as I do microservices...

An OpenAPI-Driven, API Governance Rules Engine

05 March 2018
Phil Sturgeon (@philsturgeon) alerted me to a pretty cool project he is cooking up, called Speccy. Which provides a rules engine for validating your OpenAPI definitions. “Taking off from where Mike Ralphson started with linting in swagger2openapi, Speccy aims to become the rubocop or eslint of OpenAPI”, and to “sniff your files for potentially bad things. “Bad” is objective, but you’ll see validation errors, along with special rules for making your APIs better.” Helping make sure your API definitions are as consistent as they possibly can be, and deliver on your API governance strategy (you have one right?) With Speccy, there are a default set of rules, things like ensuring you have a summary or a description for each API path: { "name": "operation-summary-or-description", "object": "operation", "enabled": true, "description": "operation should have summary or description", "or": ["summary", "description"] } Or making sure you add descriptions to your parameters: { "name": "parameter-description", "object": "parameter", "enabled": true, "description": "parameter objects should have a description", "truthy": "description" } Or making sure you include tags for each aPI path: { "name": "operation-tags", "object": "operation", "enabled": true, "description": "operation should have non-empty tags array", "truthy": "tags", "skip": "isCallback" } Then you can get more strict by requiring contact information: { "name": "contact-properties", "object": "contact", "enabled": true, "description": "contact object should have name, url and email", "truthy": [ "name", "url", "email" ]<br /> } And make sure youi have a license applied to your API: { "name": "license-url", "object": "license", "enabled": true, "description": "license object should include url", "truthy": "url" } Speccy is available as a Node package, which you can easily run at the command line...

People Seem to Want Lego Kits and Not a Bucket of Lego Blocks When It Comes To

05 March 2018
While I wish everyone saw the modular potential of APIs and microservices like I do, I’ve come to the realization that most people are just interested in ready to go kits that walk them through every detail of doing APIs, rather than actually playing, learning, evolving, and learning to be productive with a big bucket of APIs. I’m not just focusing on business users here, I am talking about a significant portion of the developers I come across, who really don’t seem that interested in learning to apply API concepts, and understanding when and where to use them, they just want a set of instructions that walk them through each step of deploying an API. I actually am a proponent of there being more boxed, lego style API kits that teach you how to build the product API, task API, press release API, and other common implementations...

The Need for Standardized API Plans and Pricing to Compete with Cloud

05 March 2018
Google launched their Cloud Billing Catalog API, providing access to thee pricing for their cloud API catalog the other day. Azure has their billing API, and AWS has their cost explorer API service, showing that programmatic access to what API resources cost, as well as management of usage, billing, invoicing, and other aspects of doing business with APIs is becoming the normal mode of operating an API platform. I’ve long used AWS, Google, and increasingly Azure as a blueprint for what us smaller API providers should be doing. They are full of positive and negative lessons for any API provider. However, I’m starting to see what they are doing as not just a blueprint, but potentially something that will force many of us API providers out of businesses if we cannot emulate what they are doing at scale...

Thoughts On The Schema.Org WebAPI Type Extension

02 March 2018
I’m putting some thought into the Schema.Org WebAPI Type Extension proposal by Mike Ralphson (Mermade Software) and Ivan Goncharov (APIs.guru), to “facilitate better automatic discovery of WebAPIs and associated machine and human-readable documentation”. It’s an interesting evolution in how we define APIs, in terms of API discovery, but I would also add potentially at “execute time”. Here is what a base WebAPI type schema could look like: ```{ “@context”: “http://schema.org/”, “@type”: “WebAPI”, “name”: “Google Knowledge Graph Search API”, “description”: “The Knowledge Graph Search API lets you find entities in the Google Knowledge Graph. The API uses standard schema...

An Observable Industry Level Directory Of API Providers And Consumers

01 March 2018
I’ve been breaking down the work on banking APIs coming out of Open Banking in the UK lately. I recently took all their OpenAPI definitions and published as a demo API developer portal. Bringing the definitions out of the shadows a little bit, and showing was is possible with the specification. Pushing the project forward some more today I published the Open Banking API Directory specification to the project, showing the surface area of the very interesting, and important component of open banking APIs in the UK. The Open Banking Directory provides a pretty complete, albeit rough and technical approach to delivering observability for the UK banking industry API ecosystem actor layer. Everyone involved in the banking API ecosystem in UK has to be registered in the directory...

An Open Banking API Portal Blueprint

28 February 2018
I have been learning all about the banking API efforts out of Open Banking in the UK lately. They are evolving a set of read / write account and transaction API, as well as public data APIs for some of the common information 3rd party developers are looking to get their hands on. I'm intrigued with the traction the organization has gotten, and I want to be able to fully understand what they are developing, as well help contribute where I can. To help me understand the API specification, as well as hopefully contribute to the conversation, I am publishing an blueprint API portal for the API. It is a demo portal, running on Github, which uses the API Evangelist graphical look, but I am also publishing documentation for v1...

The Business of Running Government As A Microservices Platform

28 February 2018
I recently wrote a response to a recent Department of Veterans Affairs RFI which contained a section about the business of operating government as a microservices platform.I know that many folks wouldn’t make it that far in the 10K word response, so I wanted to break it out into its own post. I feel pretty strongly about the potential of decoupling how we deliver technology across government, but for this to be successful we are also going to have to decouple the business and politics of it all as well. This post reflects my current research and thinking about the business of APIs in government, and is part of some ongoing work I am doing around API management, public data, and how we begin to think differently about how government engages with the public in a digital age...

What We Need To Be Machine Readable At API Run Time

28 February 2018
I had breakfast with Mike Amundsen (@mamund) and Matt McLarty (@MattMcLartyBC) of the CA API Academy team this morning in midtown this morning. As we were sharing stories of what each other was working on, the topic of what is needed to execute an API call came up. Not the time consuming find an API, sign up for an account, figure out the terms of service and pricing version, but all of this condensed into something that can happen in a split second within applications and systems. How do we distill down the essential ingredients of API consumption into a single, machine readable unit that can be automated into what Mike Amundsen calls, “find and bind”. This is something I’ve been thinking a lot about lately as I work on my API discovery research, and there are a handful of elements that need to be present: Authentication - Having keys to be able to authentication...

Three Areas I Would Like To Cover When We Sit Down For An API Consulting

27 February 2018
I’m putting together some presentations for a handful of upcoming engagements, where I’m wanting to help my audience understand what an initial engagement will look like. While I am looking to have just a handful of bullets that can live on a single, or handful of slides, I also want a richer narrative to go along with it. To achieve this I rely on my blog, which helps me work my way through the details of what I do, and distill things down into something that I can deliver on the ground within the companies, organizations, institutions, and government agencies I am conducting business with. When I am sitting down with a new audience, and working to help them understand how I can help them begin, jumpstart, revive, and move forward with their API journey, I’m usually breaking things into three main areas: Landscape Mapping - Establish a map of what currently is within an organization...

Mapping Out The API Landscape

27 February 2018
As I prepare to launch the Streamdata.io API Gallery, I am doing a handful of presentations to partners. As part of this process I am looking to distill down the objectives behind the gallery, and the opportunity it delivers to just a handful of talking points I can include in a single slide deck. Of course, as the API Evangelist, the way I do this is by crafting a story here on the blog. To help me frame the conversation, and get to the core of what I needed to present, I wanted to just ask a couple questions, so that I can answer them in my presentation. What is the Streamdata.io API Gallery? It is a machine readable, continuously deployed collection of OpenAPI definitions, indexed used APIs...

What Is The Streamdata.io API Gallery?

27 February 2018
As I prepare to launch the Streamdata.io API Gallery, I am doing a handful of presentations to partners. As part of this process I am looking to distill down the objectives behind the gallery, and the opportunity it delivers to just a handful of talking points I can include in a single slide deck. Of course, as the API Evangelist, the way I do this is by crafting a story here on the blog. To help me frame the conversation, and get to the core of what I needed to present, I wanted to just ask a couple questions, so that I can answer them in my presentation. What is the Streamdata.io API Gallery? It is a machine readable, continuously deployed collection of OpenAPI definitions, indexed used APIs...

One Of The Best API Getting Started I Have Come Across

26 February 2018
I’m working my way through banking and Fintech companies in the UK, and I stumbled across the Starling banking API. I began doing my usual clicking around as I do with any API, looking at the documentation, the getting started, and other primary links. After landing on the Starling getting started page, I have to say that it is the single best example of a getting started page I have ever come across in my time as API Evangelist. It is robust, informative, well laid out, and has everything you need to well, get started. The Starling getting started page is broken up into six separate sections: 1) Register Your Application 2) Setup Starter Kit 3) Play in the Sandbox 4) Personal Access 5) Going Live 6) Contact Us Each getting started section has a simple, concise description with relevant visuals and code samples, as well as possession simple action buttons, like sign, login, register application, and the other meaningful things you need to get started...

The Banking API Actors In The UK

26 February 2018
I’ve been profiling the work of the Open Banking Implementation Entity when nit comes to banking API standards in the UK. As part of my getting up to speed on the banking ecosystem in the UK, and Europe, I’ve been posting a series of small blog posts, outlining different aspects of how things work, and who the players are. While going through the Open Banking documentation, I came across a great list of the “actors” int he Open Banking API ecosystem, which taught me a lot about who is involved, and was worth reposting here as a list. The Open Banking eco-system consists of a number of actors, which may be a natural person or an entity: Payment Service User (PSU) - Person - Payment Services User is a natural or legal person making use of a payment service as a payee, payer or both Payment Service Provider (PSP) - Legal Entity - A legal entity (and some natural persons) that provide payment services as defined by PSD2 Article 4(11) Account Servicing Payment Service Provider (ASPSP) - Legal Entity - Account Servicing Payment Service Providers provide and maintain a payment account for a payer as defined by the PSRs and, in the context of the Open Banking Ecosystem are entities that publish Read/Write APIs to permit, with customer consent, payments initiated by third party providers and/or make their customers’ account transaction data available to third party providers via their API end points...

Round Two Of The Department of Veterans Affairs Lighthouse Platform RFI

24 February 2018
I’m spending some more time thinking about APIs at the Department of Veterans Affairs (VA), in response to round two of their request for information (RFI). A couple months back I had responded to an earlier RFI, providing as much information as I could think of, for consideration as part of their API journey. As a former VA employee, and son of two Vietnam Vets (yes two), you can say I’m always willing to invest some in APIs over at the VA. To provide a response, I have taken the main questions they asked, broken them out here, and provided answers to the best of my ability. In my style, the answers are just free form rants, based upon my knowledge of the VA, and the wider API space. It is up to the VA, to decide what is relevant to them, and should be included in their agency API strategy...

AWS IAM-Like Policies For AWS API Gateway And Marketplace Billing

22 February 2018
The primary reason I’ve been adopting more AWS solutions as part of my API stack, and using tools I have historically felt lock me into the AWS ecosystem, is the available of AWS identity and access management (IAM). I just cannot deliver secure at this level as a small business owner, and their robust solution lets me dial in exactly what I need when it comes to defining who has access to what across my API infrastructure. I can define different policies, and apply them at the API management layer using both AWS Lambda and AWS API Gateway. Keeping everything separated, yet with a single API stack as the point of entry, for all consumers and applications. I want all of this security goodness, but for the business of my APIs...

An Open Banking in the UK OpenAPI Template

21 February 2018
After learning more about what Open Banking is doing for APIs in the UK, I realized that I needed an OpenAPI template for the industry specification. There are six distinct schema available as part of the project, and I wanted a complete OpenAPI to describe which paths were available, as well as the underlying response schema. I got work crafting one from the responses that were available within the Open Banking documentation. Open Banking had schema available for their API definitions, but OpenAPI is the leading API and data specification out there today, so it makes sense that there should be an OpenAPI available, helping all participating banking API providers take advantage of all the tooling available within the OpenAPI community...

Provisioning A Default App And Keys For Your API Consumers On Signup

21 February 2018
I sign up for a lot of APIs. I love anything that reduces friction when on-boarding, and allows me to begin making an API call in 1-3 clicks. I’m a big fan of API providers that allow me to signup using my Github OAuth, preventing me from having to sign up for yet another account. I’m also a big fan of providers who automatically provision an application for me as part of the signup, and have my API keys waiting for me as soon as I’ve registered. While signing up for the Sabre travel API I saw that they provisioned my application as part of the API sign up process in a way that was worth showcasing. Saving me the time and hassle of having to add a new application after I’ve signed up...

An Opportunity Around Providing A Common OpenAPI Enum Catalog

21 February 2018
I’m down in the details of the OpenAPI specification lately, working my way through hundreds of OpenAPI definitions, trying to once again make sense of the API landscape at scale. I’m working to prepare as many API path definitions as I possibly can to be runnable within one or two clicks. OpenAPI definitions, and Postman Collections are essential to making this happen, both of which require complete details on the request surface area for an API. I need to know everything about the path, as well as any headers, path, or query parameters that need to included. A significant aspect of this definition being complete includes default, and enum values being present. If I can’t quickly choose from a list of values, or run with a default value, when executing an API, the time to seeing a live response grows significantly...

What Is Open Banking In The UK?

21 February 2018
I am profiling banks in the UK as part of an effort move forward my API Stack work, and populate the Streamdata.io API Gallery. One significant advantage that banks in the UK have over other countries in the EU, and even in the US, is the help of Open Banking. To help profile the organization, I’ll just borrow from their website to define who they are and what they do. The Open Banking Implementation Entity was created by the UK’s Competition and Markets Authority to create software standards and industry guidelines that drive competition and innovation in UK retail banking. In 2016, The Competition and Markets Authority (CMA) published a report on the UK’s retail banking market which stated that older, larger banks do not have to compete hard enough for customers’ business, and smaller and newer banks were finding it difficult to grow and access the UK banking market...

Relationship Between OpenAPI Path, Summary, Tags and AysncAPI Topics

20 February 2018
I’m working my way through several hundred OpenAPI definitions that I have forked from APIs.guru, Any API, and have automagically generated from API documentation scrape scripts I have developed over time. Anytime I evolve a new OpenAPI definition, I first make sure the summary, description, and tags are as meaningful as they possibly can. Sadly this work is also constrained by how much time I have to spend with each API, as well as how well designed their API is in the first place. I have a number of APIs that help me enrich this automatically, by mining the API path, applying regular expressions, but often times it takes a manual review to add tags, polish summaries, and make the OpenAPI details as meaningful as I possibly can, in regards to what an API does...

People Who Provide Enum For Their OpenAPI Definitions Are Good People

20 February 2018
I’m processing a significant amount of OpenAPI definitions currently, as well as crafting a number of them from scraped API documentation. After you work with a lot of OpenAPI definitions, aiming to achieve a specific objective, you really get to know which aspects of the OpenAPI are the most meaningful, and helpful when they are complete. I talked about the importance of summary, description, and tags last week, and this week I’d like to highlight how helpful it is when the stewards of OpenAPI definitions include enum values for their parameters, and I think they are just good people. ;-) Enums are simply just a list of potential values for each of the parameters you outline as part of your API definition...

Insecurity Around Providing Algorithmic Transparency And Observability Using

16 February 2018
I’m working on a ranking API for my partner Streamdata.io to help quantify the efficiencies they bring to the table when you proxy an existing JSON web API using their service. I’m evolving an algorithm they have been using for a while, wrapping it in a new API, and applying it across the APIs I’m profiling as part of my API Stack, and the Streamdata.io API Gallery work. I can pass the ranking API any OpenAPI definition, and it will poll and stream the API for 24 hours, and return a set of scores regarding how real time the API is, and what the efficiency gains are when you use Streamdata.io as a proxy for the API. As I do this work, I find myself thinking more deeply about the role that APIs can play in helping make algorithms more transparent, observable, and accountable...

Using Jekyll And OpenAPI To Evolve My API Documentation And Storytelling

16 February 2018
I’m reworking my API Stack work as independent sets of Jekyll collections. Historically I just dumped all APIs.json, and OpenAPIs into the central data folder, and grouped them into folders by company name. Now I am breaking them out into tag based collections, using a similar structure. Further evolving how I document and tell stories using each API. I have been published a single OpenAPI for each platform, but now I’m publishing a separate OpenAPI for each API path–we will see where this goes, it might ultimately end up biting me in the ass. I’m doing this because I want to be able to talk about a single API path, and provide a definition that can be viewed, interpreted, and executed against, independent of the other paths–Jekyll+OpenAPI is helping me accomplish this...

A Really Nice API Application Showcase Over At The Intrinio Market Data API

15 February 2018
I am profiling financial market data APIs currently, and as I’m doing my work profiling APIs, I’m always on the hunt for interesting elements of their API operations that I can showcase for my readers. While looking at the financial market data API from Intrinio, I found that I really, really like their application showcase, which providers a pretty attractive blueprint for how we can showcase what is being develop on top of our APIs. The Intrinio application showcase is just clean looking, and has the bells and whistles you’d expect like categories, search, detail or list view, and detail pages providing you all the information you need about the application, and where you can find tutorials, code, and other relevant resources...

The Importance of the API Path Summary, Description, and Tags in an OpenAPI

15 February 2018
I am creating a lot of OpenAPI definitions right now. Streamdata.io is investing in me pushing forward my API Stack work, where I profile API using OpenAPI, and index their operations using APIs.json. From the resulting indexes, we are building out the Streamdata.io API Gallery, which shows the possibilities of providing streaming APIs on top of existing web APIs available across the landscape. The OpenAPI definitions I’m creating aren’t 100% complete, but they are “good enough” for what we are needing to do with them, and are allowing me to catalog a variety of interesting APIs, and automate the proxying of them using Streamdata.io. I’m finding the most important part of doing this work is making sure there is a rich summary, description, and set of tags for each API...

How Big Or Small Is An API?

15 February 2018
I am working to build out the API Gallery for Streamdata.io, profiling a wide variety of APIs for inclusion in the directory, adding to the wealth of APIs that could be streamed using the service. As I work to build the index, I’m faced with the timeless question regarding, what is an API? Not technically what an API does, but what is an API in the context of helping people discover the API they are looking for. Is Twitter an API, or is the Twitter search/tweets path an API? My answer to this question always distills down to a specific API path, or as some call it an API endpoint. Targeting a specific implementation, use case, or value generated by a single API provider. Like most things in the API sector, words are used interchangeably, and depending on how much experience you have in the business, you will have much finer grained definitions about what something is, or isn’t...

Some Common Features Of An API Application Review Process

15 February 2018
I received a tweet from my friend Kelly Taylor with USDS, asking for any information regarding establishing an “approve access to production data” for developers. He is working on an OAuth + FHIR implementation for the Centers for Medicare and Medicaid Services (CMS) Blue Button API. Establishing a standard approach for on-boarding developers into a production environment always makes sense, as you don’t want to give access to sensitive information without making sure the company, developer, and application has been thoroughly vetted. As I do with my work, I wanted to think through some of the approaches I’ve come across in my research, and share some tips and best practices. The Blue Button API team has a section published regarding how to get your application approved, but I wanted to see if I can expand on, while also helping share this information with other readers...

Code Generation Of OpenAPI (fka Swagger) Still The Prevailing Approach

14 February 2018
Over 50% of the projects I consult on still generate OpenAPI (fka Swagger) from code, rather then the other way around. When I first begin working with any API development group as an advisor, strategist, or governance architect I always ask, “are you using OpenAPI?” Luckily the answer is almost always yes. The challenge is that most of the time they don’t understand the full scope of how to use OpenAPI, and are still opting for the more costly approach–writing code, then generating OpenAPI from annotations. It has been over five years since Jakub Nesetril(@jakubnesetril) of Apiary first decoupled this way of doing API design first, but clearly we still have a significant amount of work when it comes to API definition and design literacy amongst development groups...

The Growing Importance of Github Topics For Your API SEO

14 February 2018
When you are operating an API, you are always looking for new ways to be discovered. I study this aspect of operating APIs from the flip-side–how do I find new APIs, and stay in tune with what APIs are to? Historically we find APIs using ProgrammableWeb, Google, and Twitter, but increasingly Github is where I find the newest, coolest APIs. I do a lot of searching via Github for API related topics, but increasingly Github topics themselves are becoming more valuable within search engine indexes, making them an easy way to uncover interesting APIs. I was profiling the market data API Alpha Vantage today, and one of the things I always do when I am profiling an API, is I conduct a Google, and then secondarily, a Github search for the APIs name...

A Summary Of AWS API Gateway As An API Deployment and Management Solution

14 February 2018
I was providing an overview of Kong, AWS API Gateway, and other solutions for a team I’m advising a couple weeks back. I was just looking to distill down some of the key features, and provide an overview to a large, distributed team. This work lends itself well to publishing here on the blog, so I published an overview of Kong yesterday, and today I wanted to publish the summary of the AWS API Gateway. The API gateway solution from AWS has some overlap with what Kong delivers, but I consider it to be more of an API deployment, as well as an API management gateway. The AWS API Gateway brings API deployment front and center, allowing you to define and deploy APIs that are wired up to your backend (AWS) infrastructure: API Endpoint - a host name of the API...

Your Microservices Effort Will Fail Because You Will Never Decouple Your

14 February 2018
I’m regularly surprised by companies who are doing microservices which are failing to see the need the change organizational culture, and that microservices will be some magic voodoo to fix all their legacy technical debt. That simply decoupling and breaking down the technology, without any re-evaluation of the business and politics behind, will fix everything, and set the company, organizations, institution, or government agency on a more positive trajectory. In coming years, we will continue to hear stories about why microservices do not work, from endless waves or groups who were unable to do the hard work to decouple, and reorganize the operations behind the services they provide. The monolith legacy systems I’m seeing targeted are widely seen as purely technology, which is why it is often labeled as technical debt...

A Summary Of Kong As An API Management Solution

13 February 2018
I was breaking down what the API management solution Kong delivers for a customer of mine, and I figured I’d take what I shared via the team portal, and publish here on the blog. It is an easy way for me to create content, and make my consulting work more transparent here on the blog. I am using Kong as part of several healthcare and financial projects currently, and I am actively employing it to ensure customers are properly managing their APIs. I wasn’t the decision maker on any of these projects when it came to choosing the API management layer, I am just the person who is helping standardize how they are using API services and tooling across the API life cycle for these projects. First, Kong is an open source API management solution with an easy to install community edition, and enterprise level support when needed...

Aggregating Multiple Github Account RSS Feeds Into Single JSON API Feed

13 February 2018
Github is the number one signal in my API world. The activity that occurs via Github is more important than anything I find across Twitter, Facebook, LinkedIn, and other social channels. Commits to repositories and the other social activity that occurs around coding projects is infinitely more valuable, and telling regarding what a company is up to, than the deliberate social media signals blasted out via other channels is. I’m always working to dial in my monitoring of Github using the Github API, but also via the RSS feeds that are present on the public side of the platform. I feel RSS is often overlooked as an API data source, but I find that RSS is not only alive and well in 2018, it is something that is actively used on many platforms...

Having A Developer.[YourDomain] Is Clear Differentiator In The API Game

13 February 2018
I am profiling US, UK, French, and German banks as part of some research I am doing for Streamdata.io. I am profiling how far along in the API journey these banks are, and one clear differentiator for me is whether a bank has a developer.[bankdomain] subdomain setup for their APIs or not. The banks that have a dedicated subdomain for their API operations have a clear lead over those who do not. The domain doesn’t do much all by itself, but it is clear that when a bank can get this decision made, many of the other decisions that need to be made are also happening in tandem. This isn’t unique just to banking. This is something I’ve written about several times over the years, and remains constant after looking at thousands of APIs over the last eight years...

Streaming And Event-Driven Architecture Represents Maturity In The API Journey

13 February 2018
Working with Streamdata.io has forced a shift in how I see the API landscape. When I started working with their proxy I simply saw it about doing API in real time. I was hesitant because not every API had real time needs, so I viewed what they do as just a single tool in my API toolbox. While Server-Sent Events, and proxying JSON APIs is just one tool in my toolbox, like the rest of the tools in my toolbox it forces me to think through what an API does, and understand where it exists in the landscape, and where the API provider exists in their API journey. Something I’m hoping the API providers are also doing, but I enjoy doing from the outside-in as well. Taking any data, content, media, or algorithm and exposing as an API, is a journey...

More Outputs Are Better When It Comes To Establishing An API Observability

12 February 2018
I’ve been evolving an observability ranking for the APIs I track on for a couple years now. I’ve bene using the phrase to describe my API profiling and measurement approach since I first learned about the concept from Stripe. There are many perspectives floating around the space about what observability means in the context of technology, however mine is focused completely on APIs, and is more about communicating with external stakeholders, more than it is just about monitoring of systems. To recap, the Wikipedia definition for observability is: Formally, a system is said to be observable if, for any possible sequence of state and control vectors, the current state can be determined in finite time using only the outputs (this definition is slanted towards the state space representation)...

Labeling Your High Usage APIs and Externalizing API Metrics Within Your API

12 February 2018
I am profiling a number of market data APIs as part of my research with Streamdata.io. As I work my way through the process of profiling APIs I am always looking for other interesting ideas for stories on API Evangelist. One of the things I noticed while profiling Alpha Vantage, was that they highlighted their high usage APIs with prominent, very colorful labels. One of the things I’m working to determine in this round of profiling is how “real time” APIs are, or aren’t, and the high usage label adds another interesting dimension to this work. While reviewing API documentation it is nice to have labels that distinguish APIs from each other. Alpha Vantage has a fairly large number of APIs so it is nice to be able to focus on the ones that are used the most, and are more popular...

Be Clear About Your API Pricing

12 February 2018
I’m profiling a large number of APIs right now, and I am ranking APIs based upon how easy or difficult they are to access. Whether or not an API provide has a business model is part of the ranking, and how clearly articulated the access and pricing is around that model is a critical part of my profiling algorithm. The APIs that end up included in the API gallery I’m developing for Streamdata.io, and available as part of my wider API Stack research will all have to possess easy to articulate access levels. Not all of them will be free, but the ones that cost money will have straightforward pricing that can be articulate in a single sentence–something that seems to be elusive with many of the API providers I am profiling...

A Dedicated Guest Blogger Program For Your API

12 February 2018
I get endless waves of people wanting to “guest post” on API Evangelist. It isn’t something I’m interested in because of the nature of API Evangelist, and that it really is just my own stream of consciousness, and not about selling any particular product or service. However, if you are an API provider, looking for quality content for your blog, having a formal approach to managing guest bloggers might make sense. Sure, you don’t want to accept all the spammy requests that you will get, but with the right process, you could increase the drumbeat around your API, and build relationships with your partners and API consumers. There is an example of this in action at the financial data marketplace Intrinio, with their official blogger program...

You Have to Know Where All Your APIs Are Before You Can Deliver On API

06 February 2018
I wrote an earlier article that basic API design guidelines are your first step towards API governance, but I wanted to introduce another first step you should be taking even before basic API design guides–cataloging all of your APIs. I’m regularly surprised by the number of companies I’m talking with who don’t even know where all of their APIs are. Sometimes, but not always, there is some sort of API directory or catalog in place, but often times it is out of date, and people just aren’t registering their APIs, or following any common approach to delivering APIs within an organization–hence the need for API governance. My recommendation is that even before you start thinking about what your governance will look like, or even mention the word to anyone, you take inventory of what is already happening...

Riot Games Regional API Endpoints

06 February 2018
I’m slowly categorizing all the APIs I find who are offering up some sort regional availability as part of their operations. With the easy of deployment using leading cloud services, it is something I am beginning to see more frequently. However, there is still a wide variety of reasons why an API provider will invest in this aspect of their operations, and I’m looking to understand more about what these motivations are. Sometimes it is because they are serving a global audience, and latency kills the experience, but other times I’m seeing it is more about the maturity of the API provider, and they’ve have such a large user base that they are getting more requests to deliver resources closer to home...

Consistency in Branding Across API Portals

06 February 2018
I recently watched a BBC documentary about the history of the branding used as part of the London Underground. I’m pretty absorbed lately with using public transit as an analogy for complex API implementations, and moving beyond just using subway maps, I thought the branding strategy for the London Underground provided other important lessons for API providers. The BBC documentary went into great detail regarding how much work was put into standardizing the font, branding, and presentation of information for each London Underground, to help reduce confusion, and help riders get where they needed, and making the city operate more efficiently. As I continue to study the world of API documentation, I think we have so much work ahead of us when it comes to standardizing how we present our API portals...

Keeping API Schema Simple For Wider Adoption

06 February 2018
One aspect of my talk at APIDays Paris this last week, included a slide about considering to allow API consumers to negotiate CSV responses from our API. Something that would probably NEVER occur to most API providers, and probably would make many even laugh at me. I’m used to it, and don’t care. While not something that every API provider should be considering, depending on the data you are serving up, and who your target API consumer ares, it is something that might make sense. Allowing for the negotiation of CSV responses represents lowering the bar for API consumption, and widening the audience who can put our APIs to work. I was doing more work around public data recently, and was introduced to an interesting look at some lessons from developing open data standards...

API Quota API, Webhooks, and Server-Sent Events (SSE)

05 February 2018
I am profiling market data APIs as part of my partnership with Streamdata.io. It is a process I enjoy, because it provides me with a number of interesting stories I can tell here on API Evangelist. Many of the APIs I profile just frustrate me, but there are always the gems who are doing interesting things with their APIs, and understand providing APIs, as well as consuming APIs. One API that I’ve been profiling, and I am able to put to use in my work to build a gallery of real time data APIs, was 1Forge. 1Forge provides dead simple APIs for accessing market data, and surprise!! – you can sign up for a key, and begin making API calls within minutes. It might not sound like that big of a deal, but after going through 25+ APIs, I only have about 5 API keys...

The More We Know About You The More API Access You Get

05 February 2018
I’ve been trash talking APIs that identify me as part of some sort of sales funnel, and automate the decision around whether or not I get access to their API. My beef isn’t with API providers profiling me and making decisions about how much access I get, it is about them limiting profiles making it so I do not get access to their APIs at all. Their narrow definitions of the type of API consumers they are seeking does not include me, even though I have thousands of regular readers of my blog who do fit their profile. In the end, it is their loss, not mine, that they do not let me in, but the topic is still something I feel should be discussed out in the open, hopefully expanding the profile definitions for some API providers who may not have considered the bigger picture...

Learning About The Headers Used for gRPC over HTTP/2

05 February 2018
I am learning more about gRPC and HTTP/2, as part of the recent expansion of my API toolbox. I’m not a huge fan of Protocol Buffers, however I do get the performance gain they introduce, but I am very interested in learning more about how HTTP/2 is being used as a transport. While I’ve been studying how websockets, Kafka, MQTT, and other protocols have left the boundaries of HTTP and are embracing the performance gains available in the pure TCP realm, I’m more intrigued by the next generation of HTTP as a transport. Part of my learning process is all about understanding the headers available to us in the HTTP/2 realm. I’ve been learning more about the next generation HTTP headers from the gRPC Github repository which provides details on the request and response headers in play...

I Appreciate The Request To Jump On Phone But I Have Other APIs To Test Drive

05 February 2018
Streamdata.io is investing in my API Stack work as we build out their API Gallery of valuable data streaming APIs. I’m powering through hundreds of APIs and using my approach to profiling APIs that I have been developing over the last eight years of operating API Evangelist. I have a large number of APIs to get through, so I don’t have a lot of time to spend on each API. I am quickly profiling and ranking them to quickly identify which one’s are worth my time. While there are many elements that get in the way of me actually being able to obtain an API key and begin using an API, one of the more frustrating elements when API providers require me to jump on the phone with them before I can test drive any APIs...

API Is Not Just REST

03 February 2018
This is one of my talks from APIDays Paris 2018. Here is the abstract: The modern API toolbox includes a variety of standards and methodologies, which centers around REST, but also includes Hypermedia, GraphQL, real time streaming, event-driven architecture , and gRPC. API design has pushed beyond just basic access to data, and also can be about querying complex data structures, providing experience rich APIs, real-time data streams with Kafka and other standards, as well as also leveraging the latest algorithms and providing access to machine learning models. The biggest mistake any company, organization, or government agency can do is limit their API toolbox to be just about REST. Learn about a robust and modern API toolbox from the API Evangelist, Kin Lane...

A Regulatory Subway Map For PSD2

03 February 2018
This is one of my talks from APIDays Paris 2018. Here is the abstract: Understanding the PSD2 regulations unfolding for the banking industry is a daunting challenge for banks, aggregators, and regulators, let alone when you are an average user, journalist, or analyst trying to make sense of things. As the API Evangelist I have used a common approach to mapping out transit systems using the universally recognized subway map introduced by Harry Beck in London in the early 20th century. I’m taking this mapping technique and applying it to the PSD2 specification, helping provide a visual, and interactive way to navigating this new regulatory world unfolding in Europe. Join me for an exploration of API regulations in the banking industry, and how we can use a subway and transit map to help us quickly understand the complexities of PSD2, and learn what takes to get up and running with this new definition for the API economy...

Shifting Gears Between the Technology and Politics of APIs

26 January 2018
I’ve been working on two talks for API Days in Paris next week. These talks are at two opposite ends of the API spectrum for me. The first one, API Is Not Just REST, is rooted in the technology of APIs, but then touches lightly on the business and politics of APIs. The second one, a regulatory subway map for PSD2, is all about the politics of APIs, but then touches lightly on the business and technology of APIs. I have the outlines for both talks done, and I’m working on the narrative and slides for each, along the way I’m really caught by how different each end of the spectrum are, and require me to use a different part of my brain–something I think really defines the yin and yang of APIs...

Where Am I In The Sales Funnel For Your API?

24 January 2018
I’m signing up for a large number of new APIs lately as part of a project I am working on. It is pretty normal for me to sign up for a couple new APIs a week, or 10-20 within a month, but right now I’m signing up for hundreds, setting up an application and getting keys for each service. I’ll share more about what I’m working on in future stories, but I wanted to talk more about the on-boarding practices of some of these APIs. It is pretty clear from the on-boarding processes that I don’t rank very high in some of these API provider’s sales funnels, making me not deserving of self-service access, or even a sales call–which is a separate topic I will talk about in a future post...

Helping Define Stream(Line)Data.io As More Than Just Real Time Streaming

24 January 2018
One aspect of my partnership with Streamdata.io is about helping define what it is that Streamdata.io does–internally, and externally. When I use any API technology I always immerse myself in what it does, and understand every detail regarding the value it delivers, and I work to tell stories about this. This process helps me refine not just how I talk about the products and services, but also helps influence the road map for what the products and services deliver. As I get intimate with what Streamdata.io delivers, I’m beginning to push forward how I talk about the company. The first thoughts you have when you hear the name Streamdata.io, and learn about how you can proxy any existing JSON API, and begin delivering responses via Server-Sent Events (SSE) and JSON Patch, are all about streaming and real time...

I Want to Be Able to POST and PUT and Receive Credits on My API Bill

24 January 2018
I’ve been thinking about the potential for measuring value exchange at the API management level a lot more lately, and while I’m working on a project to profile banks that are needing to comply with the PSD2 regulations in Europe, I’m thinking about the missed opportunities for the API providers I’m using to fuel my research to leverage the value I’m generating. I’m using a variety of data enrichment APIs for helping add to the contact data, corporate profiles, images, documents, patents, and other valuable data to what I’m doing as part of my wider research into the API space. While these APIs have valuable services that I am paying for, all of the APIs are just using one HTTP verb–GET...

The Role of European Banking Authority (EBA) When It Comes To PSD2

23 January 2018
As part of my continued effort to break down the Payment Services Directive 2 (PSD2) in Europe, and develop my awareness of how the regulations are intended, as well as the reality on the ground within the industry, I am working to map out all of the players involved. This post is about understanding the role of the European Banking Authority (EBA), and clearly understanding when and where they come into the conversation. First, what is the European Banking Authority (EBA)? They are the regulatory agency for the European Union, who is in charge of conducting stress tests on European banks and increasing transparency in the European financial system and identifying weaknesses in banks’ capital structures...

Key Points From The Payment Services Directive 2 (PSD2)

22 January 2018
I’m immersed in studying the Payment Services Directive 2 (PSD2) in Europe, which includes an API definition to help enable the interoperability they are looking to achieve as part of the regulation. I’m working to break down the directive into bit such chunks to help be digest, and understand exactly what it does. The PSD2 laws seeks to improve the existing EU rules for electronic payments (hence the 2), and takes into account emerging approaches to payment services, such as Internet and mobile payments, with APIs at the hear. The directive sets out rules concerning: strict security requirements for electronic payments and the protection of consumers’ financial data, guaranteeing safe authentication and reducing the risk of fraud the transparency of conditions and information requirements for payment services the rights and obligations of users and providers of payment services Additionally, “the directive is complemented by Regulation (EU) 2015/751 which puts a cap on interchange fees charged between banks for card-based transactions...

AWS API Gateway OpenAPI Vendor Extensions

19 January 2018
I was doing some work on the AWS API Gateway, and as I was going through their API documentation I found some of the OpenAPI vendor extensions they use as part of operations. These vendor extensions show up in the OpenAPI you export for any API, and reflect how AWS has extended the OpenAPI specification, making sure it does what they need it to do as part of AWS API Gateway operations. AWS has 20 separate OpenAPI vendor extensions as part of the OpenAPI specification for any API you manage using their gateway solution: x-amazon-apigateway-any-method - Specifies the Swagger Operation Object for the API Gateway catch-all ANY method in a Swagger Path Item Object. This object can exist alongside other Operation objects and will catch any HTTP method that was not explicitly declared...

A Health Check Response Format for HTTP APIs

19 January 2018
My friend Irakli Nadareishvili, has published a new health check response format for HTTP APIs that I wanted to make sure was documented as part of my research. The way I do this is write a blog post, forever sealing this work in time, and adding it to the public record that is my API Evangelist brain. Since I use my blog as a reference when writing white papers, guides, blueprints, policies, and other aspects of my work, I need as many references to usable standards like this. I am going to just share the introduction from Irakli’s draft, as it says it all: The vast majority of modern APIs driving data to web and mobile applications use HTTP [RFC7230] as a transport protocol. The health and uptime of these APIs determine availability of the applications themselves...

Developing a Microservice to Orchestrate Long Running Background Server-Sent

19 January 2018
I am working to understand the value that Streamdata.io brings to the table, and one of the tools I am developing is a set of APIs to help me measure the difference in data received for normal API calls versus when they are proxied with Streamdata.io using Server-Sent Events (SSE) and JSON Patch. Creating an API to poll any 3rd party API I plug in is pretty easy and straightforward, but setting up a server setup to operate long running Server-Sent Events (SSE), managing for failure and keeping an eye on the results takes a little more consideration. Doing it browser side is easy, but server side removes the human aspect of the equation, which starts and stops the process. This post is just meant to just outline what I’m looking to build, and act as a set of project requirements for what I’m going to develop–it isn’t a guide to building it...

Docker Engine API Has OpenAPI Download At Top Of Their API Docs

18 January 2018
I am a big fan API providers taking ownership of their OpenAPI definition, which enables API consumers to download a complete OpenAPI then import into any client tooling like Postman, using it to generate client SDKs, and getting up to speed regarding the surface area of an API. This is why I like to showcase API providers I come across who do this well, and occasionally shame API providers who don’t do it, and demonstrate to their consumers that they don’t really understand what OpenAPI definitions are all about. This week I am showcasing an API provider who does it well. I was on the hunt for an OpenAPI of the Docker Engine API, for use in a project I am consulting on, and was please to find that they have a button to download the OpenAPI for each version of the Docker Engine API right at the top of the page...

Five APIs to Guide You on Your Way to the Data Dark Side

17 January 2018
I was integrating with the Clearbit API, doing some enrichment of the API providers I track on, and I found their API stack pretty interesting. I’m just using the enrichment API, which allows me to pass it a URL, and it gives me back a bunch of intelligence on the organization behind. I’ve added a bookmarklet to my browser, which allows me to push it, and the enriched data goes directly into my CRM system. Delivering what it the title says it does–enrichment. Next up, I’m going to be using the Clearbit Discovery API to find some potentially new companies who are doing APIs in specific industries. As I head over the to the docs for the API, I notice the other three APIs, and I feel like they reflect the five stages of transition to the data intelligence dark side...

API Management and the Measurement of Value Exchanged

17 January 2018
The concept of API management has been around for a decade now, and is something that is now part of the fabric of the cloud with services like AWS API Gateway. API management is about requiring all consumers of any API resource to sign up for any API access, obtain a set of keys that identify who they are, and pass these keys in with each API call they make from any application. Since every API call is logged, and every API call possesses these keys, it opens up the ability to understand exactly how your APIs are being used through reporting and analytics packages which come with all modern API management available today. This is the fundamentals of API management, allowing us to understand who is accessing our digital resources, and how they are putting them to use–in real time...

API Transit Basics: Deprecation

17 January 2018
This is a series of stories I’m doing as part of my API Transit work, trying to map out a simple journey that some of my clients can take to rethink some of the basics of their API strategy. I’m using a subway map visual, and experience to help map out the journey, which I’m calling API transit–leveraging the verb form of transit, to describe what every API should go through. This is a simple one. All APIs will eventually need to be deprecated. This is how you avoid legacy systems that have been up for over decades. Make sure the life span of each service is discussed as part of its conception, and put some details out about the expected timeline for its existence. Even if this becomes an unknown, at least you thought about it, and hopefully discussed it with others...

Breaking Down The Value Of Real Time APIs

17 January 2018
I am working to evolve an algorithm for Streamdata.io that helps measure the benefits of their streaming service. There are a couple layers to what they offer as a company, but as I dive into this algorithm, there are also multiple dimensions to what we all perceive as real time, and adding more complexity to the discussion, it is something that can significantly shift from industry to industry. The Streamdata.io team was working to productize this algorithm for quantifying the value their service delivers, but I wanted to take some time to break it down, lay it out on the workbench and think about it before they moved to far down this path. Ok. To help me get my brain going, I wanted to work my way through the dictionary sites, exploring what is real time? Real time often seems to describe a human rather than a machine sense of time...

API Transit Basics: Training

16 January 2018
This is a series of stories I’m doing as part of my API Transit work, trying to map out a simple journey that some of my clients can take to rethink some of the basics of their API strategy. I’m using a subway map visual, and experience to help map out the journey, which I’m calling API transit–leveraging the verb form of transit, to describe what every API should go through. Think of support as a reactive area, while training will be the proactive area of the API life cycle. Ensuring there is a wealth of up to date material for API developers and consumers across all stops along the API life cycle. Investing in internal, and partner capacity when it comes to the fundamentals of APIs, as well as the finer details of each stop along the API life cycle, and CI/CD pipelines will pay off big time down the road...

Transit Authorities Need to Understand that API Management Means More Control

16 January 2018
As I look through the developer, data, and API portals of transit authorities in cities around the United States, one thing is clear–they are all underfunded, understaffed, and not a priority. This is something that will have to change if transit authorities are expected to survive, let alone thrive in a digital world. I’m working on a series of white papers as part of my partnership with Streamdata.io, on transit data, and the monetization of public data. I’ll be writing more on this subject as part of this work, but I needed to start working through my ideas, and begin crafting my narrative around how transit authorities can generate much needed revenue and compete in this digital world...

Moving Beyond A Single API Developer Portal

16 January 2018
I am working with a number of different groups who are using developer portals in some very different ways once they have moved beyond the concept that API developer portals are just for use in the public domain. With the introduction of the static site shift in the CMS landscape, and the introduction of Jekyll and Github Pages as part of the Github project workflow, the concept of the API developer portal is beginning to mean a lot of different things, depending on what the project objective is. An API portal is becoming something that can reflect a specific project, or group, and isn’t something that always has a public URL. Here are just a few of the ways in which I’m seeing portals being wielded as part of API operations...

The Value of Historical Transit Data When it Comes to Machine Learning

16 January 2018
I’m working through the different ways that transit authorities can generate more revenue from their data using APIs as part of my work with Streamdata.io. Making data streaming and truly more real time is the obvious goal of this research, but Streamdata.io is invested in transit authorities take more control over their data resources, and use APIs to generate revenue at a time when they need all the revenue they can possible get their hands on. One overlap in the projects I’m working on with Streamdata.io is where transit data intersects with machine learning, and artificial intelligence. I’m not sure what transit authorities are doing with their historical data, but I know that it isn’t available via their APIs, and developer portals...

API Transit Basics: Support

16 January 2018
This is a series of stories I’m doing as part of my API Transit work, trying to map out a simple journey that some of my clients can take to rethink some of the basics of their API strategy. I’m using a subway map visual, and experience to help map out the journey, which I’m calling API transit–leveraging the verb form of transit, to describe what every API should go through. Beyond communication, make sure there is adequate support across API teams, and the services, tooling, and processes involved with operations. If an API goes unsupported, it might as well not exist at all, making standardized, comprehensive support practices essential. Every API should have an owner, with a contact information published as part of all API definitions...

Providing a Guest API Key

16 January 2018
I’m spending time immersed in the world of transit data and APIs lately, and found a simple, yet useful approach to helping onboard developers over at the Washington Metropolitan Area Transit Authority (WMATA) API. When you you click on their products page (not sure why they use this name), you get a guest API key which allows you try out the API, and kick the tires. Of course, you can’t use the key in production applications, as it is rate limited and can change at any time, but the concept is simple, and provides an example which other API providers might want to consider. In my days as the API Evangelist I’ve seen API providers do this in a variety of ways, by providing sample API URLs complete with an API key, and by embedding a key in the OpenAPI definition, so that the interactive documentation picks up the key and will allow developers to make live, interactive API calls–to name a few...

API Transit Basics: Communication

15 January 2018
This is a series of stories I’m doing as part of my API Transit work, trying to map out a simple journey that some of my clients can take to rethink some of the basics of their API strategy. I’m using a subway map visual, and experience to help map out the journey, which I’m calling API transit–leveraging the verb form of transit, to describe what every API should go through. Moving further towards the human side of this API transit journey, I’d like to focus on one of the areas that I see cause the failure and stagnation of many API operations–basic communications. A lack of communication, and one way communication are the most common contributors to APIs not reaching their intended audience, and establishing much needed feedback loops that contribute to the API road map...

Can I Resell Your API?

15 January 2018
Everyone wants their API to be used. We all suffer from “if we build it, they will come” syndrome in the world of APIs. If we craft a simple, useful API, developers will flock to it and integrate it into their applications. However, if you operate an API, you know that getting the attention of developers, and standing out amongst the growing number of APIs is easier said than done. Even if your API truly does bring the value you envision to the table, getting people to discover this value, and invest the time into integrating it into the platforms, products, and services takes a significant amount of work–requiring that you remove all possible obstacles and friction from any possible integration opportunity...

API Transit Basics: Security

15 January 2018
This is a series of stories I’m doing as part of my API Transit work, trying to map out a simple journey that some of my clients can take to rethink some of the basics of their API strategy. I’m using a subway map visual, and experience to help map out the journey, which I’m calling API transit–leveraging the verb form of transit, to describe what every API should go through. Hopefully you already have your own security practices in place, with the ability to scan for vulnerabilities, and understand where security problems might exist. If you do, I’m guessing you probably already have procedures and protocols around reporting, and handling security problems across teams. Ideally, your API security practices are more about prevention than they are about responding to a crisis, but your overall strategy should have plans in place for addressing both ends of the spectrum...

An Organized Approach to OpenAPI Vendor Extensions Across API Teams

15 January 2018
One of aspects of a project I’ve been assisting with recently involves helping define, implement, and organize the usage of OpenAPI vendor extensions across a distributed microservice development team. When I first began advising this group, I introduced them to the concept of extending the OpenAPI definition using x-extension format, expanding the teams approach to how they use the OpenAPI specification. They hadn’t heard that you can extend OpenAPI beyond what the specification brings to the table, allowing them to make it deliver exactly what they needed. Within this project each microservice exists in its own Github repository, with an OpenAPI definition available in the root, defining the surface area of the API...

Orchestrating API Integration, Consumption, and Collaboration with the Postman

12 January 2018
You hear me say it all the time–if you are selling services and tooling to the API sector, you should have an API. In support of this way of thinking I like to highlight the API service providers I work with who follow this philosophy, and today’s example is from (Postman](https://getpostman.com). If you aren’t familiar with Postman, I recommend getting acquainted. It is an indispensable tool for integrating, consuming, and collaborating around the APIs you depend on, and are developing. Postman is essential to working with APIs in 2018, no matter whether you are developing them, or integrating with 3rd party APIs. Further amplifying the usefulness of Postman as a client tool, the Postman API reflects the heart of what Postman does as not just a client, but a complete life cycle tool...

API Life Cycle Basics: Testing

12 January 2018
Every API should be tested to ensure it delivers what is expected of it. All code being deployed should meet required unit and code tests, but increasingly API testing is adding another layer of assurance to existing build processes, even going so far as halting CI/CD workflows if tests fail. API testing is another area where API definitions are delivering, allowing tests to be built from existing artifacts, and allowing detailed assertions to be associated with tests to add to and evolve the existing definitions. API testing has grown over the last couple of years to include a variety of open source solutions, as well as cloud service providers. Most of the quality solutions allow you to import your OpenAPI, and automate the testing via APIs...

"API Transit Basics: SDKs\t"

12 January 2018
Software Development Kits (SDKs), and code libraries in a variety of programming languages have always been a hallmark of API operations. Some API pundits feel that SDKs aren’t worth the effort to maintain, and keep in development alongside the rest of API operations, while others have done well delivering robust SDKs that span very valuable API stacks–consider the AWS JavaScript SDK as an example. Amidst this debate, SDKs continue to maintain their presence, and even have been evolving to support a more continuous integration (CI) and continuous deployment (CD) approach to delivering APIs and the applications that depend on them. Supporting SDKs in a variety of programming languages can be difficult for some API providers...

AWS Has Head Start Helping Navigate Regulatory Compliance In The Cloud

12 January 2018
I’m providing API guidance on a project being delivered to a government agency, as part of my Skylight partnership, and found myself spending more time looking around the AWS compliance department. You can find details on certifications, regulations, laws, and frameworks ranging from HIPPA and FERPA to FedRAMP, so that it can be used by federal government agencies in the United States, and other countries. You can find a list of services that are in scope, and track on their progress when it comes to compliance across this complex web of compliance rules. I’ve been primarily tracking on the progress of the AWS API Gateway which is currently in progress when it comes to FedRAMP compliance...

API Life Cycle Basics: Clients

11 January 2018
I broke this area of my research into a separate stops a couple years back, as I saw several new types of service providers emerging to provide a new type of web-based API client. These new tools allowed you to consume, collaborate, and put APIs to use without writing any code. I knew that this shift was going to be significant, even though it hasn’t played out as I expected, with most of the providers disappearing, or being acquired, and leaving just a handful of solutions that we see today. These new web API clients allow for authentication, and the ability to quickly copy and paste API urls, or the importing of API definitions to begin making requests, and seeing responses for targeted aPIs...

The Metropolitan Transportation Authority (MTA) Bus Time API Supports Service

11 January 2018
The General Transit Feed Specification (GTFS) format for providing access to transit data has dominated the landscape for most of the time I have been researching transit data and APIs over the last couple of weeks. A dominance led by Google and their Google Maps, who is the primary entity behind GTFS. However the tech team at Streamdata.io brought it to my attention the other day that the Metropolitan Transportation Authority (MTA) Bus Time API Supports Service Interface for Real Time Information (SIRI), another standard out of Europe. I think MTA’s introduction to Siri, and the story behind their decision tells a significant tale about how standards are viewed. According to the MTA, “SIRI (Service Interface for Real Time Information) is a standard covering a wide range of types of real-time information for public transportation...

API Life Cycle Basics: Documentation

11 January 2018
API documentation is the number one pain point for developers trying to understand what is going on with an API, as they work to get up and running consuming the resources they possess. From many discussions I’ve had with API providers it is also a pretty big pain point for many API developers when it comes to trying to keep up to date, and delivering value to consumers. Thankfully API documentation has been being driven by API definitions like OpenAPI for a while, helping keep things up date and in sync with changes going on behind the scenes. The challenge for many groups who are only doing OpenAPI to produce documentation, is that if the OpenAPI isn’t used across the API life cycle, it will often become forgotten, recreating that timeless challenge with API documentation...

OpenAPI Will Help You Get Your API House In Order

11 January 2018
I wrote a piece previously about Consul not supporting Swagger documentation at this time, and the API provider and consumer impact of this decision. I’m going to continue picking on Consul with another API definition story, because they are forcing me to hand-craft my own OpenAPI. If I just had to learn about the API, and load the OpenAPI (fka Swagger) definition into my postman, publish to the repo for the project, and import into other tooling I’m using, I wouldn’t be so critical. However, since I’m having to take their static, and often incomplete documentation, and generate an OpenAPI for my project, I’m going to vent some about their API and schema design, and they short-sighted view of OpenAPI (cough, cough fka Swagger)...

Working With General Transit Feed Specification(GTFS) Realtime Data

11 January 2018
I’ve been diving into the world of transit data, and learning more about GTFS and GTFS Realtime, two of the leading specifications for providing access to static and real time transit data. I’ve been able to take the static GTFS data and quickly render as APIs, using the zipped up CSV files provided. Next on my list I wanted to be able to work with GTFS Realtime data, as this is where the data is that changes much more often, and ultimately is more valuable in applications and to consumers. Google has developed a nice suite of GTFS Realtime bindings in a variety of programming languages, including .NET, Java, JavaScript / Node.js, PHP, Python, Ruby, and Golang. I went with the PHP bindings, which interestingly enough is the only one in its own Github repository...

How Do We Keep Teams From Being Defensive With Resources When Doing APIs?

10 January 2018
I was talking with the IRS about their internal API strategy before Christmas, reviewing the teams current proposal before they pitched in across teams. One of the topics that came up, which I thought was interesting, was about how to prevent some teams from taking up a defensive stances around their resources when you are trying to level the playing field across groups using APIs and microservices. They had expressed concern that some groups just didn’t see APIs as a benefit, and in some cases perceived them as a threat to their current position within the agency. This is something I see at almost EVERY SINGLE organization I work with. Most technical groups who have established control over some valuable data, content, or other digital resource, have entrenched themselves, and become resistant to change...

API Life Cycle Basics: Portal

10 January 2018
A coherent strategy to delivering and operating API portals is something that gets lost in a number of the API operations I am asked to review. It is also one of the more interesting aspects of the successful strategies I track on, something that when done right, can become a vibrant source of information, and when done wrong, can make an API a ghost town, and something people back away from when finding. As part of my research I think a lot about how API portals can be used as part of each APIs lifecycle, as well as at the aggregate levels across teams, within groups, between partners, and the public. The most common form of the API portal is the classic public developer portal you find with Twitter, Twilio, Facebook, and other leading API pioneers...

Building An API Partner Program For Streamdata.io

10 January 2018
I am working with Streamdata.io on a number of fronts when it comes to our partnership in 2018. One of the areas I’m helping them build, is the partner program around their API service. I’m taking what I’ve learned from studying the partner programs of other leading APIs, and I am pulling it together into coherent strategy that Streamdata.io can put to work over time. Like any other area of operations, we are going to start small, and move forward incrementally, making sure we are doing this in a sensible, and pragmatic way. First up, are the basics. What are we trying to accomplish with the Streamdata.io partner program. I want to have a simple and concise answer to what their partner program does, and is designed to accomplish...

API Life Cycle Basics: DNS

10 January 2018
DNS is one of those shadowy things that tends to be managed by a select few wizards, and the rest of an organization doesn’t have much knowledge, awareness, or access at this level. APIs has shifted this reality for me, and is something I’m also seeing at organizations who are adopting a microservices, and devops approach to getting things done. DNS should be a first class citizen in the API toolbox, allowing for well planned deployments supporting a variety of services, but also allow for logging, orchestration, and most importantly security, at the frontline of our API operations. There are some basics I wanted to introduce to my readers when it comes to DNS for their API operations, but I also wanted to shine a light on where the DNS space is headed because of APIs...

Some Of The Thinking Behind The Protocols Used By Kafka

10 January 2018
I’ve been studying the overall Apache Stack a lot lately, with an emphasis on Kafka. I’m trying to understand what the future of APIs will hold, and where the leading edge of real time, event-driven architecture is at these days. I’m going through the protocol page for Kafka, learning about exactly how they move data around, and found their answers behind the decisions they’ve made along the way in deciding what protocols they chose to use were very interesting. All the way at the bottom of the Kafka protocol page you can find the following “Some Common Philosophical Questions”, providing some interesting backstory on the decisions behind the very popular platform. Some people have asked why we don’t use HTTP...

We Are Not Supporting OpenAPI (fka Swagger) As We Already Published Our Docs

10 January 2018
I was looking for an OpenAPI for the Consul API to use in a project I’m working on. I have a few tricks for finding OpenAPI out in the wild, which always starts with looking over at APIs.guru, then secondarily Githubbing it (are we to verb status yet?). From a search on Github I came across an issue on the Github repo for Hashicorp’s Consul, which asked for “improved API documentation”, a Hashicorp employee ultimately responded with “we just finished a revamp of the API docs and we don’t have plans to support Swagger at this time.”. Highlighting the continued misconception of what is “OpenAPI”, what it is used for, and how important it can be to not just providing an API, but also consuming it...

API Life Cycle Basics: API Logging

09 January 2018
Logging has always been in the background of other stops along the API lifecycle, most notably the API management layer. However increasingly I am recommending pulling logging out of API management, and making it a first-class citizen, ensuring that the logging of all systems across the API lifecycle are aggregated, and accessible, allowing them to be accessed alongside other resources. Almost every stop in this basics of an API life cycle series will have its own logging layer, providing an opportunity to better understand each stop, but also side by side as part of the bigger picture. There are some clear leaders when it comes to logging, searching, and analyzing large volumes of data generated across API operations...

A Blueprint For An Augmented Transit API

09 January 2018
I’m working through research on the world of transit APIs as part of my partnership with Streamdata.io. From what I’ve gathered so far, the world of transit data and APIs is quite a mess, and there is a pretty significant opportunity to improve upon what already exists. In the course of my research, I stumbled across MetroHero, which is an application and API provider that operates on top of the Washington Metropolitan Area Transit Authority data and API feeds. I’m still working my way through their website, services, APIs, as well as talking with their team, but I’m fascinated with what they are doing, and wanted to think a little more about it before I talk with them this week. While their approach to improving upon WMATA applications is interesting, I think applying this way of thought to a government API is more interesting (surprise)...

API Life Cycle Basics: API Management

09 January 2018
The need to manage APIs is one of the older aspects of doing business with web APIs. Beginning around 2006, then maturing, and being baked into the cloud and markets by 2016. Whether it is through an management gateway that proxies existing APIs, natively as part of the gateway that is used to deploy the APIs themselves, or as a connective layer within the code, API management is all about authenticating, metering, logging, analyzing, reporting, and even billing against API consumption. This landscape has significantly shifted lately, with the bottom end of the market becoming more competitive, but luckily there are enough open source and cloud solutions available to get the job done. Over the last decade API management providers have collectively defined some common approaches to getting business done using web APIs...

Generating Revenue From The Support Of Public Data Using APIs

09 January 2018
I’m exploring the different ways that public data access via APIs can be invested in, even with the opportunity for generating revenue, but without charging access to the data itself. I want public data to remain accessible, but in reality it costs money to provide access to public data, to refine, and evolve it. This is meant to be an exploration of how public data is invested in, not how you lock up public data, so please read everything before commenting, as every time I write about this subject, there are folks who blindly declare that ALL public data has to be free, no matter what. I agree (mostly), but there has to be commercial monetization opportunities around public data, otherwise it will never evolve, improve, be enriched, and in some cases available at all...

The Data Behind The Washington Post Story On Police Shootings in 2017

09 January 2018
I was getting ready to write my usual, “wish there was actual data behind this story about a database” story, while reading the Fatal Force story in the Washington Post, and then I saw the link! Fatal Force, 987 people have been shot and killed by police in 2017. Read about our methodology. Download the data. I am so very happy to see this. An actual prominent link to a machine readable version of the data, published on Github–this should be the default for ALL data journalism in this era. I see story after story reference the data behind, without providing any links to the data. As a database professional this practice drives me insane. Every single story that provides data driven visualizations, statistics, analysis, tables, or any other derivative from data journalism, should provide a link to the Github repository which contains at least CSV representations of the data, if not JSON...

The Child Welfare Digital Services (CWDS) Certification, Approval, and

09 January 2018
My partner Chris Cairns(@cscairns) over at Skylight sent me a link to the Child Welfare Digital Services (CWDS) Certification, Approval, and Licensing Services (CALS) API on Github the other day. The API isn’t your traditional public API, but shows what is possible when it comes to APIs at government agencies. The group behind the API has published their Digital Service Development Standards, and is actively using a Github Wiki to layout the API strategy for the organization. To give some backround, the Child Welfare Digital Services (CWDS) is for “state and county workers who ensure that safe and quality licensed facilities and approved homes are available for the children and nonminor dependents who need them, the CALS Digital Service Team will facilitate activities related to ensuring that licensed facilities, approved homes and associated adults meet and maintain required standards...

Seeing Reflections From The Past Rippling In The API Pool When I Translated

08 January 2018
I was looking for the API definition and schema for the Service Interface for Real Time Information (SIRI) standard, but all they have were WSDL and XSDs. I am working with the Metropolitan Transit Authorities (MTA) SIRI feed, which returns JSON, and I wanted to have a JSON schema reflecting the responses I was working with. So I took the WSDLs and converted them to OpenAPI using the API Transformer, which kind of felt like that scene in the matrix where the world around him is beginning to turn to liquid as he pokes at it, right before he exits the matrix. I regularly get the emails and tweets from folks telling me “we’ve done all this before”, when I talk about OpenAPI. I’m fully aware that we have, and have even written a few stories about it...

API Life Cycle Basics: Gateway

08 January 2018
API gateways have long played a role in providing access to backend resources via web services and APIs. This is how web services have historically been deployed, but it is also how modern web APIs are being managed. Providing a gateway that you can stand up in front of existing web APIs, and proxy them through a single gateway that authenticates, logs, and manages the traffic that comes in and out. There are many management characteristics of API gateways, but I want to provide a stop along the API lifecycle that allows us to think about the API deployment, as well as the API management aspects of delivering APIs. I wanted to separate out the API gateway discussion from deploy and manage, focusing specifically on the opportunities to deploy one or many gateways, while also looking at it separately as a pattern in service of microservices...

Looking For THE Answer Instead Of Developing An Understanding Of Good API

08 January 2018
I recently worked with a large team on a microservices and API governance training a couple months back, where I saw a repeating pattern that I’ve experienced with other large enterprise groups. They seemed to want the right answers to doing APIs and microservices, instead of developing an understanding of good (or bad) API design, and determining the right way for themselves. The biggest challenge with this perception amongst development groups, is that there is no right answer, or one way of doing APIs and microservices–you need to find the right way forward for your team, and for each project. I get this a lot within large organizations who are just beginning their API journey–just show us the right way of doing it! To which I usually reply with, let’s roll up our sleeves and get to work on one of your services, and we will start showing you have to craft a simple, sensible, yet robust API that meets the needs of the project...

API Life Cycle Basics: Deployment

08 January 2018
There are many ways to deploy an API, making this another confusing stop along the API life cycle for some of my readers. My goal in having this be a separate stop from design, or possibly management, is to help API providers think about where and how they deploy APIs. From my perspective, API deployment might be about which framework and language you choose to deploy in, spanning all the way to where you might deploy it, either on-premise, on-device, or in the cloud. The how and why of deploying your API will play a significant role in determining how stable and consistent you are able to deploy API resources, impacting almost every other stop along the API life cycle. Many API providers still think of API deployment in the context of their internal operations, as opposed to thinking about how they will be put to use...

I Created An OpenAPI For The Hashicorp Consul API

08 January 2018
I was needing an OpenAPI (fka Swagger) definition for the Hashicorp Consul API, so that I could use in a federal government project I’m advising on. We are using the solution for the microservices discovery layer, and I wanted to be able to automate using the Consul API, publish documentation within our project Github, import into Postman across the team, as well as several other aspects of API operations. I’m working to assemble at least a first draft OpenAPI for the entire technology stack we’ve opted to use for this project. First thing I did was Google, “Consul API OpenAPI”, then “Consul API Swagger”, which didn’t yield any results. Then I Githubbed “Consul API Swagger”, and came across a Github Issue where a user had asked for “improved API documentation”...

Understanding Events Across Your API Platform In Real Time

08 January 2018
I spend a lot of time trying to understand and define what is API. With my new partnership with Streamdata.io I’m pushing that work into understanding APIs in real time, and as part of event-driven architecture. As the Streamdata.io team and I work to identify interesting APIs out there that would benefit from streaming using the service, a picture of the real time nature of API platforms begins to emerge. I’m beginning to see all of this as a maturity aspect of API platforms, and those who are further along in their journey, have a better understanding the meaningful events that are occurring via their operations. As part of this research I’ve been studying the Stripe API, looking for aspects of the platform that you could make more real time, and streaming...

API Discovery Is Mostly About You Sharing Stories About The APIs You Use

04 January 2018
I do a lot of thinking about API discovery, and how I can help people find the APIs they need. As part of this thinking I’m always curious why API discovery hasn’t evolved much in the last decade. You know, no Google for APIs. No magical AI, ML, AR, VR, or Blockchain for distributed API mining. As I’m thinking, I ask myself, “how is it that the API Evangelist finds most of his APIs?” Well, word of mouth. Storytelling. People talking about the APIs they are using to solve a real world business problem. That is it! API storytelling is API discovery. If people aren’t talking about your API, it is unlikely it will be found. Sure people still need to be able to Google for solutions, but really that is just Googling, not API discovery...

API Transit Basics: Mocking

04 January 2018
This is a series of stories I’m doing as part of my API Transit work, trying to map out a simple journey that some of my clients can take to rethink some of the basics of their API strategy. I’m using a subway map visual, and experience to help map out the journey, which I’m calling API transit–leveraging the verb form of transit, to describe what every API should go through. One key deficiency I see in organizations that I work with on a regular basis, is the absence of the ability to quickly deploy a mock version of an API. Meaning, the ability to deliver a virtualized instance of the surface area of an API, that will accept requests, and return responses, without writing or generating any existing backend code...

Keeping Things In The Club By Drowning Everyone In API Complexity

04 January 2018
After seven years of doing API Evangelist I have learned a lot about the realities of the technology sector, versus my own beliefs. One of the things that attracted me to web APIs in the first place was the ability to simplify the access to data, content, algorithms, and other resources using a web url. I could get a list of news articles, post a picture, launch a server in the cloud, and many other common business tasks using a simple URL. To me good API design is more about simplicity, than it was ever about REST, or any other dogmatic approach to doing APIs. However, after seven years of doing this, I’m pretty convinced that most folks have very little interest in truly making things simple for anyone...

API Transit Basics: API Design

03 January 2018
This is a series of stories I’m doing as part of my API Transit work, trying to map out a simple journey that some of my clients can take to rethink some of the basics of their API strategy. I’m using a subway map visual, and experience to help map out the journey, which I’m calling API transit–leveraging the verb form of transit, to describe what every API should go through. API design is not just about REST. Sure, a great deal of the focus within this stop along the API journey will be focused on REST, but this is because it is the dominant methodology at this moment in time. API design is about establishing a framework for how you will consistently craft your APIs across teams, whether they are REST, GraphQL, Microservices, or even gRPC...

API Life Cycle Basics: Database

03 January 2018

Alexa Voice Skills Are The Poster Child For Your Enterprise API Efforts

03 January 2018
I was sitting in an IT architectural planning meeting for a large enterprise organization the other day, and one of the presentation from one of the executives contained a complex diagram of their IT infrastructure, with a column to the right showing a simple five step Alexa conversation, asking a specific question from customer. Each question posed as part of the Alexa conversation theoretically accessed a different system, weaving a pretty complex web of IT connections, to enable this simple conversation. This presentation reflects why I feel that Alexa Skills development poses some interesting questions in the API world, and why the platform becomes interesting to so many business users...

The Transit Feed API Is A Nice Blueprint For Your Home Grown API Project

03 January 2018
I look at a lot of APIs. When I land on the home page of an API portal, more often than not I am lost, confused, and unsure of what I need to do to get started. Us developers are very good at complexifying things, and making our APIs implementations as messy as our backends, and the API ideas in our heads. I suffer from this still, and I know what it takes to deliver a simple, useful API experience. It just takes time, resources, as well as knowledge to it properly, and simply. Oh, and caring. You have to care. I am always on the hunt for good examples of simple API implementations that people can emulate, that aren’t the API rockstars like Twilio and Stripe who have crazy amounts of resources at their disposal...

API Transit Basics: API Definitions

03 January 2018
This is a series of stories I’m doing as part of my API Transit work, trying to map out a simple journey that some of my clients can take to rethink some of the basics of their API strategy. I’m using a subway map visual, and experience to help map out the journey, which I’m calling API transit–leveraging the verb form of transit, to describe what every API should go through. Defining an API is the first stop along any API journey. When I say definitions, I’m not just talking about OpenAPI (fka Swagger), and specifically definitions for the surface area of your API. I’m talking about defining your idea, your goals, and the standard aspects of doing business with APIs. By API definitions, I mean having a robust toolbox of definitions for everything that is going into your API operations, from standardized dates and currencies, to common data schema, and yes to making sure there is an active OpenAPI definition for every single one of your APIs...

My Evolving Definition Of A Robust And Diverse API Toolbox

02 January 2018
It is always telling when folks assume I mean REST when I say API. While the web dominates my definition of API, and REST is definitely a leading architectural style, these assumptions always define the people who bring them to the table, more than they ever do me. I’m in the business of studying how people are applying programmatic interfaces using the web. To reflect my research I’ve been evolving a diagram of my toolbox that I’ve been publishing as part of workshops, presentations, and some talks I’m preparing for 2018. It reflects what I’m seeing as the evolving API toolbox that I’m seeing companies working with, and a diversity in which I’m encouraging others to think about more, as we choose to ignore the polarizing forces in the API sector...

Treating All APIs Like They Are Public

02 January 2018
I was talking with the Internal Revenue Service (IRS) about their internal API strategy the week before Christmas, sharing my thoughts on the strategy that they were pitching internally when it comes to the next phase of their API journey. One topic that kept coming up is the firm line of separate between public and private APIs, which you kind of get at an organization like the IRS. It isn’t really the type of organization you want to be vague about this line, making sure everyone understands where an API should be consumed, and where it should not be consumed. Even with that reality, I still made the suggestion that they should be treating ALL APIs like they are public. I clarified by saying you shouldn’t be getting rid of the hard line dictating whether or not an API is internal or external, but if you treat them all like they are public, and act like they are all under threat, you will be better off for it...

The National Transit Database (NTD) Needs To Be An API

02 January 2018
I’ve been looking for sources of transit data as part of some research I’m doing with Streamdata.io. Like most industries I study as part of my API research, it is a mess. There is no single source of truth, lack of robust open source solutions, government PDFs acting as databases, and tech companies extracting as much value as they can, and giving as little in return as they possibly can. Todays frustration centers around the unfortunately common federal government PDF database, or more specifically, the National Transit Database (NTD). In 2017, when you publish something to the web as a “database”, it should be machine readable. There is some valuable data in the agency profile reports for the 800+ transit agencies available in the database, but this information is locked up in PDFs...

API Transit - The Basics

02 January 2018
I have been evolving my approach to mapping out all the stops along my API research, using a subway map approach lately. It has been something I’ve been working on since 2014, and had developed as a keynote talk in 2015. My goal is to be able to lay out simple, as well as increasingly complex aspects of consistently operating an API. Something I’ve historically called the API life cycle, but will work to call API transit in the future. Right now, I have two main approaches to delivering the API Transit maps. 1) API Life Cycle, and 2) API Documentation. The first is about applying consistent practices to API operations, and the second is about understanding API operations as they happen...

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