These are the news items I've curated in my monitoring of the API space that have some relevance to the API definition conversation and I wanted to include in my research. I'm using all of these links to better understand how the space is testing their APIs, going beyond just monitoring and understand the details of each request and response.07 Nov 2017
We just wrapped up the 8th edition of APIStrat in Portland, Oregon this last week. I’ll be working through my notes, and memory of the event in future posts, but thing that stood out for me was the presence of Postman at the event. No, I’m not talking about their booth, and army of evangelists and company reps on site–although this was the first time I’ve seen them out in such force. I’m talking about the usage of the API development environment by presenters, as a live coding environment in their talks, replacing the command line and browser for how you demonstrate the magic of APIs to your audience.
On the first day of the conference I attended two separate workshops where Postman was the anchor for the talk. As they worked their way through their slides they kept switching back to the Postman application to show some sort of real results, from an actual, or mocked API. It is the new live coding environment for API evangelist, architects, designers, developers, and security folks. It is the quickest way to go from API concept, to demonstrating API solutions in any presentation. What I also really like is that it transcends any single programming language. In the past, I’ve always hated when someone would bust out some .NET code to show an API call, or something very language or platform specific. Postman reflects a more API way of doing things, that is elevated above the dogma of any single programming language community.
I am beginning to use Postman and Restlet client in my API training and curriculum more. Directing my users to actually try something out in the API client before moving on to the next step. It is kind of becoming the new interactive API documentation, but something that is linkable from any story, training materials, or incorporated directly into a live talk. As an evangelist it is yet another reason to maintain OpenAPI definitions and Postman Collections of all your most common API use cases. So that you can find, and include all your relevant API calls directly into your storytelling. I’m going to start exploring the viability of doing this with non-developers, and folks who aren’t familiar with Postman yet. I have a feeling that within the echo chamber there is a sort of familiarity taking hold when it comes to Postman, but I want to make sure the environment isn’t a shock for newcomers, and is something that can help users go from zero to API response in 60 seconds or less.
It is interesting to watch the API space evolve, and what tools become common place like Postman has become. For a while the Apigee API Explorer was common place, but has quickly fallen into the background. Swagger UI has enjoyed dominance when it comes to interactive API documentation, but is something I see beginning to shift. I’m hoping that API clients and development environment like Postman, Restlet, PAW, and Insomnia continue to develop mindshare. These tools are all good for helping make API integration easier, but as I saw at APIStrat, they can also help us communicate with our readers, and audience about what is possible with APIs. Speaking to as wide of a group as possible, elevating above any single programming language, and just speaking API.
There are many reasons you want to have a road map for your API. It helps you communicate with your API community where you are going with your API. It also helps you have a plan in place for the future, which increases the chances you will be moving things forward in a predictable and stable way. When I’m reviewing and API I don’t see a public API road map available, I tend to give them a ding on the reliability and communication for their operations. One of the reasons we do APIs is to help us focus externally with our digital resources, which communication plays an important role, and when API providers aren’t communicating effectively with their community, there are almost always other issues right behind the scenes.
A road map for your API helps you plan, and think through how and what you will be releasing for the foreseeable future. Communicating this plan externally helps force you think about your road map in context of your consumers. Having a road map, and successfully communicating about it via a blog, on Twitter, and other channels helps keep your API consumers in tune with what you doing. In my opinion, an API road map is an essential building block for all API providers, because it has direct value on the health of API operations, but because it also provides an external sign of the overall health of a platform.
Beyond the direct value of having an API road map, there are other reasons for having one that will go beyond just your developer community. In a story in Search Engine Land about Google Posts, the author directly references the road map as part of their storytelling. “In version 4.0 of the API, Google noted that “you can now create Posts on Google directly through the API.” The changelog include a bunch of other features, but the Google Posts is the most notable.” Adding another significant dimension to the road map conversation, and helping out with SEO, and other API marketing efforts.
As you craft your road map you might not be thinking about the fact that people might be referencing it as part of stories about your platform. I wouldn’t sweat it too much, but you should at least make sure you are having a conversation about it with your team, and maybe add an editorial cycle to your road map publishing process. Making sure what you publish will speak to your API consumers, but also make for quotable nuggets that other folks can use when referencing what you are up to. This is all just a thought I am having as I’m monitoring the space, and reading about what other APIs are are up to. I find road maps to be a critical piece of the API communication, and support, and I depend on them to do what I do as the API Evangelist. I just wanted to let you know how important your API road map is, so you don’t forget to give it some energy on a regular basis.
APIs are not forever, and eventually will go away. The trick with API deprecation is to communicate clearly, and regularly with API consumers, making sure they are prepared for the future. I’ve been tracking on the healthy, and not so healthy practices when it comes to API deprecation for some time now, but felt like Google had some more examples I wanted to add to our toolbox. Their approach to setting expectations around API deprecation is worthy of emulating, and making common practice across industries.
The Google Adwords API team is changing their release schedule, which in turns impacts the number of APIs they’ll support, and how quickly they will be deprecating their APIs. They will be releasing new versions of the API three times a year, in February, June and September. They will also be only supporting two releases concurrently at all times, and three releases for a brief period of four weeks, pushing the pace of API deprecation alongside each release. I think that Google’s approach provides a nice blueprint that other API provides might consider adopting.
Adopting an API release and sunset schedule helps communicate the changes on the horizon, but it also provides a regular rhythm that API consumers can learn to depend on. You just know that there will be three releases a year, and you have a quantified amount of time to invest in evolving integration before any API is deprecated. It’s not just the communication around the roadmap, it is about establishing the schedule, and establishing an API release and sunset cadence that API consumers can be in sync with. Something that can go a lot further than just publishing a road map, and tweeting things out.
I’ll add this example to my API deprecation research. Unfortunately the topic is one that is widely communicated around in the API space, but Google has long a strong player when it comes to finding healthy API deprecation examples to follow. I’m hoping to get to the point soon where I can publish a simple guide to API deprecation. Something API providers can follow when they are defining and deploying their APIs, and establish a regular API release and deprecation approach that API developers can depend on. It can be easy to get excited about launching a new API, and forget all about it’s release and deprecation cycles, so a little guidance goes a long way to helping API providers think about the bigger picture.
I study the API universe every day of the week, looking for common patterns in the way people are using technology. I study almost 100 stops along the API lifecycle, looking for healthy practices that companies, organizations, institutions, and government agencies can follow when dialing in their API operations. Along the way I am also looking for patterns that aren’t so healthy, which are contributing to many of the problems we see across the API sector, but more importantly the applications and devices that they are delivering valuable data, content, media, and algorithms to.
One layer of my research is centered around studying API security, which also includes keeping up with vulnerabilities and breaches. I also pay attention to cybersecurity, which is a more theatrical version of regular security, with more drama, hype, and storytelling. I’ve been reading everything I can on the Equifax, Accenture, and other scary breaches, and like the other areas of the industry I track on, I’m beginning to see some common patterns emerge. It is something that starts with the way we use (or don’t use) technology, but then is significantly amplified by the human side of things.
There are a number of common patterns that contribute to these breaches on the technical side, such as not enough monitoring, logging, and redundancy in security practices. However, there are also many common patterns emerging from the business approach by leadership during security incidents, and breaches. These companies security practices are questionable, but I’d say the thing that is the most unacceptable about all of these is the communication around these security events. I feel like they demonstrate just how dysfunctional things are behind the scenes at these companies, but also demonstrate their complete lack of respect and concern for individuals who are impacted by these incidents.
I am pretty shocked by seeing how little some companies are investing in API security. The lack of conversation from API providers about their security practices, or lack of, demonstrates how much work we still have to do in the API space. It is something that leaves me concerned, but willing to work with folks to help find the best path forward. However, when I see companies do all of this, and then do not tell people for months, or years after a security breach, and obfuscate, and bungle the response to an incident, I find it difficult to muster up any compassion for the situations these companies have put themselves in. Their security practices are questionable, but their communication around security breaches is unacceptable.
Creating regular content for your blog is essential to maintaining a presence. If you don’t publish regularly, and refresh your content, you will find your SEO, and wider presence quickly becoming irrelevant. I understand that unlike me, many of you have jobs, and responsibilities when it comes to operating your APIs, and carving out the time to craft regular blog posts can be difficult. To help you in your storytelling journey I am always looking for other stories to help alleviate your pain, while helping keep your blog active, and ensure folks will continue stumbling across your API, or API service, while Google, or on social media.
Another interesting example of how to keep your blog fresh came from my partners over at Runscope, who conducted a featured guest blog post series, where they were paying API community leaders to help “create an incredible resource of blog posts about APIs, microservices, DevOps, and QA.” Which has produced a handful of interesting posts:
- Monolith to Microservices: Transforming a web-scale, real-world e-commerce platform using the Strangler Pattern
- You Might Not Need GraphQL
- 3 Easy Steps to Cloud Operational Excellence
- Building a Steam Powered IoT API with Thingsboard
One thing to note is that Runscope paid $500.00 per post to help raise the bar when it comes to the type of author that will step up for such an effort. I’ve seen companies try to do this before, offering gift cards, swag, and even nothing in return, with varying grades of success and failure. I’m not saying a guest author program for your blog will always yield the results you are looking for, but it is a good way to help build relationships with your community, and help augment your existing workload, with some regular storytelling on the blog.
A guest blogger program is a tool I will be adding to my API communications research, expanding on the tools API operators have in their toolbox to keep their communication strategies active. An active blog does more than just educate your community, and boost your SEO. An active blog, that is informative, and relevant shows that there is someone home behind an API, and that they are investing in the platform. While there are exceptions, the clearest sign that an API will soon be deprecated, or does not have the resources to support consumers properly is when the blog hasn’t been updated in the last six months. While I’m reviewing, indexing, and learning about different APIs, when I come across an inactive blog, or Twitter account for an API, I’ll almost always keep moving, feeling like there really isn’t much worthwhile there, as it will soon be gone.
Coming up with things creative things to write about regularly on the blog, and on Twitter when you are operating an API is hard. It has taken a lot of discipline to keep posts going up on API Evangelist regularly for the last seven years–totaling almost 3K total stories told so far. I don’t expect every API provider to have the same obsessive compulsive disorder that I do, so I’m always looking for innovative things that they can do to communicate with their API communities–something that Amazon Web Services is always good at providing healthy examples that I feel I can showcase.
One thing the AWS team does on a regular basis is tweeting out links to specific areas of their documentation, that helps users accomplish specific things with AWS APIs. The AWS security team is great at doing this, with recent examples focusing on securing things with the AWS Directory Service, and API Organizations. Each contains a useful description, attractive looking image, and a link to a specific page in the documentation that helps you learn more about what is possible.
I have been pushing myself to make sure all headers, and subheaders in my API documentation have anchors, so that I can not just link to a specific page, but I can link to a specific section, path, or other relevant item within my API documentation. This helps me in my storytelling when I’m looking to reference specific topics, and would help when it comes to tweeting out regular elements across my documentation in tweets. I’m slowly going to push out some of the lower grade tweets of curated news that I push out, and replace with relevant work I do in specific areas of my research–using my own work to fill the cracks over less than exciting things I may come across in the API space.
Tweeting out what is possible with your API, with links to specific sections of your API documentation is something I’m going to add to my API communication research. Providing a common building block that other API providers, or even API service providers can consider when looking for things to fill the cracks in their platform communication strategy. It is simple, useful to API consumers, and is an easy way to keep the Tweet stream regularly flowing, and helping developers understand what is possible.
How AWS Is doing it…
I’ve covered this topic several times before, but I figured I’d share again for folks who might have just become readers int he last year. Providing an overview of how API Evangelist works, to help eliminate confusion as you are navigating around my site, as well as to help you find what you are looking for. First, API Evangelist was started in the summer of 2010 as a research site to help me better understand what is going on in the world of APIs. In 2017, it is still a research site, but it has grown and expanded pretty dramatically into a network of websites, driven by a data and a content core.
The most import thing to remember is that all my sites run on Github, which is my workbench in the the API Evangelist workshop. apievangelist.com is the front door of the workshop, with each area of my research existing as its own Github repository, at its own subdomain with the apievangelist domain. An example of this can be found in my API design research, where you will find at design.apievangelist.com. As I do my work each day, I publish my research to each of my domains, in the form of YAML data for one of these areas:
- Organizatons - Companies, organizations, institutions, programs, and government agencies doing anything interesting with APIs.
- Individuals - The individual people at organizations, or independently doing anything interesting with APIs.
- News - The interesting API related, or other news I curate and tag daily in my feed reader or as I browse the web.
- Tools - The open source tooling I come across that I think is relevant to the API space in some way.
- Building Blocks - The common building blocks I find across the organizations, and tooling I’m studying, showing the good and the bad of doing APIs.
- Patents - The API related patents I harvest from the US Patent Office, showing how IP is impacting the world of APIs.
You can find the data for each of my research areas in the _ data folder for each repository. Which is then rendered as HTML for each subdomain using Liquid via each Jekyll CMS driven website. All of this is research. It isn’t meant to be perfect, or a comprehensive directory for others to use. If you find value in it–great!! However, it is just my research laying on my workbench. It will change, evolve, and be remixed and reworked as I see fit, to support my view of the API sector. You are always welcome to learn from this research, or even fork and reuse it in your own work. You are also welcome to submit pull requests to add or update content that you come across about your organization or open source tool.
The thing to remember about API Evangelist is it exist primarily for me. It is about me learning. I take what I learn and publish as blog posts to API Evangelist. This is how I work through what I’m discovering as part of my research each day, and use as a vehicle to move my understanding of APIs forward. This is where it starts getting real. After seven years of doing this I am reaching 4K to 7K page views per day, and clearly other folks find value in reading, and sifting through my research. Because of this I have four partners, 3Scale, Restlet, Runscope, and Tyk who pay me money to have their logo on the home page, in the navigation, and via a footer toolbar. Runscope also pays me to place a re-marketing tag on my site so they can show advertising to my users on other websites, and Facebook. This is how I pay my rent, an how I eat each month.
Beyond this base, I take my research and create API Evangelist industry guides. API Definitions, and API Design are the two most recent editions. I’m currently working on one for data, database, as well as deployment, and management. These guides are sometimes underwritten by my partners, but mostly they are just the end result of my API research. I also spend time and energy taking what I know and craft API strategy and white papers for clients, and occasionally I actually create APIs for people–mostly in the realm of human services, or other social good efforts. I’m not really interested in building APIs for startups, or in service of the Silicon Valley machine. Even tough I enjoy watching, studying, and learning from this world, because there are endless lessons regarding how we can use technology in this community, as well as how we should not be using technology.
That is a pretty basic walk through of API Evangelist works. It is important to remember I am doing this research for myself. To learn, and to make a living. API Evangelist is a production, a persona I created to help me wade through the technology, business, and politics of APIs. It reflects who I am, but honestly is increasingly more bullshit than it is reality, kind of like the API space. I hope you enjoy this work. I enjoy hearing from my readers, and hearing how my research impacts your world. It keeps me learning each day, and from ever having to go get a real job. It is always a work in progress and never done. Which I know frustrates some, but I find endlessly interesting, and is something that reflects the API journey, something you have to get used to if you are going to be successful doing APIs in this crazy world.
I’m always learning from the API communication practices from out of the different AWS teams. From the regular storytelling coming out of the Alexa team, to the mythical tales of leadership at AWS that have contributed to the platform’s success, the platform provides a wealth of examples that other API providers can emulate.
As I talked about last week, finding creative ways to keep publishing interesting content to your blog as part of your API evangelism and communications strategy is hard. It is something you have to work at. One way I find inspiration is by watching the API leaders, and learning from what they do. An interesting example I recently found out of the AWS security team, was their approach to showcasing the top 20 AWS IAM documentation pages so far in 2017. It is a pretty simple, yet valuable way to deliver some content for your readers, that can also help you expose the dark corners of your API documentation, and other resources on your blog.
The approach from the AWS security team is a great way to generate content without having to come up with good ideas, but also will help with your SEO, especially if you can cross publish, or promote through other channels. It’s pretty basic content stuff, that helps with your overall SEO, and if you play it right, you could also get some SMM juice by tweeting out the store, as well as maybe a handful of the top links from your list. It is pretty listicle type stuff, but honestly if you do right, it will also deliver value. These are the top answers, in a specific category, that your API consumers are looking for answers in. Helping these answers rise to the top of your blog, search engine, and social media does your consumers good, as well as your platform.
One more tool for the API communications and evangelism toolbox. Something you can pull out when you don’t have any storytelling mojo. Which is something you will need on a regular basis as an API provider, or service provider. It is one of the tricks of trade that will keep your blog flowing, you readers reading, and hopefully your valuable API, products, services, and stories floating to the top of the heap. And that is what all of this is about–staying on top of the pile, keeping things relevant, valuable, and useful. If we can’t do that, it is time to go find something else to do.
After seven years of telling stories on API Evangelist I’ve had to repeat myself from time to time. Honestly, I repeat myself A LOT. Hopefully I do it in a way that some of you don’t notice, or at least you are good at filtering the stories you’ve already heard from your feed timeline. My primary target audience is the waves of new folks to the world of APIs I catch with the SEO net I’m casting and working on a daily basis. Secondarily, it is the API echo chamber, and folks who have been following me for a while. I try to write stories across the spectrum, speaking to the leading edge API conversations, as well as the 101 level, and everything in between.
Ask anyone doing API evangelism, advocacy, training, outreach, and leadership–and they’ll that you have to repeat yourself a lot. It is something you get pretty sick of, and if you don’t find ways to make things interesting, and change things up, you will burn out. To help tell the same story over and over I’m always looking for a slightly different angle. Let’s take API Meetups as an example. Writing a story about conducting an API Meetup has been done. Overdone. To write a new story about it I’ll evaluate what is happening at the Meetup that is different, or maybe the company, or the speaker. Diving into the background of what they are doing looking for interesting things they’ve done. You have to find an angle to wrap the boring in something of value.
API documentation is another topic I cover over, and over, and over. You can only talk about static or interactive API documentation so much. Then you move into the process behind. Maybe a list of other supporting elements like code samples, visualizations, or authentication. How was the onboarding process improved? How the open source solution behind it simplifies the process. You really have to work at this stuff. You have to explore, scratch, dig through your intended topic until you find an angle that you truly care about. Sure, it has to matter to your readers, but if you don’t care about it, the chances of writing an interesting story diminishes.
This process requires you to get to know a topic. Read other people’s writing on the topic. Study it. Spin it around. Dive into other angles like the company or people behind. Spend time learning the history of how we got here with the topic. If you do all this work, there is a greater chance you will be able to find some new angle that will be interesting. Also, when something new happens in any topical area, you have this wealth of knowledge about it, and you might find a new spark here as well. Even after all that, you still might not find what you are looking for. You still end up with many half finished stories in your notebook. It is just the way things go. It’s ok. Not everything you write has to see the light of day. Sometimes it will just be exercise for the next round of inspiration. That hard work you are experiencing to find a good story is what it takes to reach the point where you are able to discover the gems, those stories that people read, retweet, and talk about.
I know that I make some tech companies nervous. They see me as being unpredictable, with no guarantees regarding what I will say, in a world where the message should be tightly controlled. I feel it in the silence from many of the folks that are paying attention to me at large companies, and I’ve heard it specifically from some of my friends who aren’t concerned with telling me personally. These concerns keep them from working with me on storytelling projects, and prevent them from telling me stories about what is happening internally behind their firewall. It often doesn’t stop employees from telling me things off the record, but it does hinder official relationships, and on the record stories from being shared.
I just want folks to know that I’m not in the scoop, or gotcha business. I only check-in on my page views monthly to help articulate where things are with my sponsors. I’m more than happy to keep conversations off the record, anonymize sources and topics. Even the folks in the space who have pissed me off do not get directly called out by me. Well, most of them. I’ve gone after Oracle a couple of times, but they are the worst of the worst. There are other startups and bigcos who I do not like, and you don’t ever hear me talking trash about them on my blog. Most of my rants are anonymized, generalized, and I take extra care to ensure no enterprise egos, careers, or brands are hurt in the making of API Evangelist.
If you study my work, you’ll see that I talk regularly with federal government agencies, and large enterprise organizations weekly, and I never disclose things I shouldn’t be. If you find me unpredictable, I’m guessing you really haven’t been tuning into what I’ve been doing for very long, or your insecurities run deeper than anything to do with me. I’m not in the business of making folks look bad. Most of the companies who are looking bad in the API space do not need my help, they excel at doing it on their own. I’m usually just chiming in to help amplify, and use as a case study for what API providers should consider NOT DOING in their own API operations. Sure, I may call you out for your dumb patents, and the harmful acquisitions you make, but anything I rant about is going to already be public material–I NEVER do this with private conversations.
So, if you are experiencing reservations about sharing stories with me, or possibly sponsoring some storytelling on API Evangelist because you are worried about what will happen, stop fretting. If you are upfront with me, clear about what is on the record, and what is off, and honest about what you are looking to get out of the relationship, things will be fine. Even if they end up being rocky, I’m not the kind of person to call you out on the blog. I may complain, rant, and vent, but you can look through seven years of the blog and you won’t find me doing that about anyone I’ve specifically worked with on storytelling projects. I don’t always agree with why corporations, institutions, and government agencies are so controlling of the message around their API operations, but I will be respectful of any line you draw for me.
I am spending two days this week with the Capital One DevExchange team outside of Washington DC, and they’ve provided me with a list of questions for one of our sessions, which they will be recording for internal use. To prepare, I wanted to work through my thoughts, and make sure each of these answers were on the tip of my tongue–here is one of those questions, along with my thoughts.
The number API that gets me out of bed each day, with an opportunity to apply what I’ve learned in the API sector is with the Human Services Data API (HSDA). Which is an open API standard I am the technical lead for which helps municipalities, and human service organizations better share information that helps people find services in their communities. This begins with the basics like food, housing, and healthcare, but in recent months I’m seeing the standard get applied in disaster scenarios like Hurricane Irma to help organize shelter information. This is why I do APIs. The project is always struggling for funding, and is something I do mostly for free, with small paychecks whenever we receive grants, or find projects where we can deliver an actual API on the ground.
Next, I’d say it is government APIs at the municipal, state, but mostly at the federal levels. I was a Presidential Innovation Fellow in the Obama administration, helping federal agencies publish their open data assets, take inventory of their web services. I don’t work for the government anymore, but it doesn’t mean the work hasn’t stopped. I’m regularly working on projects to ensure RFPs, and RFIs have appropriate API language in them, and talking with agencies about their API strategy, helping educate them what is going on in the private sector, and often times even across other government agencies. APIs like the new FOIA API, Recreational Information Database API, Regulations.gov, IRS APis, and others will have the biggest impact on our economy and our lives in my opinion, so I make sure to invest a considerable amount of time here whenever I can.
After that, working with API education and awareness at higher educational institutions is one my passions and interest. My partner in crime Audrey Watters has a site called Hack Education, where she covers how technology is applied in education, so I find my work often overlapping with her efforts. A portion of these conversations involve APIs at the institutional level, and working with campus IT, but mostly it about how the Facebook, Twitter, WordPress, Dropbox, Google, and other public APIs can be used in the classroom. My partner and I are dedicated to understanding the privacy implications of technology, and how APIs can be leveraged to give students and faculty more control over their data and content. We work regularly to tell stories, give talks, and conduct workshops that help folks understand what is possible at the intersection of APIs and education.
After that, I’d say the main stream API sector keeps me interested. I’m not that interested in the whole startup game, but I do find a significant amount of inspiration from studying the API pioneers like SalesForce and Amazon, and social platforms like Twitter and Facebook. As well as the cool kids like Twilio, Stripe, and Slack. I enjoy learning from these API leaders, studying their approaches, but where I find the most value is sharing these stories with folks in SMB, SME, and the enterprise. These are the real-world stories I thrive on, and enjoy retelling as part of my work on API Evangelist. I’m a technologist, so the technology of doing APIs can be compelling, and the business of doing this has some interesting aspects, but it’s mostly the politics of doing APIs that intrigues me. This primarily involves the politics of the humans involved within a company, or industry, providing what I always find to be the biggest challenges of doing APIs.
In all of these areas, what actually gets me up each day, is being able to tell stories. I’ve written about 3,000 blog posts on API Evangelist in seven years. I work to publish 3-5 posts each weekday, with some gaps in there due to life getting in the way. I enjoy writing about what I’m learning each day, showcasing the healthy practices I find in my research, and calling out the unhealthy practices I regularly come across. This is one of the reasons I find it so hard to take a regular job in the space, as most companies are looking to impose restrictions, or editorial control over my storytelling. This is something that would lead to me not really wanting to get up each day, and is the number one reason I don’t work in government, resulting in me pushing to make change from the outside-in. Storytelling is the most important tool in my toolbox, and it should be in every API providers as well.
I’ve been setting aside time to browse through and explore tagged projects on Github each week, learning about what is new and trending out there on the Githubz. It is a great way to explore what is being built, and what is getting traction with users. You have to wade through a lot of useless stuff, but when I come across the gems it is always worth it. I’ve been providing guidance to all my customers that they should be publishing their projects to Github, as well as tagging them coherently, so that they come up as part of tagged searches via the Github website, and the API (I do a lot of discovery via the API).
When I am browsing API projects on Github I usually have a couple of orgs and users I tend to peek in on, and my friend Mike Ralphson (@PermittedSoc) is always one. Except, I usually don’t have to remember to peek in on Mike’s work, because he is really good at tagging his work, and building interesting projects, so his stuff is usually coming up as I’m browsing tags. He is the first repository I’ve come across that is organizing OpenAPI 3.0 tooling, and on his project he has some great advice for project owners: “Why not make your project discoverable by using the topic openapi3 on GitHub and using the hashtag #openapi3 on social media?” « Great advice Mike!!
As I said, I regularly monitor Github tags, and I also monitor a variety of hashtags on Twitter for API chatter. If you aren’t tagging your projects, and Tweeting them out with appropriate hashtags, the likelihood they are going to be found decreases pretty significantly. This is how Mike will find your OpenAPI 3.0 tooling for inclusion in his catalog, and it is how I will find your project for inclusion in stories via API Evangelist. It’s a pretty basic thing, but it is one that I know many of you are overlooking because you are down in the weeds working on your project, and even when you come up for air, you probably aren’t always thinking about self-promotion (you’re not a narcissist like me, or are you?)
Twitter #hashtags has long been a discovery mechanism on social media, but the tagging on Github is quickly picking up steam when it comes to coding project discovery. Also, with the myriad of ways in which Github repos are being used beyond code, Github tagging makes it a discovery tool in general. When you consider how API providers are publishing their API portals, documentation, SDKs, definitions, schema, guides, and much more, it makes Github one of the most important API discovery tools out there, moving well beyond what ProgrammableWeb or Google brings to the table. I’ll continue to turn up the volume on what is possible with Github, as it is no secret that I’m a fan. Everything I do runs on Github, from my website, to my APIs, and supporting tooling–making it a pretty critical part of what I do in the API sector.
If you have followed my work in the API space you know that I consider myself an API storyteller before I ever would an API evangelist, architect, or the other skills I bring to the table. Telling stories about what folks are up to in the space is the most important thing to me, and I feel it is the most common thing people stumble across, and end up associating with my brand. You hear me talk regularly about how important stories are, and how all of this API thing is only a thing, because of stories. Really, telling stories is the most important you should be doing if you are an API provider or API service provider, and something you need to be prioritizing.
I was talking with a friend, and client the other day about their API operations, and after they told me a great story about the impact their APIs were making I said, “you should tell that story”! Which they responded, “I wish I had time to tell that story, but I don’t. My boss doesn’t prioritize me spending time on telling stories about what we are doing.” ;-( It just broke my heart. I get really, really busy during the week with phone calls, social media, and other project related activity. However, I always will stop what I’m doing and write 3-5 blog posts for API Evangelist about what I’m doing, and what I’m seeing. I know many of the stories are mundane and probably pretty boring, but they are exercise for me, of my ideas, my words, and how I communicate with other people.
The way that enterprise groups and startups operate is something I’m very familiar with. I’ve been scolded by many bosses, and told not read or write on my blog. This is one of the reasons I don’t work in government anymore, or in the enterprise, as it would KILL ME to not be able to tell stories. I need storytelling to do what I do. To work through ideas. It is how I learn from others. Why would I want to do something that I can’t tell others about? Why would I not prioritize the cool things my clients are doing with my APIs? Sure, there are some classified, and sensitive situations where you definitely would not, but most of the reasons I hear for not telling stories publicly about the cool things you are doing are complete bullshit. I’m sorry, but they are. Even if you have to package it as a white paper or case study, you should be putting this down for others to learn from.
When you find yourself telling your creative side (or me), that you wish you had time to tell that story, you should consider that a canary in the coal mine. A sign that there is other illnesses going on. Sure, once or twice is fine, but if this becomes a sustained thing, or worse–you stop wanting to tell stories at all, then you should be looking for a new gig. You just had your mojo killed. Nobody deserves that. No employer should kills their employees storytelling mojo. Even if you are all business, telling stories is essential to making things work. Press releases are stories. Ok, they are usually a very sad, pathetic story, but they are a story. Your company blog should be active. Your personal blog should be active. Go check out your personal blog, when was the last time you wrote something you were passionate about? If it was more than a year ago, your employer has put you in a box, and is looking to keep you there.
Photo Credit: The Boyhood of Raleigh by Sir John Everett Millais, oil on canvas, 1870. A seafarer tells the young Sir Walter Raleigh and his brother the story of what happened out at sea, from the Wikipedia entry for storytelling.
Don’t who know who I am? I am the API Evangelist. Ok, I know this post is dripping with ego. However, it is the last post in my week of API rants, and I’m just pumped from writing all of these. These types of posts are so easy to write because I don’t have to do any research, and real work, I just write, putting my mad skills at whitesplaining and mansplaining to work–tapping into my privilege. So I’m going to end the week with a bang, and fully channel the ego that has developed along with the persona that is API Evangelist.
However, there is a touch of truth to this. If you are operating an API today, and you do not know who I am, I’m just going to put it out there–you live in a silo. I have published around 3,000 blog posts since 2010 on APIs. I’m publishing 3-5 posts a day, and have consistently done so for seven years. There are definitely some major gaps in that, but my SEO placement is pretty damn good. You type API or APIs, and I’m in the top 30 usually, with the occasional popping up on home page. The number thing I get from folks who message me is that they can’t search for anything API without coming across one of my posts, so they want to talk to me. So why is it that you do not know who I am? I have some ideas on that.
It is because you do not read much outside your silo. When you do, you don’t give any credit to authorship. So when you have read any of my posts you didn’t associate them with a person named Kin Lane. You operate within your silo 98% of the time, and the 2% you get out, you really don’t read much, or learn from others. I on the other hand spend 98% of my time studying what others are doing, and 2% hiding away. My goal is to share this with you. I’d say 75% of my work is just referencing and building on the work of others, only 25% is of my own creation. I’m putting all of this out there for you, and you don’t even know it exists. What does that tell you about your information diet? It tells me that you probably aren’t getting enough exercise and nutrients as part of your regular daily intake, that will make your API operations be less healthy and strong–reading is good for healthy bones girls and boys!
Kin Lane doesn’t have this much ego, but API Evangelist does. The fact that you don’t know who I am shows you aren’t spending enough time studying the API space before launching an API. I’m hoping that you in your API journey you learn more about the importance of coming out of your bubble, and learning from your community, and the wider API community. It is why we do APIs, and why APIs work (when they do). I wrote this title to be provocative and part of my week of rants, but honestly it is true. If you haven’t come across one of my API posts, and stumbled on my blog at some point you should probably think about why this is. The most successful API providers and evangelists I know are tuned into their communities, industries, and wider API space, and are familiar with my work–even if they don’t all like me. ;-)
Note: If my writing is a little dark this week, here is a little explainer–don’t worry, things will back to normal at API Evangelist soon.
I am an API storyteller before am an API architect, designer, or evangelist. My number one job is to tell stories about the API space. I make sure there is always (almost) 3-5 stories a day published to API Evangelist about what I’m seeing as I conduct my research on the sector, and thoughts I’m having while consulting and working on API projects. I’ve been telling stories like this for seven years, which has proven to me how much stories matter in the world of technology, and the worlds that it is impacting–which is pretty much everything right now.
Occasionally I get folks who like to criticize what I do, making sure I know that stories don’t matter. That nobody in the enterprise or startups care about stories. Results are what matter. Ohhhhh reeeaaaly. ;-) I hate to tell you, it is all stories. VC investment in startups is all about the story. The markets all operate on stories. Twitter. Facebook. LinkedIn. Medium. TechCrunch. It is all stories. The stories we tell ourselves. The stories we tell each other. The stories we believe. The stories we refuse to believe. It is all stories. Stories are important to everything.
The mythical story about Jeff Bezos’s mandate that all employees needed to use APIs internally is still 2-3% of my monthly traffic, down from 5-8% for the last couple of years, and it was written in 2012 (five years ago). I’ve seen this story on the home page of the GSA internal portal, and framed hanging on the wall in a bank in Amsterdam. Stories are important. Stories are still important when they aren’t true, or partially true, like the Amazon mythical tale is(n’t). Stories are how we make sense of all this abstract stuff, and turn it into relatable concepts that we can use within the constructs of our own worlds. Stories are how the cloud became a thing. Stories are why microservices and devops is becoming a thing. Stories are how GraphQL wants to be a thing.
For me, most importantly, telling stories is how I make sense of the world. If I can’t communicate something to you here on API Evangelist, it isn’t filed away in my mental filing cabinet. Telling stories is how I have made sense of the API space. If I can’t articulate a coherent story around API related technology, and it just doesn’t make sense to me, it probably won’t stick around in my storytelling, research, and consulting strategy. Stories are everything to me. If they aren’t to you, it’s probably because you are more on the receiving end of stories, and not really influencing those around you in your community, and workplace. Stories are important. Whether you want to admit it or not.
The discussion around whether or not you should be hosting your own questions and answers (QA) and frequently asked questions (FAQ) for your API has continued, with many of the leading API pioneers asserting responsibility over the operations of these important API resources. Amazon noticed that answers about their platform on Quora and Stack Exchange were usually out of date and often just plain wrong, prompting them to launch their own QA solution.
I have written about using API providers using Stack Overflow for may years now. It the last few years I’ve had my readers push back on this for a variety of reasons, from the Stack Overflow community being primarily a white male bro-fest, to finding things being unreliable, out of date, and often a pretty hostile and unfriendly place for people to try and learn about APIs. I’d say that I still use Stack Overflow for about 40% of my querying of API and programming related subjects, but since I’m a white male who has been doing software for 30 years, I’m a little more resistant to the bro-fest. But, I get it, and hear what folks are saying, and get it is not always a suitable environment.
Going back and forth on this subject, I’m back in the camp where API providers should be investing in operating their own QA, FAQ, and support forums. It’s definitely requires a significant amount of investment, policing, and sometimes taking stances that are unpopular, but if you are in this for the long game, it will be worth it. After watching AWS for a decade, you can see how incorrect information about your API operations can really begin to become a liability, and you might want to keep a tighter grip on where your API consumers go look for their answers. An added bonus is that you also get to set the tone for the types of questions that get answered, and the inclusiveness that will exist across your FAQ, QA, and Support.
I really need to get my core API design guides like definitions, design, deployment, and management out the door, because I need to diving into areas like support, and gather all my thoughts regarding how API providers should be approaching this critical layer of operations. I feel like support is one of the most defining characteristics of sustainable API providers, right up there with communications I’d say. I don’t care how good your API is technically, if you don’t have a solid approach to supporting and communicating with your API community, I’m guessing you won’t be around very long, or if you do survive, your platform will be something savvy API consumers steer clear of.
I’m spending a significant amount of time learning about machine learning APIs lately. Some of what I’m reading is easy to follow, while most of it is not. A good deal of what I’m reading is technically complex, and more on the documentation side of the conversation. Other stuff I come across is difficult to read, not because it is technical, but because it is more algorithmic marketing magic, and doesn’t really get at what is really going on (or not) under the hood.
If you are in the business of writing marketing copy, documentation, or even the API design itself, please work extra hard to keep things simple and in plain language. I read so much hype, jargon, fluff, and meaningless content about artificial intelligence and machine learning each day, I take pleasure anytime I find simple, concise, and information descriptions of what ML APIs do. In an exploding world of machine learning hype your products will stand out if they are straight up, and avoid the BS, which will pretty quickly turn off the savvy folks to whatever you are peddling.
Really, this advice applies to any API, not just machine learning. It’s just the quantity of hype we are seeing around AI and ML in 2017 is reaching some pretty extreme levels. Following the hype is easy. Writing fluffy content doesn’t take any skills. Writing simple, concise, plain language names, descriptions, and other meta data for artificial intelligence and machine learning APIs takes time, and a significant amount of contemplation regarding the message you want to be sending. The ML APIs I come across that get right to the point, are always the ones that stick around in my mind, and find a place within my research and storytelling.
We are going to continue to see an explosion in the number of algorithmic APIs, delivering across the artificial intelligence, machine learning, deep learning, cognitive, and other magical realms. The APIs that deliver real business value will survive. The ones that have simple intuitive titles, and concise yet informative description that avoid hype and buzz will be the ones that get shared, reused, and ultimately float to the top of the pile and sticking around. I’m spending upwards of 5-10 hours a week looking through AI and ML API descriptions, and when I come across something that is clearly bullshit I don’t hesitate to flag, and push it back to the back warehouses of my research, keeping my time focused on the APIs which I can easily articulate what they do, and will also make sense to my readers.
Photo Credit: Bryan Mathers (Machine Learning)
I personally understand the challenges with communicating publicly when you work for the federal government. It is one of the top reasons I do not work in federal government anymore. It would kill me if I couldn’t blog each day without friction–it is how I create and ideate. Even with this understanding I find myself regularly frustrated with the lack of communication by owners of APIs across federal government agencies. There are numerous agencies who do successfully communicate around their APIs and open data projects, but the majority of APIs I come across have little, or no communication around their API operations.
Have a blog, Twitter, or Github account might seem like a nice to have, but in reality they are often the only sign that anyone is home, and an API is reliable, and make the the difference between choosing to integrate with an API, or not. A blog or Twitter account, and whats new feature box on the home page of an API developer portal can send the winning (or losing) signal that an API is actually active and alive. Developers come across a lot of APIs that are dormant or abandoned, and the presence of common communication channels (blog, Twitter, Facebook, LinkedIn, Github) are the signal we often need before we are willing to invest the time into learning another new API, or signing up for yet another developer account.
I know that it is possible to handle API communications in a healthy way at government agencies–18F, Census, and others are doing it right. There is some serious storytelling friction occurring in government. I see the same illness in corporate and other institutional API platforms–geeks and IT folks aren’t always the best at getting the word out about what they are doing. However, I think there is additional friction at the government level. We’ve seen a significant increase in blogging, and social network usage usage across government agencies, we need to investigate how we can incentivize federal government API operators to get a little more chatty with their work.
Communication around API operations is an essential building block. Federal government isn’t immune to this. If you aren’t telling the story about why developers should be using it, and actively communicating with your integrators, you will never find the success you seek when doing APIs at your agency. You don’t have to launch a wildly active and popular blog or social media presence. You just need something. A simple blog with RSS, hosted on your Github account. A Twitter account. Something. Please. Anything. Thank you!
There are many good things to come out of doing APIs properly. Unfortunately there are also many bad things that can come out of doing APIs badly, or with misaligned expectations. It is easy to focus on the direct benefits of doing APIs like making data resources available to partners, or maybe developing a mobile application. I prefer looking for the more indirect benefits, which are more human, more than they are ever technical.
As I work with different groups on a variety of API definitions and strategies, one very significant part of the process I see, is people being forced to think outside their box. APIs are all about engaging around data, content, and algorithms on the web, with 3rd parties that operate outside your box. You are forced to lookup, and outward a bit. Not everyone I engage with is fully equipped to do this, for a variety of reasons, but overall the API process does make folks just a little more critical than they do with even their websites.
The web has come with a number of affordances. Those same affordances aren’t always present in API discussions forcing folks to have more conversations around why we are doing APIs (an answer shouldn’t always be yes), and discussing the finer details not just storing your data, and managing your schema, but doing in a way that will play nicely with other external systems. You may be doing things one way internally, and it might even be working for you, but it is something that can only get better with each outside partner, or consumer you are exposed to along your journey. Even with all of the internal politics I encounter in my API conversations, the API process always leaves me enjoying almost any outcome.
I know that some of my friends who follow API Evangelist shake their heads when I talk about API business models, partner programs, and many of the business sides of API operations. Much of my work will have an almost delusional attraction towards the concept of an API. Heavily doused in a belief in technology as a solution. This isn’t accidental. This is API Evangelist. A persona I have developed to help me make a living, and help influence where we go (or don’t go) with technology.
I am delusional enough to think I can influence change in how the world uses technology. I’m borderline megalomaniac, but there really is not sufficient ego to get me quite all the way there. While still very, very, very minor, I feel I have influenced where technology has flowed over my seven years as the API Evangelist. Even if it just slowing the speed (seconds) at which the machines turn on us, and kills us all. If nothing else, I know there are few folks out there who I have touched, and shaped how they see, use, and allow technology in their lives (cause they told me so).
Through my storytelling on API Evangelist, I am always looking for the next convert–even if it takes years and hundreds of stories. A significant portion of this outreach involves telling stories that reach my intended audience–usually startups, business, institutional, and government agency workers and influencers. To reach them I need to tell stories that speak to them, and feed their current goals around finding success in their startup, or their role within businesses, institutions, and government agencies. With this in mind, I am always trying to bend my stories in their direction, talking about topics that they’ll care about, and tune into.
Once I have their attention, I will work on them in other ways. I’ll help them think about their business model, but also help them understand transparency and communication when it comes to executing this model. I will help them understand the best practices for managing an API using open source solutions like Tyk or Dreamfactory, and the leading approaches to using Runscope for monitoring and testing, while also encouraging them to me more observable with these practices. Making sure companies tell stories about what they are doing, and how they are doing it all–the good and bad.
I’m always working to build bridges to folks who might not see this whole API thing like I do. I’d say that many of these bridges will never get fully walked across by my target audience, but when someone does, and my stories influence the way they see or use technology even a little bit–mission accomplished. I’m constantly testing new ways or reaching out, speaking in the language of my target audience (without selling out), using trendy terms like microservices, devops, and serverless, but this isn’t just about following the latest fad. It is meant to capture your attention, build some trust, and then when it matters I can share some information about what really matters in all of this–in hopes of influencing how you see technology, and how it can be used a little more sensibly, securely, or maybe not even at all. ;-)
My friend Matthew Reinbold, formerly of Vox Pop, and now the Lead for the Capital One API Center of Excellence, as well as the maintainer of web API events has shifted his blogging platform to use Github, using Jekyll. Ok, yawn, why is this news? Someone is shifting the underlying platform for their blog. Well, first Matt is one of the leading API practitioners in the space, who is also a storyteller. Second, his approach highlights a set of tools that other API providers should be considering for their API communications pipeline.
Matt is using a pretty potent formula for his communications platform in my opinion, with a handful of essential ingredients:
- Github - Using a Github repository as the open source folder for your website.
- Github Pages - Using Github Pages to publish the front-end for your website.
- Jekyll - The content management system that sits in the folder for your website.
- CloudFlare - The DNS and SSL front-end for your website, complete with analytics.
- Hover - The registrar for the domain which you offload DNS management to CloudFlare.
Matt is taking advantage of the benefits of static website development, which some of the benefits are, as Matt describes:
- Security - While not so much an issue with my own coded CMS, I lived in constant fear of missing a zero-day Wordpress exploit patch and finding myself, along with clients, compromised. Reducing the number of moving parts significantly decreases the places where something might go wrong.
- Hosting - Rather than having to find, research, and deploy to increasingly rare ColdFusion hosts (or port to another language), I can post my content to anywhere that supports HTTP/JS/CSS. hosting. This becomes very compelling given that Github Pages, one option, is free.
This is the cheapest and quickest way for your API to get a blog stood up, and get publishing stories about the value your API is bringing to the table. This approach isn’t just limited to your developer portal or engineering team blog, this could be for partners, or any API related project that you are running. I publish a static Jekyll blog for each area of my research, and I try to always have one for each of my data, or API tooling project–telling the story of each project that is independent from the API Evangelist blog, providing a static log of everything that has happened.
Github isn’t just a pipeline for code, it can be a pipeline for your communications and storytelling. It also can be a pipeline for your documentation, how-to-guides, and other resources. I’m happy to see Matt putting it to be use. Another thing I like about his post, other than him mentioning me ;-), is that he also mentioned the benefits of this approach over using Medium, which is something I’ve been advising API providers against for some time. In my opinion you are better off publishing your blog like Matt has, and then syndicating to Medium if you want. There is a lot more detail available on Matt’s story behind his new blog strategy, I recommend heading over and learning from what he’s done.
Communicating effectively around API operations is the number one illness I see across the API space. Engineers are good at writing code and devopping their way to a usable API, but often fall short when it comes to telling the story of what the API does, and consistently beating this drum until people become familiar with what is going on.
An effective API communication strategy is more art than it is science, and I’d like to share three of my rules when it comes to telling stories on the API Evangelist platform.
- Honesty - Be honest with yourself, you’re readers, and those you are writing about. If you can’t find a way to be honest in your writing go find a new job–it won’t be sustainable.
- Consistent - Communicate every day. Ok, maybe every other day. Regardless of frequency, make sure you are communicating on a consistent basis, setting the tone for what your audience can expect.
- Compelling - Make it compelling. No, not every single post will be compelling, but make it your primary goal to tell a compelling story that you would read yourself, if it was on someone else’s blog.
That is it. Don’t sweat all the technical details. Just write on the blog, spend the time on Twitter, participate in threads on Github, and regularly dive into the bowels of the Slack. Don’t spend all your time worrying about your communication strategy, just make sure you give it a sensible amount of time, and follow these three rules–the rest will come.
As of this moment, there are 2,680 blog posts on API Evangelist, with the first entry in September 2010. These three rules have kept me on track when I was taking money from bigcos like Intel and Mulesoft, and kept me from losing my shit when I was traveling and drinking too heavily. These three rules are what keep me doing this effectively after seven years.
There are never enough hours in the day. I have an ever growing queue of APIs and API related services that I need to play with for the first time, or just make sure and take another look at. I was FINALLY making time to take another look at the RepreZen API Studio again when I saw that they were now supporting OpenAPI 3.0.
I am still driving it around the block, but I thought the second email I got from them when I was signing up was worth writing about. I had received a pretty standard getting started email from them, but then I got a second email from Miles Daffin, their product manager, reminding me that I can reach out, and providing me with a “Yes I Would Like To Talk Button”. I know, another pretty obvious thing, but you’d be surprised how a little thing like this can actually break us from our regular isolated workspace, and make the people behind an API, or API related service more accessible. The email was pretty concise and simple, but what caught my eye when I scanned was the button.
Anyways, just a small potential building block for your API communication strategy. I’ll be adding the list I am cultivating. I’m not a big hard sell kind of guy, and I appreciate soft outreach like this–leaving it up to me when I want to connect. I’ll keep playing with RepreZen API Studio and report back when I have anything worth sharing. I just wanted to make sure this type of signup email was included in my API communication research.
I process a lot of stories each week, which I do not think is at all unique. While I tend to read short, medium, and longer form pieces, I notice that people tend to tune into my shorter, more concise pieces. I’m an aggregator, analyst, so people probably are looking to me to understand what is going on and in turn I’m looking for individual API providers and service providers to help me keep in tune with what is going on with their operations–I depend on blog posts, change logs, and other common building blocks to do my work.
One recommendation I have for API providers and service providers when it comes to their communication strategies is to provide short concise blog posts regarding specific goings on. Make your blog posts like your API resources–doing one thing and doing it well. You can still do a round-up at the end of the week providing an executive summary, but don’t cut out the short individual blog posts. In my experience, people tend to read titles, tweets, and don’t have much attention span beyond 300 to 500 words. Personally, if I am busy, the first thing I cut out each week is the lengthy weekly roundups from providers–I will scan, but really do not read much of the detail if something catches my eyes.
This advice isn’t for other aggregators and analysts. Your job is to round up and provide and overview of what is going on. My advice is for individual API providers looking to update everyone with what is going on with their API operations, services, tooling, customers, and other common things you should be evangelizing and communicating as part of your regular operations. This is just some feedback from someone who is passionate about consuming as much information as I possibly can each week. Many short stories are better than just a single round-up, and you tend to get better search and social media bang for your buck when you have well-crafted titles, and a short body, that focuses on a single topic. Think of your API communication strategy similar to your microservices approach and I think you’ll get the reach you are looking for.
Amazon Web Service teams sure have been rocking their architectural icons across their storytelling lately. They standardized a set of icons for each of their cloud services and published in a variety of formats as the AWS Simple Icons for Architecture Diagrams. I am a big fan of the Noun Project API for use across my storytelling and find that having a standardized library of meaningful images and icons to be extremely valuable in helping quickly convey meaning (or entertain).
I was reading optimizing Amazon S3 for high concurrency in distributed workloads from AWS, and the diagram they provided, daisy chaining each of the AWS services at play, really brought the concept home for me. I read a lot, but I also scan a lot, and meaningful diagrams like this can go a long way to help me get up to speed as quickly as possible.
I have been an advocate for establishing icon sets for common API technologies, and even service providers, and I think I will add individual API resources to the stack. It would be valuable to have icon sets for common API resources like images, video, storage, etc. Icons that spoke to what they did, but also clearly identifies them as an API resource and allowing them to possibly be daisy chained together like Amazon does.
API industry icons will have to wait until some benefactor steps up to invest in this crazy idea. I'm graphically challenged, I know what looks good, but I can't craft anything graphical to save my life--look at my logo. Even if we don't have an industry-wide set of icons, it might be something individual API providers would want to consider creating for their API resources, like Amazon does. It is something that could help make your storytelling more impactful, and provide a common set of icons for everyone to use when referencing specific API resources.
If you think there is a link I should have listed here feel free to tweet it at me, or submit as a Github issue. Even though I do this full time, I'm still a one person show, and I miss quite a bit, and depend on my network to help me know what is going on.