{"API Evangelist"}

Slowly Adding The People Layer To The API Evangelist Network

I'm adding a new layer to my monitoring of the API space, what I consider to be the people layer of the API Evangelist network--the actual people who are executing on much of what I talk about, across my research, and storytelling. This is all born out of the network of people I already talk to regularly, to get the stories, and details for the research that I publish regularly.

I have been tracking on many of the doers of the space for a while, behind the scenes, and this is just about exposing a select handful of individuals who can help you with some of the areas I discuss in my research and storytelling.

Up until now, my research has been about showcasing:

  • News
  • Companies
  • Tools

All I’m doing now is exposing some of the people who are doing interesting things as well, and are open to being contacted about their work, and discuss how you can potentially tap their expertise to help you achieve your API objectives. Over the next couple weeks, you will see me start listing individuals who are open to helping out in the core areas I research:

  • API Design
  • API Deployment
  • API Management
  • API Discovery
  • API Integration
  • API Evangelism
  • API Monetization
  • API Security

I already showcase companies in many of these areas, and track on the features, or building blocks employed to deliver products and services they offer, all I’m going to do now is provide more information on individuals who can help execute in these areas as well. Along the way you will also find me showcasing specific companies and tooling as well--API Evangelist partners like 3Scale, WSO2, and Restlet, but also other products I’m personally invested in like APIs.json, and the companies, and tools I use daily like Swagger, API Blueprint, APITools, API Science, and Runscope.

After five years of doing this, I’m trying to understand what scale looks like for API Evangelist. My objective is to keep funding my research, producing the short form (blog), and long form (guides, white papers, and blueprints), while keeping it all rooted in what the leading API providers, and ultimately the people behind them are doing on the ground. With this in mind, you will find more areas of my research, providing links to people actually doing these things in the field, and you will also hear more about the conversations I am having with these people as they execute their craft.

As always, if you, or your company is doing something interesting in these areas, let me know—if you are an individual looking to freelance in these ares, or build a consultancy delivering services in these areas, let me know. I can’t guarantee I’ll include you in my research, but if you are doing interesting things, you’ll stand out, and I’m sure I can find some way to showcase your work in a way that helps you, me, and the wider API space. Also, if you need help with a project in one of these areas, feel free to reach out, and I’ll do my best to point you in the right direction.

Postman Collections Will Take Your API Productivity To The Next Level

If you are an API developer, it is likely you have used Postman, the simple tool for building, testing, and documenting your APIs. I have Postman open as a Google Chrome App, which allows me to make API calls as I’m designing, developing, and integrating with the APIs across my world. Something which opens up the response and requests of API calls that I’m making, giving me more insight into how things are actually working (or not).

One of the key aspects of Postman, are the collections, which:

A collection lets you group individual requests together. These requests can be further organized into sub-collections/folders to completely mirror your API. Requests can also store variations and responses when saved in a collection. You can add metadata like name and description too so that all the information that a developer needs to use your API is available right where he(she) needs it. Collections are listed in the sidebar alphabetically. You can search through collection requests using the search form for quick access.

To me, Postman Collections are API discovery at the API transaction level. Allowing you to define a single unit of currency in the API economy, save, and organize them, and execute them at any point in your API lifecycle. Postman Collections measure not just an API transaction that happens, it is a measure of future transactions that can happen, complete with any relevant meta data that will be needed along the way.

Along with Swagger, and API Blueprint, I’m working to better understand how Postman Collections impact, and fuel the API lifecycle, including conversations with Abhinav Asthana (@a85), Founder and CEO of Postman, about their roadmap. Postman Collections are not just about defining, organizing, and executing your API calls in the Postman client as a solo API developer, they are also about collaborating with other key players involved throughout the API lifecycle.

I’m setting up my API Stack as Postman Collections, to help me understand how I can use the format to improve my API own API workflows. My goal is to ensure Postman works seamless with all stops along my own API and micro service lifecycle, from design to evangelism, and is plug and play as a machine readable element of APIs.json.

Ask The Stack When You Need API Support

I was profiling the video sharing API Dailymotion the other day, going through their developer area and profiling their API operations. One of the things I do as part of the profiling of any company, is checkout how they execute their support.

Dailymotion employs two very common building blocks for their platform support, including an API specific Twitter handle, and good ol fashion email—both pretty proven approaches. However Dailymotion also employs a third aspect to thier API support, by recommending you head over to Stack Overflow for some community support.

Using Stack Overflow in this way is not that original, I see numerous API providers doing this, the part I found interesting was their reference to getting Dailymotion API support via Stack Overflow as, "ask the stack!" I like that, I think it reflects what Stack Overflow is to the API developer community, and was an elegant way to send API developers off your site, to get the support they need.

We Need An Open Library Of The Most Common Utility API Implementations

I was spending time profiling APIs late last night while putting back a couple of IPAs. Yes this is what I do on a Friday night, you have a problem with that? Anyways, I was crafting Swagger definitions for the 7digital music APIs, and the I came across their territories API. "The Territories API serves data about countries that 7digital operates in, data about those counties, and a one or more languages with shop urls in each country”, something that I could see being pretty useful to developers when building music apps on top of the platform.

There has been numerous APIs I’ve developed in the past, where the need for some supporting, utility APIs, such as a list of states, zip codes, counties, or other resources was called for. Two layers to doing this: 1) Acknowledging the little things developers need goes a long way in building trust with them, letting them know you actually care, and get what they are facing 2) You want devs to achieve integration as quickly as possible, provide them with the little things that they will have to go hunt for, and possibly prevent them from achieving their objectives. — Reduce any friction possible!

