{"API Evangelist"}

Five Years Of API Evangelist

In July of 2010, I started researching what would be the next step in my career. I was VP of Technology at WebEvents global, and was in charge of the technical side of running conferences for SAP and Google. I enjoyed the work I did, scaling the technology to support the events, using the Amazon Cloud and APIs, but I was not fully satisfied in the events industry. 

I clearly remember spending my Fourth of July weekend researching some possible next steps. Building on my strengths at the time, I looked at what I could do in the cloud computing space. My early research is still even online, forever preserved as a Google Site. The last update to the research was mid half way through July, when after a couple weeks of careful evaluation and contemplating, I saw the core of cloud computing was really about APIs.

I had an epiphany -- APIs were central to the recent social and cloud evolutions in the Internet, and as I looked deeper, I saw that web APIs were also beginning to play a central role in the mobile evolution as well. As I continued my research in July of 2010 I also noticed that everyone was focused on the technical aspects of APIs, discussing, often arguing about the technical merits of REST, and very few people were talking about the business side of successful API efforts.

Through my early research in cloud computing, and ultimately APIs, I had found my focus -- the business of APIs. My partner in crime Audrey Watters (@audreywatters) was also looking for her own direction, and we agreed that if she started Hack Education, I would help her run her server and other IT infrastructure, and if I started API Evangelist, she would help me learn to write, and craft better stories--some of the early stories were actually written or edited by her.

July 2010's research was all about finding my focus, and by August I purchased the domain apievangelist.com, where I would openly share my research, and by October I published my first story, which I think was appropriately titled, the API Economy. The plan was to research the business of APIs, while sharing my research in real-time via the API Evangelist site. Five years later, I am still doing what I originally set out to do, I've just gotten more organized about how I conduct my research, evolved my storytelling voice, and have expanded the focus beyond just the business of APIs, to what I consider to be the politics of APIs.

I couldn't be more happy with the work I've been able to do over the last five years. Something that wouldn't happen without the support of my partners 3Scale, Restlet, and WSO2--THANK YOU!!!! While I do have claustrophobic moments, where I freak out, questioning why the hell I do what I do, in 2015 I can see myself doing this for at least another five years. Who knows though, things could change, and go in a different way, at any point..but at the moment, I think API Evangelist will stick around.

From my current vantage point, the next five years will be focused more on the politics of APIs, continuing my work around the copyright of APIs, API patents, the importance of open API definitions, and advocacy around privacy, transparency, access, data portability, interoperability and security issues. I'll continue to rely on others to innovate around the tech of APIs, shining a light on the best practices, and work to understand how the business of APIs is evolving, as the API economy truly becomes a reality, but I feel the politics of APIs will be the biggest challenges we face in the next five years.

Thank you to all my readers, and people who support what I do. I really enjoy what I do, and from I can tell, there are a number of people, and companies who benefit from what I do, which keeps me going. I need as much help as I can, to make sure the API economy stays secure, accessible, transparent, and truly open for developers, in a way that includes end-users in the conversation, focusing on building healthy API driven platforms, that businesses, organizations, governments, and individuals can depend on.



Building Micro Apps and Tooling On Top Of Your API To Demonstrate The Value Your API Delivers

I was doing one of my regular checkins with my friend Anne Wootton (@annewootton) of Popup Archive today, something we try to do regularly, to share stories about what they are up to in the world of audio and podcast API, and what I am seeing across the voice, audio, video, and wider API landscape. 

Anne was walking me through their latest rollout AudioSear.ch, a full text search & recommendation API for podcasts and radio, that is API driven. One of the endpoints for the AudioSear.ch API allows for searching of people who are involved with the podcasts and radio programs that they are indexing. As we talked, she articulated that in order to help people see the value the AudioSear.ch People API, rather than just telling them about it, they were building micro applications, that demonstrated it.

This may seem obvious too many, but I've made a career out of shining a light on the obvious, and with APIs being such an abstract concept, little ideas like this can go a long ways. In this era of microservices, the concept of micro, portable, simple, and focused goes a long way, and what AudioSear.ch is doing with their people API is something that other API providers should consider as well.