I'd like to see an open source library of utility API design, complete with a variety of server side code, and data stores emerge, that help API providers deliver a more complete stacks of API resources. If you need a state / province API, or a language API, you could just grab one off the shelf and install it seamlessly into your API stack. This is just one of those little areas, that I think could be slowing the overall advancement of APis (just a wee bit), and with a little community effort, could really grease the wheels in API adoption, and fuel more meaningful integrations.

A Breakdown Of My Dream APIs.json File

I'm continuing my work, to help people understand what APIs.json is, and the varying ways that it can be put to use. My post the other week, breaking down Fitbits APIs.json file is a good example of where to get started, and as a follow-up I wanted to help further set the bar for what a minimum viable APIs.json looks like, and today, I am going in the other direction--toward my dream APis.json file.

APIs.json starts with a basic set of descriptions for who you are, the API provider. Each header of an APIs.json file gives you a handful of parameters for describing who you are:

  • name - your individual or company name, who is managing the APIs.json file.
  • description - a description of your company and / or the API collection you are building.
  • image - an image, logo, or icon that describes yourself or your company
  • tags - a handful of key words and phrases that describe your API collection.
  • created - the first date in which an APIs.json file was created.
  • modified - the last date in which an APIs.json file created.
  • url - The url of where the APIs.json lives, allowing your file to be portable.

Those seven parameters provide details on who you are, and what the API collection is all about. Remember an API collection doesn’t always have to live under a specific company domain like Twilio.com, it could be a temporary or more permanent collection, that is part of specific project or application.

The next essential element of an APIs.json file, is the APIs collection, providing you the ability to describe one or many APIs as part of this collection. Similar to the parameters provided for the header, each API entry is allowed a handful of parameters that describe the API:

  • name - the name of the API.
  • description - a description of the value an API delivers.
  • image - an image, logo, or icon that describes an API.
  • tags - a handful of key words and phrases that describe the API itself.
  • humanURL - The url any human should visit to learn more about an API.
  • baseURL - The base url any machine should follow to start using an API.

Each API should have at least this information, at a minimum. I could stay here, with a minimum viable APIs.json definition, but I encourage you to take one more step, and put the properties collection to use for each API. You can provide any other URL you want for an APIs properties, but I recommend starting with the basic properties:

  • TermsOfService - where do I find your terms of service page.
  • StatusPage - where is the url of the status page, where I can get platform update.
  • Pricing - point me directly to where your pricing page is, so I can make a decision on price.
  • Forums - where is the community forum located for a platform, even if this is Stack Overflow.
  • AlertsTwitterHandle - what is the primary Twitter handle for the API itself.

These are meant to satisfy the common needs of anyone learning about API operations, however they are just URLs meant for the human API consumer. In my dream APIs.json file, there will be a robust amount of machine readable properties available for each API, beginning with the two most important:

  • Swagger  - a machine readable JSON or YAML file describing your API surface area
  • Blueprint - a machine readable markdown file describing your API surface area

Along with providing machine readable definitions of the API surface area, establishing a central truth or fingerprint for any API interface, it is just as important to provide a machine readable license for the API:

  • InterfaceLicense - a machine readable pointer to the licensing for the API interface

Along with making sure the interface of an API matches your application objectives, consumers need to understand the licensing restrictions, or the freedom that comes with deeply integrating an API resource into any system or app.

Since I’m talking about my dream APIs.json file, I’m going to talk about two added property formats I’m currently working on behind the scenes, adding to the stack of machine readable API definition formats.. These new areas, represent two areas I’m working hard to define and understand, right after I hand-craft Swagger definitions for my APIs:

  • API Pricing - taking pricing to the next level and making it machine readable.
  • API Questions - answering the important questions I need to know about each API.

Can you imagine if API pricing was machine readable by default? Think of the options for building in a broker or market layer within the index of API platforms, and API collections, or even via an IDE. These two definitions are in an alpha stage, but are based upon data I've been gathering behind the scenes, so a lot of thought has gone into settling on these buckets.

After that, I’d say there are a handful custom properties I’d like to see applied to each API indexed within an APIs.json:

  • x-blog - where do I find your blog. (machine-readable below)
  • x-blogrss - where can I just get an RSS of your blog stream.
  • b-github - what is the primary Github account for the API.

That concludes my list of elements I’d like to see available in my dream APIs.json file. You can see examples of this in action, with the 700+ companies I've generated APIs.json files for, over at my API Stack Github repo. There is a lot of work left to do, but this dream APIs.json file resembles a vision I have for the future of API discovery—which I see as the engine for the API economy.

My goal is to get there I need the most important aspects of API operations machine readable. We aren't there yet, but I can see it. Taste it. Imagine what we can do when you can program against:

  • Surface Area (Swagger, Blueprint)
  • Blog (RSS Feed)
  • Status (RSS Feed)
  • Forum (RSS Feed)
  • Twitter (Twitter API)
  • Github (Github API)
  • Pricing (api-pricing)
  • Licensing (API Commons)
  • Questions (api-questions)

I have been staying in tune with the API space using RSS feeds, and the Twitter and Github APIs for a couple years. I’m just now developing a deeper understanding of the overall API space through the generation of machine readable API definitions for popular APIs. I can’t do much on the API licensing front beyond launching API Commons, but I am working to define pricing with my api-pricing definition work, and also trying to capture the vital meta-data I need about API operations using api-questions.

This post ended up being longer than I anticipated, but it is helping me beter understand what some of the next steps are for not just APIs.json, but also my own monitoring of the space. My goal is to not just push forward the APIs.json definition, but push forward my understanding along the way. Who knows maybe I'll drag you along too! ;-)

Ok, back to work. I just needed to wrap up these two posts about APis.json that were lingering in my outgoing story and idea queue.