Sometimes, the little things like a demo micro application built on top of your API can be the thing that plants a seed in someones mind about what your API does--a seed that over time could grow into something much, much more. I already advocate for other code related building blocks like SDK, PDKs, and starter projects--maybe I'll add micro apps as a building block and see if I can incite API providers to deploy more of them to support API operations.



Tightening Up The Organizations That Are Included In My API Design Research

I try to go through each of my areas of research as often as I can and update the content, as well as my understanding. Ideally I update the news each week, take a look at the organizations involved once a month, and evaluate the building blocks and tools each quarter. Unfortunately it doesn't always happen as planned, but as a one man operation, I think I do pretty well. 

I just went through my API design research, and adjusted my definition of what I felt needed be listed there. As I move API definitions to their own research area(s), I'm reconsidering what I want to keep an eye on when it comes to API design, and my current definition involves organizations who offer API design editors, either in the cloud or as download. They should allow you to add, edit, and manage the API details, then also provide the ability to import and export using common API definition format(s).

Currently I have nine organizations represented, as part of my API design research:

Apiary Apiary jump-started the modern API design movement, by making API definitions more than just about API documentation, allowing API designers to define APIs in the machine readable API definition format API blueprint, then mock, share, and publish documentation via a cloud platform.    
 
Apigee API Studio Apigee launched their API Studio out of their earlier Apigee-127 product, their work on the Swagger platform and editor, and their BaaS offering. Opening up the ability for developers to design, mock, test and share via their online platform.            
 
APIMATIC When you use APIMATIC to manage SDKs, they provide you with an editor for adding, editing, and deleting the details of each API. When you bundles this with their multi API definition format import and export, the platform quickly becomes an API design tool as well as a platform for generating your SDKs.          
APIMATIC API            
 
deployd Deployd is an open source API design, and deployment platform that allows developers to quickly design, customize, and deploy an API, with supporting application interface via a downloadable app, and command line utilities.        
 
Mashape Mashape provides an API editor, as part of their API management and discovery platform, allowing API providers to add, edit, and manage the details of an API design, while also managing the rest of API operations--from design to discovery and integraiton.      
 
MuleSoft Mulesoft provides a cloud, and open source version of their API design editor, enabling API designers to craft APIs using the RAML API definition format, then publish to notebook, as well as manage through other aspects of the API lifecycle with other Mulesoft systems.    
 
Restlet The Restlet Studio allows you to design APIs, and add, edit, and manage the details via cloud based API editor, import and export in Swagger and RAML, then also generate server, and client side code, as well as interactive documentation.    
 
Sandbox Sandbox provides an environment for users to quickly mock APIs that are generated from common API definition formats like API Blueprint, and Swagger, then deploy, collaboratively build, and debug APIs using an online platform.        
 
Swagger Swagger is a machine readable API definition format that has built a number of tools around the specification, including an open source API design editor that allows you to design, import, and export APIs in JSON and YAML, then also generate server, and client side code, as well as interactive documentation.      
 
 

As I work to refine each of my research areas, it can be hard to draw the line where each projects starts, and ends. I had Readme.io, and Wavemaker on this list, but I really felt they were more in the API management, and API deployment realms, resulting in me drawing the line where I did.

Next I am looking to tackle the API design tooling, which I am looking to organize into groups, as there is kind of a mash-up of different things there now. Hopefully I can break it all into a more coherent breakdown of not just the open tooling, but also open content, and other resources that might help all of us all in our API design journey. 

One thing I have to say after updating the list of organizations on my API design research, is I am impressed how far the services, tooling, and overall API design mindset has come in just two short years. We have more than one editor, with a couple of the implementations being open source--I'd say this is pretty healthy progress. ;-)



The API Design Tooling I Have Included In My Research

I am going through each of my research projects, and tightening things down, now that I have them all driven through my new, master stack of APIs. First up was API design, and the other day I spent time going through the organization I track on as part of my API design research, and today mission was to refine the tooling section.

Previously my tooling page was just an alphabetical list of tools, and I wanted to at least group things in a more meaningful way, reflecting how I break them down in my own monitoring system. So I reworked the publishing to allow me to group the tools by tags, resulting in the following list:

API Blueprint

API Blueprint

 

API Blueprint is a documentation-oriented API description language. A couple of semantic assumptions over the plain Markdown. API Blueprint is perfect for designing your Web API and its comprehensive documentation but also for quick prototyping and collaboration. It is easy to learn and even easier to read – after all it is just a form of plain text. API Blueprint, its parser, and most of its tools are completely open sourced so you don't have to worry about vendor lock-in. This also means you can freely integrate API Blueprint into any type of product, commercial or not.

 


Atom Editor API Blueprint Preview

 

The Atom Editor API Blueprint preview is a plugin for the Atom editor that allows you to render HTML representation of API Blueprint in the right of the current open Atom editor using CTRL-SHIFT-A. This plugin requires Agilo to be installed and available in your path.

 


API Definitions

API Blueprint

 

API Blueprint is a documentation-oriented API description language. A couple of semantic assumptions over the plain Markdown. API Blueprint is perfect for designing your Web API and its comprehensive documentation but also for quick prototyping and collaboration. It is easy to learn and even easier to read – after all it is just a form of plain text. API Blueprint, its parser, and most of its tools are completely open sourced so you don't have to worry about vendor lock-in. This also means you can freely integrate API Blueprint into any type of product, commercial or not.

 


RAML Specification

 

RESTful API Modeling Language (RAML) is a simple and succinct way of describing practically-RESTful APIs. It encourages reuse, enables discovery and pattern-sharing, and aims for merit-based emergence of best practices. The goal is to help our current API ecosystem by solving immediate problems and then encourage ever-better API patterns. RAML is built on broadly-used standards such as YAML and JSON and is a non-proprietary, vendor-neutral open spec.

 


Swagger Specification

 

Swagger is a simple yet robust representation of a RESTful API, with a large ecosystem of API tooling that includes code generation, interactive documentation, and much more. Currently  there are housands of developers supporting Swagger in almost every modern programming language and deployment environment, using the 100% open source software and specification.

 


API Design Editor

Atom Editor API Blueprint Preview

 

The Atom Editor API Blueprint preview is a plugin for the Atom editor that allows you to render HTML representation of API Blueprint in the right of the current open Atom editor using CTRL-SHIFT-A. This plugin requires Agilo to be installed and available in your path.

 


Deployd

 

Deployd is the simplest way to build real-time APIs for web and mobile apps. Ready-made, configurable Resources add common functionality to a Deployd back-end, which can be further customized with JavaScript Events.

 


RAML API Designer

 

API Designer is a standalone/embeddable editor for RAML (RESTful API Modeling Language) written in JavaScript using Angular.JS, which by default, uses an in-browser filesystem stored in HTML5 Localstorage. Mulesoft provides a cloud version of the editor as part of their larger API suite.

 


Swagger Editor

 

Swagger Editor lets you edit API specifications in YAML inside your browser and to preview documentations in real time. Valid Swagger JSON descriptions can then be generated and used with the full Swagger tooling (code generation, documentation, etc).

 


API Design Guide

18F API Standards

 

18F is a technology team inside the US federal government. 18F is very API-focused: our first project was an API for business opportunities. This document captures 18F's view of API best practices and standards. We aim to incorporate as many of them as possible into our work. APIs, like other web applications, vary greatly in implementation and design, depending on the situation and the problem the application is solving.

 


Heroku - API Design Guide

 

Heroku has provide their own set of what they call HTTP+JSON API design practices, which I think describes what we do much better than just web API. The guide is designed for internal and external usage, and looking to provide some consistency in API design, that anyone can follow.

 


Paypal API Design Standards

 

Paypal has developed their own API design standards, providing a common blueprint for their teams to follow, while also transparently sharing with their API community, and the wider API industry to follow.

 


Realtime API Design Guide from Fanout

 

An API Design Guide dedicated to helping you understand the common design approaches, as well as the pros and cons of realtime API design, showcasing the implementations of 16 public real-time APIs--developed by Fanout.io

 


The RESTed NARWHL

 

NARWHL is a framework intended to provide a roadmap for those needing to implement an API using current best practices but flexible enough to grow into the future. This guide contains a set of API design recommendations you can implement today with the confidence that your API will be RESTful (level 3 according to the Richardson Maturity Model) and able to adapt to future iterations while still making it easier for developers to use.

 


UK Government Service Design Manual for APIs

 

Martha Lane Fox report called for government to act as a wholesaler, as well as the retail shop front, for services and content by mandating the development and opening up of Application Programme Interfaces (APIs) to third parties -- this section is a set of guiding principles for exposing a digital service as an API.

 


White House Web API Standards

 

This document provides guidelines and examples for White House Web APIs, encouraging consistency, maintainability, and best practices across applications. White House APIs aim to balance a truly RESTful API interface with a positive developer experience (DX).

 


RAML

RAML Specification

 

RESTful API Modeling Language (RAML) is a simple and succinct way of describing practically-RESTful APIs. It encourages reuse, enables discovery and pattern-sharing, and aims for merit-based emergence of best practices. The goal is to help our current API ecosystem by solving immediate problems and then encourage ever-better API patterns. RAML is built on broadly-used standards such as YAML and JSON and is a non-proprietary, vendor-neutral open spec.

 


Swagger

Swagger Specification

 

Swagger is a simple yet robust representation of a RESTful API, with a large ecosystem of API tooling that includes code generation, interactive documentation, and much more. Currently  there are thousands of developers supporting Swagger in almost every modern programming language and deployment environment, using the 100% open source software and specification.

 


I have other resources I need to add to this list, but each one requires a certain amount of love before its ready to be included. Everything here should be openly licensed, providing essential tools API providers, designers, and architects will need. If there is something that you think should be here, let me know, and I will consider adding it. 

One area I am still working on, is cross linking areas of tooling, potentially with other research areas. For example API definitions has its own evolving area, and Swagger does as well. This is why I wanted to retool and break things down by tags, because some of these tags eventually become other projects, and when I break off a new area, I  want to keep things connected.

Next I'll give the API design building blocks page a little attention, but it was recently overhauled, so I think I am pretty good there. After that, I need to give my paper API a little love, which allows me to aggregate my design research into a white paper. Once I'm done with that I'll quickly go through some of my other core research like API deployment, management, discovery, and beyond.



APIs Will Not Be Suffocated By Oracle and the Courts, It Will Be Done By Each Of You Not Sharing Your API Designs

I just read on Re/Code, that the Supreme Court declined to hear Google's appeal on the Oracle v Google case--prepare for the waves of stories from tech blogs, that this will suffocate the API economy. During the last response to the case by the US Solicitor General, I wrote about how I can't even argue the concept anymore, and nothing has changed for me. 

I just wanted to take the moment to remind everyone that this decision means nothing if we all share our API definitions, in open ways, using machine readable definitions like API Blueprint and Swagger. The disturbing move by Oracle to bring a lawsuit against Google, and the very unaware decision(s) made all the way up to federal level, will NOT bring down the API economy--your inaction will!

If I've learned anything during my time defending APIs, as part of the Oracle v Google case, is that many of you are holding your API designs close to your chest, thinking maybe, just maybe, they are intellectual property we should protect, and can make money on, when we are the next unicorn start-up. You are willing to do this, even at the expense of the success of your APIs, ignoring that it creates huge amounts of friction with developers, and the businesses you are asking to integrate your APIs into their systems.

When you bundle this with the large numbers of folks who don't even understand the difference between an API definition or design, and its code back-end, you end up with a very dangerous, controllable group of folks, who will slowly stifle, and potentially suffocate any momentum we have built with the API economy. It will be these groups of individuals and companies, who will blindly do Oracle's bidding, and make sure any democratizing power APIs had, stays in the hands of the powerful few.

Why would anyone integrate your API definition into their application, if at some point they can be forced to license and pay for the naming, and order of API endpoints that are called? I sure wouldn't. This is why Steve Willmott and I started API Commons, so that we can start sorting out the open API definitions, from the closed ones, and index these API operations using APIs.json, allowing the API economy to filter itself at run-time, leaving closed, potentially dangerous definitions behind.

Please join me in the fight, by helping me define the common API patterns available across the space, as part our the API Stack work--do not let this decision get you down.