API Support News

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.

Please Refer The Engineer From Your API Team To This Story

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

One of the API providers I reached out to recently responded with this, “I spoke with one of our engineers and he asked me to refer you to https://developer.[company].com/”. Ok. First, I spend over 30 minutes there just the other day. Learning about what you do, reading through documentation, and thinking about what was possible–which I referenced in my email. At this point I’m guessing that the engineer in question doesn’t know what an OpenAPI or Postman Collection is, they do not understand the impact these specifications are having on the wider API ecosystem, and lastly, I’m guessing they don’t have any idea who I am(ego taking control). All of which provides me with the signals I need to make an assessment of where any API is in their overall journey. Demonstrating to me that they have a long ways to go when it comes to understanding the wider API landscape in which they are operating in, and they are too busy to really come out of their engineering box and help their API consumers truly be successful in integrating with their platform.

I see this a lot. It isn’t that I expect everyone to understand what OpenAPI and Postman Collections are, or even know who I am. However, I do expect people doing APIs to come out of their boxes a little bit, and be willing to maybe Google a topic before responding to question, or maybe Google the name of the person they are responding to. I don’t use a address to communicate, I am using, and if you are using a solution like Clearbit, or other business intelligence solution, you should always be retrieving some basic details about who you are communicating with, before you ever respond. That is, you do all of this kind of stuff if you are truly serious about operating your API, helping your API consumers be more successful, and taking the time to provide them with the resources they need along the way–things like an OpenAPI, or Postman Collections.

Ok, so why was this response so inadequate?

  • No API Team Present - It shows me that your company doesn’t have any humans their to support the humans that will be using your API. My email went from general support, to a backend engineer who doesn’t care about who I am, and about what I need. This is a sign of what the future will hold if I actually bake their API into my applications–I don’t need my questions lost between support and engineering, with no dedicated API team to talk to.
  • No Business Intelligence - It shows me that your company has put zero thought into the API business model, on-boarding, and support process. Which means you do not have a feedback loop established for your platform, and your API will always be deficient of the nutrients it needs to grow. Always make sure you conduct a lookup based upon on the domain, or Twitter handle or your consumers to get the context you need to understand who you are talking to.
  • Stuck In Your Bubble - You aren’t aware of the wider API community, and the impact OpenAPI, and Postman are having on the on-boarding, documentation, and other stops along the API lifecycle. Which means you probably aren’t going to keep your platform evolving with where things are headed.

Ok, so why should you have an OpenAPI and Postman Collection?

  • Reduce Onboarding Friction - As a developer I won’t always have the time to spend absorbing your documentation. Let me import your OpenAPI or Postman Collection into my client tooling of choice, register for a key and begin making API calls in seconds, or minutes. Make learning about your API a hands on experience, something I’m not going to get from your static documentation.
  • Interactive API Documentation - Having a machine readable definition for your API allows you to easily keep your documentation up to date, and make it a more interactive experience. Rather than just reading your API documentation, I should be able to make calls, see responses, errors, and other elements I will need to truly understand what you do. There are plenty of open source interactive API documentation solutions that are driven by OpenAPI and Postman, but you’d know this if you were aware of the wider landscape.
  • Generate SDKs, and Other Code - Please do not make me hand code the integration with each of your API endpoints, crafting each request and response manually. Allow me to autogenerate the most mundane aspects of integration, allowing OpenAPI and Postman Collection to act as the integration contract.
  • Discovery - Please don’t expect your potential consumers to always know about your company, and regularly return to your developer.[company].com portal. Please make your APIs portable so that they can be published in any directory, catalog, gallery, marketplace, and platform that I’m already using, and frequent as part of my daily activities. If you are in my Postman Client, I’m more likely to remember that you exist in my busy world.

These are just a few of the basics of why this type of response to my question was inadequate, and why you’d want to have OpenAPI and Postman Collections available. My experience on-boarding will be similar to that of other developers, it just happens that the application I’m developing are out of the normal range of web and mobile applications you have probably been thinking about when publishing your API. But this is why we do APIs, to reach the long tail users, and encourage innovate around our platforms. I just stepped up and gave 30 minutes of my time (now 60 minutes with this story) to learning about your platform, and pointing me to your developer.[company].com page was all you could muster in return?

Just like other developers will, if I can’t onboard with your API without friction, and I can’t tell if there is anyone home, and willing to give me the time of day when I have questions, I’m going to move on. There are other platforms that will accommodate me. The other downside of your response, and me moving on to another platform, is that now I’m not going to write about your API on my blog. Oh well? After eight years of blogging on APIs, and getting 5-10K page views per day, I can write about a topic or industry, and usually dominate the SEO landscape for that API search term(s) (ego still has control). But…I am moving on, no story to be told here. The best part of my job is there are always stories to be told somewhere else, and I get to just move on, and avoid the friction wherever possible when learning how to put APIs to work.

I just needed this single link to provide in response to my email response, before I moved on!

The Basics Of The VA API Feedback Loop

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

Current Seeds Of The VA API Feedback Loop Current the VA is supporting the VA API developer portal using GitHub Issues and email. I mentioned in my previous review of the VA API developer portal that the personal email addresses provided for email support should be generalized, sharing the load when it comes to email support for the platform. Next, I’d like to address the usage of GitHub issues for support, along with email, and step back to look at how this contributes to, or could possibly take away from the overall feedback loop for the VAPI API effort. Defining what the basics of an API feedback loop for the VA might be.

Expanding Upon The VA Usage Of GitHub Issues I support the usage of GitHub issues for public support of any API related project. It provides a simple, observable way for anyone to get support around the VA APIs. While I’m guessing it was accidental, I like the specialization of the current repo, and usage of GitHub issues, and that it being dedicated to VA API clients and their needs. I’d encourage this type of continued focus when it comes to establishing additional feedback loops, keeping them dedicated to a specific aspect of operating on the VA API platform. It is something that might seem a little messy at first, but could easily be managed with the proper strategy, and usage of GitHub APIs, which I’ll highlight below.

Makes API Operations More Public And Observable One of the most important reasons for using GitHub as the cornerstone of the VA API feedback loop is that it allows for transparent, observable, auditable operation of the feedback loop across the VA API platform. One of the critical aspects of the overall health of the VA API platform in the future, will be feedback loops being as open as they possibly can. Of course, there are some feedback loops that should remain private, which GitHub issues can accommodate, but whenever possible the feedback loop for the VA API platform should be in the public domain, allowing all stakeholders, veterans, and the public to actively participate in the process. In a way that can ensures every aspect of API operations is documented, and auditable, providing as much accountability as possible across VA API operations.

Allowing For More Modular Organization Of Feedback Loops Using GitHub Issues for the deployment, management, and organization of more modular feedback loops. Treating your feedback loops just as you would your APIs, making them small, meaningful, and doing one thing and doing it well. Any GitHub repository can have its own GitHub Issues, allowing for the deployment of specialized feedback loops based upon single project that are part of different organizational groups. Beyond the modularity available when you leverage GitHub repositories, and organize them within GitHub Organizations, Github Issues can also be tagged, allowing for even more meaningful organization of feedback as it comes in, tagging and bagging for consideration as part of the road map, and other decision making processes that will be feeding off the VA API platform’s feedback loop.

Enabling Feedback Loop Automation With The GitHub API Another benefit of using GitHub Issues as an API feedback loop building block, is that they also have an API. Allowing for the automation of all aspects of the VA API platform feedback loop(s). The GitHub API can be used to aggregate, automate, audit, and work with the Github Issues for any GitHub organization and repo the VA has access to. Providing the ability to manage not just the Github Issues for a single GitHub repository, but for the orchestration of feedback loops across many different GitHub repositories, managed by many different GitHub organizations. Establishing a distributed feedback loop system in which VA API leadership can use to coordinate with different internal, agency, partner, vendor, or public stakeholder(s) at scale, across many different projects, and components of the VA API platform.

Augmenting Public Feedback With Private Github Repos While it is critical that as many of the feedback loops across the VA API platform are publicly accessible, and observable by everyone as possible, it is also important that there are private channels for communication around some of the components of the platform. This is another reason why GitHub Issues can work as a building block for not just public feedback loops, but also being able to operate feedback loops as well. Taking advantage of private repositories when it comes to establishing modular, automated, and private conversations to occur around certain VA API platform projects. Balancing the public aspects of the platform, with feedback loops amongst trusted groups, while still leveraging GitHub for delivering the identity and access management aspects of governing private VA feedback loops.

Extending Private GitHub Repos With Email Support Beyond the private GitHub repositories, and using their issues to facilitate private conversations, it always makes sense to have a generalized and dedicated email account as part of the feedback loop for any API platform. Providing another private, but also a vendor neutral way of supporting the platform. People just are familiar with email, and it makes sense to have a general account that is managed by many individuals who are coordinating around platform operations. Make it easy to provide feedback around the API the VA API operations, and support anyone participating within the VA API ecosystem.

Auditing, Documenting, And Reporting Upon The VA Feedback Loop I suggested in my review of the VA API platform that email should be standardized and delivered via a dedicated email account, so that multiple stakeholders can participate in support of the platform from a VA operational perspective. This way emails can be tagged, organized, and archived in support of the larger VA API feedback loop. Making sure all questions get answered, and that they are also contributed to the evolution of the platform. Something that can also be done via the automation described earlier using the GitHub API. Allowing all threads, across any project and organization to be audited, documented, and reported upon across all VA API operations. Ensuring that their is transparency, observability, and accountability across the VA API platform feedback loop.

Have A Strategy In Place For The VA API Feedback Loop GitHub Issues and email are the two basic building blocks of any API platform, and I support the VA starting their official journey here. I think GitHub makes for an essential building block of any API platform, when used right. It just helps to have a plan in place for when a repo’s GitHub is included in the overall feedback loop framework, and the organization and prioritization of the conversation going on there. GitHub Issues spread across many different GitHub repositories, without any real strategy to how they are organized, tagged, and engaged with can seem overwhelming, and become a mess. However, with a little planning, and the establishment of even the most basic approach to managing them, can help develop a pretty robust feedback loop across the VA API platform, that follows the lead of how open source software gets delivered.

Consider Other API Feedback Loop Building Blocks I wanted to keep this post just about the basics of the feedback loop for the VA, or for any API platform–GitHub Issues, and email. However, I’d also like suggest the consideration of some other building blocks, to help augment GitHub Issues, providing some other direct, and indirect approaches to operating the VA API platform feedback loop:

  • FAQ - Providing a frequently asked question that is an aggregate of all the questions that get asked across the GitHub issues, and via email.
  • Newsletter - Providing a regular channel for updating platform stakeholders, via a structured email newsletter. Offering up private, and public editions, targeting different groups.
  • Road Map - Publishing a road map regarding what is getting built across all projects included within the VA API platform perimeter, aggregating GitHub Issues that evolve as part of the feedback loop and get tagged as milestones for adding to the road map.

I’m always hesitant to make suggestions about where to go next, when an organization is just getting started on their API journey. However, I think the VA team knows when to ignore my advice, and when they can cherry pick the things they want to include in their strategy. I just want to make sure I provide as much constructive criticism about what is there, and constructive feedback around what can be invested in next.

Hopefully this post provides a basic overview of the VA API platform feedback loop. Expands on what they are already doing, but shines a light on some of the positive aspects of using GitHub for the VA API platform feedback loop. I was the one who worked with the former VA CIO Marina Martin (@MarinaNitze) to get the the VA GitHub organization setup back in 2013. So it makes me happy to see it being used as a cornerstone of the VA API platform. I am happy to give feedback on how they can continue to put the powerful platform to such good use.

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

I do not like email. I do not have a good relationship with my inbox. However, it is one of those ubiquitous tools I have to use, and understand the value it can bring to my world. The goal is to not let my inbox control me too much, as my it is is often a task list that other people think they can control. With all that said, I’m finding renewed value in email newsletters, on several fronts. While I’d prefer to get updates via Atom, I’m warming up to receiving updates from API providers, and API service providers in my inbox.

I am an active subscriber to the REST API Notes Newsletter, API Developer Weekly, and other relative newsletters. I’m also finding myself opening up more emails from the API providers, and service providers I’m registered with. Historically, I often see email as a nuisance, but I’m beginning to see emails from the companies I’m paying attention to as a healthy signal. Increasingly, it is a signal that I’m using to understand the overall health of a platform, and yet another signal that will go silent when a platform isn’t supporting their user base, and potentially running out of funding for their operations.

I recently wrote a script that harvests emails from my inbox, and tracks on the communications occurring with API providers and service providers I am monitoring. At it’s most basic, it is a heartbeat that I can use to tell when an API provider or service provider is still alive. After that, I’m looking at harvest URLs, and other data, and use the signals to float an API provider or service provider up on my list. It can be tough to remember to tune into what is going on across hundreds and thousands of APIs, and any signal I can harvest to help companies float up is a positive thing. Hopefully it is something that will also incentivize API provider and service providers to tell more stories via email, as well as their blog and social media.

Email is still one of my least favorite signals out there, but I’m beginning to realize there is still a lot of value to be found within my inbox. Having a regular newsletter is something I’m going to write about more, encouraging more API providers and service providers to provide. I think more companies, institutions, and government agencies feel comfortable telling stories via email, over a public blog. It may not be my preferred medium of choice, but I know that it takes a diverse set of channels to reach a large audience, and who am I to only use the ones I like the most.

SendGrid Managing Their OpenAPI Using Github

This is a post that has been in my API notebook for quite a while. I feel it is important to keep showcasing the growing number of API providers who are not just using OpenAPI, but also managing them on Github, so I had to make the time to talk about the email API provider SendGrid managing their OpenAPI using Github. Adding to the stack of top tier API providers managing their API definitions in this way.

SendGrid is managing announcements around their OpenAPI definition using Github, allowing developers to signup for email notifications around releases and breaking changes. You can use the Github repository to stay in tune with the API roadmap, and contribute feature requests, submit bug reports, and even submit a pull request with the changes you’d like to see. Going beyond just an API definition being about API documentation, and actually driving the API road map and feedback loop.

This approach to managing an API definition, while also making it a centerpiece of the feedback loop with your community is why I keep beating this drum, and showcasing API providers who are doing this. It is a way to manage the central API contract, where the platform provider and API consumers both have a voice, and producing a machine readable artifact that can be then used across the API lifecycle, from design to deprecation. Elevating the API definition beyond just a bi-product of creating API docs, and making it a central actor in everything that occurs as part of API operations.

I’m still struggling with convincing API providers that they should be adopting OpenAPI. That it is much more than an artifact driving interactive documentation. Showcasing companies like SendGrid using OpenAPI, as well as their usage of Github, is an important part of me convincing other API providers to do the same. If you want me to write about your API, and what you are working to accomplish with your API resources, then publish your OpenAPI definition to Github, and engage with your community there. It may take me a few months, but eventually I will get around to writing it up, and incorporating your story into my toolbox for changing behavior in our API community.

API Transit Basics: Support

This is a series of stories I’m doing as part of my API Transit work, trying to map out a simple journey that some of my clients can take to rethink some of the basics of their API strategy. I’m using a subway map visual, and experience to help map out the journey, which I’m calling API transit–leveraging the verb form of transit, to describe what every API should go through.

Beyond communication, make sure there is adequate support across API teams, and the services, tooling, and processes involved with operations. If an API goes unsupported, it might as well not exist at all, making standardized, comprehensive support practices essential. Every API should have an owner, with a contact information published as part of all API definitions. Ideally, every API owner has a backup point of contact to go to if someone should leave a company, or is out sick.

Similar to the communications stop along this journey, there a handful of common support building blocks you see present within the leading API pioneers portals. These are the four I recommend baking in by default to all of your API portals, and anywhere API discovery and documentation exists.

  • Email - Make sure there is support available via email channels, with a responsive individual on the other end–with accountability.
  • Tickets - Consider a ticketing system for submitting and supporting requests around API operations.
  • Dedicated - Identify one, or many individuals who can act as internal, partner, and public support when it makes sense.
  • Office Hours - Consider one time a week where there is a human being available in person, or online to answer direct question.

Every single API should have a support element present as part of its operations. Each API definition allows for the inclusion of responsible point of contact via email, and other channels–make use of it. Support should be baked into each API’s definition, making it accessible across the API lifecycle, in a machine readable way. Ideally, every API developer provides support for their own work, bringing them closer to how their solutions are working, or not working for consumers.

API support isn’t rocket surgery, but will make or break your API operations if not done well. The APIs that perform the best, will have strong support behind them. The APIs that go dormant, or aren’t reliable will not have proper support. Developers do not think about support by default, which means it will often go overlooked unless a more senior developer, business user, or manager steps up. This is why API operations is a team sport, because there are different skill levels, and personalities at play, and while proper support won’t be everyone’s strength, it is something everyone should be responsible for.

Api Transit Basics Support

404: Not Found

From CI/CD To A Continuous Everything (CE) Workflow

I am evaluating an existing continuous integration and deployment workflow to make recommendations regarding how they can evolve to service their growing API lifecycle. This is an area of my research that spans multiple areas of my work, but I tend to house under what I call API orchestration. I try to always step back and look at an evolving area of the tech space as part of the big picture, and attempt to look beyond any individual company, or even the wider industry hype in place that is moving something forward. I see the clear technical benefits of CI/CD, and I see the business benefits of it as well, but I haven’t always been convinced of it as a standalone thing, and have spent the last couple of years trying understand how it fits into the bigger picture.

As I’ve been consulting with several enterprise groups working to adopt a CI/CD mindset, and having similar conversations with government agencies, I’m beginning to see the bigger picture of “continuous”, and starting to decouple it from just deployment and even integration. The first thing that is assumed, not always evident for newbies, but is always a default–is testing. You alway test before you integrate or deploy, right? As I watch groups adopt I’m seeing them struggle with making sure there are other things I feel are an obvious part of the API lifecycle, but aren’t default in a CI/CD mindset, but quickly are being plugged in–things like security, licensing, documentation, discovery, support, communications, etc. In the end, I think us technologists are good at focusing on the tech innovations, but often move right past many of the other things that are essential for the business world. I see this happening with containers, microservices, Kubernetes, Kafka, and other fast moving trends.

I guess the point I want to make is that there is more to a pipeline than just deployment, integration, and testing. We need to make sure that documentation, discovery, security, and other essentials are baked in by default. Otherwise us techies might be continuously forgetting about these aspects, and the newbies might be continuously frustrated that these things aren’t present. We need to make sure we are continuously documenting, continuously securing, and continuously communicating around training, and our continuously evolving (and sharing) our road maps. I’m sure what I’m saying isn’t anything new for the CI/CD veterans, but I’m trying to onboard new folks with the concept, and as with most areas of the tech sector I find the naming and on-boarding materials fairly deficient in possessing all the concepts large organizations are needing to make the shift.

I’m thinking I’m going to be merging my API orchestration (CI/CD) research with my overall API lifecycle research, thinking deeply about how everything from definition to deprecation fits into the pipeline. I feel like CI/CD has been highly focused on the technology of evolving how we deploy and integrate (rightfully so) for some time now, and with adoption expanding we need to zoom out and think about everything else organizations will need to be successful. I see CI/CD as being essential to decoupling the monolith, and changing culture at some of the large organizations I’m working with. I want these folks to be successful, and not fall into the trappings of only thinking about the tech, but also consider the business and political implications involved with being able to move from annual or quarterly deployments and integrations, to where they can do things in weeks, or even days.

Disaster API Rate Limit Considerations

This API operations consideration won’t apply to every API, but for APIs that provide essential resources in a time of need, I wanted to highlight an API rate limit cry for help that came across my desk this weekend. Our friend over at Pinboard alerted me to someone in Texas asking for some help in getting Google to increase the Google Maps API rate limits for an app they were depending on as Hurricane Harvey:

The app they depended on had ceased working and was showing a Google Maps API rate limit error, and they were trying to get the attention of Google to help increase usage limits. As Pinboard points out, it would be nice if Google had more direct support channels to make requests like this, but it would be also great if API providers were monitoring API usage, aware of applications serving geographic locations being impacted, and would relax API rate limiting on their own. There are many reasons API providers leverage their API management infrastructure to make rate limit exceptions and natural disasters seems like it should be top of the list.

I don’t think API providers are being malicious with rate limits in this area. I just think it is yet another area where technologists are blind to the way technology is making an impact (positive or negative) on the world around us. Staying in tune to the needs of applications that help people in their time of need seems like it will have to components, 1) knowing your applications (you should be doing this anyways) and identifying the ones that have a public service, and 2) staying in tune with natural and other disasters that are happening around the world. We see larger platforms like Facebook and Twitter rolling out permanent solutions to assist communities in their times of needs, and it seems like something that other smaller platforms should be tuning into as well.

Disaster support and considerations will be an area of API operations I’m going to consider adding into my research, and spending more time to identify best practices, and what platforms are doing to better serve communities in a time of need using APIs.

The Importance Of API Stories

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.

API Platform FAQ And QA Responsibility

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.

The Plivo Support Portal And Knowledge Base

I’m always watching out for how existing API providers are shifting up their support strategies in their communities as part of my work. This means staying into tune with their communications, which includes processing their email newsletters and developer updates. Staying aware of what is actually working, and what is not working, based upon active API service providers who are finding ways to make it all work.

Plivo opted out to phase out direct emails at the end of the month, and pushing developers to use the Plivo support portal, and the ticketing system. The support portal provides a knowledge base which provides a base of self-service support before any developer actually uses the support ticketing system to:

  • Create, manage, respond to and check the status of your support ticket(s)
  • Select improved ticket categories for more efficient ticket routing and faster resolution
  • Receive resolution suggestions from our knowledge base before you submit a ticket to help decrease resolution time

Email only support isn’t always the most optimal way of handling support, and using a ticketing system definitely provides a nice trail to follow for both sides of the conversations. The central ticketing system also provides a nice source of content to feed into the self-service support knowledge base, keeping self-service support in sync with direct support activity.

I’m going to continue to track on which API providers offer a ticketing solution, as well as a knowledge base. I’m feeling like these are what I’m going to recommend to new API providers as what I consider to be default support building blocks that EVERY API platform should be starting with, covering the self-service and direct support requirements of a platform. I’m going to start pushing 1-3 support solutions like ZenDesk, also giving API providers some options when it comes to quickly delivering adequate support for their platforms.

Tweeting Out Your API Forum Conversations

It is a lot of work to keep the API evangelism drumbeat going each day on your blog, Twitter, and other social media channels you use for your API operations. Each Tweet, Facebook or LinkedIn Post is one possible signal that might reach existing developers, or possibly reach a potentially new API consumer–educating them about what your API does.

My friends over at the Oxford Dictionaries APIs are getting really good at this API evangelism song and dance, and one of the tactics in their toolbox is regularly Tweeting out relevant threads from their API forum. It is a great way to expose conversations that are going on within your API support forum, and help make other developers aware that these conversations are going on in a way that will also boost your overall SEO, making your API support operations more visible to the public.

Another benefit of sending out these regular API signals is that there is always the potential that I will write up what you are doing, and you’ll get the additional exposure of being on API Evangelist. When people ask me what is the #1 thing they can do to be more successful with evangelism for their API, it is always consistency. Regular, consistent drumbeats about what is going on with your platform, the problems it solves is always the best way to make sure your valuable API resources will be found and put to use in meaningful ways.

The Support Elements Of Your API Service Level Agreement

Zendesk gave me some valuable building blocks to add to both my API support and API service level agreement research, with their support SLA. This is why I keep an eye on not just how API providers are handling their support, but also how leading support software as a service API providers are setting the bar for how we do support.

The Zendesk support SLA provides us with some valuable information about setting a service level objective, developing support SLA workflow, dealing with a breach, and even some key performance indicators (KPIs) to help you measure success. I will be taking the bullet points from each area and adding to the overlap of my API support and service level research, and I’ll even begin flushing out my API breach research with its first handful of building blocks regarding how to handle a really bad situation.

I’m seeing an uptick in the number of SLAs with leading API providers, so it makes sense to start considering how other aspects of API operations should be reflected in our API service level agreements. How you support and communicate with your customers can be just as important as the technical bullets of your SLA. Most of the SLAs I’ve read in the API space focus on the technical, business, and legal considerations of integration, but Zendesk reminds us of the actual human elements of setting and meeting a specific level of service when it comes to API integration.

The Depth And Dimensions Of Monitoring API Operations

When I play with my Hitch service I am always left thinking about the many dimensions of API monitoring. When you talk about API monitoring in the tech sector conversations almost always start with the API providers and the technical details monitoring of individual APIs. Hopefully, these discussions also focus on API monitoring from the API consumers point of view, but I wanted to also shine a light on companies like Hitch who are adding an additional dimension from the API service provider view of things–which is closer to my vantage point as an analyst.

I am an advisor to Hitch because they are a different breed of API monitoring service, that isn’t just focused on the APIs. Hitch brings in the wider view of monitoring the entire operations of an API–if documentation changes, an SDK on Github, or update via Twitter, or a pricing change, you get alerted. As a developer I enjoy being made aware of what is going on across operations, keeping me in tune with not just the technical, but also the business and politics of API platform operations.

Another reason I like Hitch, and really the reason behind me writing this post, is that they are helping API providers think about the bigger picture of API monitoring. Helping them think deeply, as well as getting their shit together when it comes to regularly sending out the critical signals us API consumers are tuning into. When you are down in the trenches of operating an API at a large company, it is easy to get caught up in the internal vacuum, forgetting to properly communicate and support your community–Hitch helps keep this bubble from forming, assisting you in keeping an external focus on your community.

If you are just embarking on your API journey I recommend tuning into API Evangelist first. ;-) However, if you are unsure of how to properly communicate and support your community I recommend you talk to the Hitch team. They’ll help get you up to speed on the best practices when it comes to API operations, and understand how to send the right signals to your community–something that will make or break your API efforts, so please don’t ignore it.

Disclosure: I am an advisor for Hitch, and they are my friends.

Heavier Investment In API Training Will Be Necessary


I was learning about the virtual classes that Github are offering, as I was working on some basic API curriculum for some of my clients, and I was reminded of how important training and education is when it comes to technological adoption. Not everyone learns the same way, and not everyone is an autodidact, and providing training around any technology, platform, or service your company, institution, or government agency is adopting is important.

If you look at the historic spending of leading API companies like Apigee, you’ll see a large chunk of the budget going to educating and bringing would be or existing clients up to speed with the technology in play. Training and education will be a significant portion of each of the trends you see in play like DevOps, Microservices, and Serverless. A core aspect of all of these movements hinges on unwinding legacy technical debt and moving often large groups of people forward with a new way of doing things–if education isn’t a significant portion of your strategy, you will fail.

If you see any interesting API training out there on LinkedIn (Lynda), or on the open web, please let me know, I’d like to start curating more resources for people to use. I am also working with groups to develop their own internal API training and curriculum to match not just the wider API space, but also what is going on internally within an organization. In coming months I will also be going through each of my research areas that might help API providers think about how they are going to tackle API education and help my readers understand that a heavier investment in API training will be necessary to steer the ship where you want it to go.

Google Support Buttons

I talked about the gap between developer relations and support at Google, something that Sam Ramji (@sramji) has acknowledged is being worked on. Support for a single API can be a lot of work and is something that is exponentially harder with each API and developer to add to your operations, and after looking through 75 of the Google APIs this weekend, you see evidence that Google is working on it.

While there are many Google APIs that still have sub-standard support for their APIs, when you look at Google Sheets you start seeing evidence of their evolved approach to support, with a consistent set of buttons that tackle many of the common areas of API support. For general questions, Google provides two buttons linked to StackOverflow:

The search just drops you into Stack Overflow, with the tag "google sheets api", and the ask a new question drops you into the Stack Overflow submit new question form. For bug reporting, they provide a similar set of buttons:

The search and report bug buttons drop you into the Google Code issues page for Google Sheets, leveraging the issues management for the Gooogle Code repository--something that can just as easily be done with Github issues. Then lastly, they provide a third set of buttons when you are looking to submit a feature:

Even though there is a typo on the first button, they also leverage Google Code issue management to handle all feature requests. Obviously working to centralize bug and feature reporting, and support management using Google Code--something I do across all my API projects using Github organizations, repositories, and their issue management. I'm guessing Google Support is tapping into Google Code to tackle support across projects at scale.

These support buttons may seem trivial, but they represent a more consistent approach by the API giant to be consistent in how they approach support across their API offerings--something that can go a long way in my experience. It gives your API consumers a familiar and intuitive way to ask questions, submit bugs, and suggest new features. Equally as important, I'm hoping it is also giving Google a consistent way to tackle support for their APIs in a meaningful way, that meets the needs of their API consumers.

The Relationship Between Dev Relations And Support

I saw an interesting chasm emerge while at a Google Community Summit this last week, while I heard their support team talk, as well as their developer relations team discuss what they were up to. During the discussion, one of the companies presents discussed how their overall experience with the developer relations team has been amazing, their experience with support has widely been a pretty bad experience--revealing a potential gap between the two teams.

This is a pretty common gap I've seen with many other API platforms. The developer relations team is all about getting the word out, and encouraging platform usage and support teams are there to be the front line for support and being the buffer between integration, and platform engineering teams. I've been the person in the role as the evangelist when there is a bug in an API, and I'm at the mercy of an already overloaded engineering team, and QA staff, before anything gets resolved--this is a difficult position to be in.

How wide this chasm becomes ultimately depends on how much of a priority the API is for an engineering team, and how overloaded they are. I've worked on projects where this chasm is pretty wide, taking days, even weeks to get bugs fixed. I'm guessing this is something a more DevOps focused approach to the API life cycle might help with, where an API developer relations and support team have more access to making changes and fixing bugs--something that has to be pretty difficult to deal with at Google scale.

Anyways, I thought the potential chasm between developer relations and support was worthy enough to discuss and include in my research. It is something we all should be considering no matter how big or small our operations are. There is no quicker way to kill the morale of your API developer relations and support teams by allowing a canyon like this to persist. What challenges have you experienced when it comes to getting support from your API provider? Or inversely, what challenges have you faced supporting your APIs or executing on your developer outreach strategy? I'm curious if other folks are feeling this same pain.

All The Right Channel Icons In Support Of Your API Platform

I look at a lot of websites for companies who are providing APIs and selling services to the API space. When I find a new company, I can spend upwards of 10 minutes looking for all the relevant information I need to connect. Elements like where their Twitter and Github accounts are. These are all the key channels I am looking for so that I can better understand what a company does and stay in tune with any activity, but they are also the same channels that developers will be looking for so that they can stay in tune a platform as well.

I spend a great deal of time looking for these channels, so I'm always happy when I find companies who provide a near complete set of icons for all the channels that matter. Restlet, the API design, deployment, management,and testing platform has a nice example of this in action, providing the following channels:

  • Facebook
  • Twitter
  • Google+
  • LinkedIn
  • Vimeo
  • Slideshare
  • Github
  • Stack Overflow
  • Email

All of these channels are available as orderly icons in the footer of their site. Making my job easier, and I'm sure making it easier for other would be API developers. They also provide an email newsletter signup along with the set of icons. While this provides me with a nice set of channels to tune into, more than I usually find, I would still like to have a blog and atom feed icons, as well as maybe an AngelList or Crunchbase, so that i can peak behind the business curtain a little.

I know. I know. I am demanding, and never happy. I am just trying to provide an easy checklist for companies looking to do interesting things APIs of the common channels they should consider offering. You should only offer up channels that you can keep active, but I recommend that you think about offering up as many of these as you possibly can manage. No matter which ones you choose, make sure you organize them all together, in the header and footer of your website, so nobody has to go looking for them.

Every Government Agency Should Have An FAQ API Like The DOL

I wrote about my feelings that all government agencies should have a forms API like the Department of Labor (DOL), and I wanted to separately showcase their FAQ API, and say same thing--ALL government agencies should have a frequently asked question (FAQ) API. Think about the websites and mobile applications that would benefit from ALL government agencies at the federal, state, and local level having frequently asked questions available in this way--it would be huge. 

In a perfect world, like any good API provider, government agencies should also use their FAQ API to run their website(s), mobile, and internal systems--this way the results are always fresh, up to date, and answering the relevant questions (hopefully). I get folks in government questioning the opening up of sensitive information via APIs, but making FAQs available in a machine readable way, via the web, just makes sense in a digital world.

Like the forms API, I will be looking across other government agencies for any FAQ APIs. I will be crafting an OpenAPI Spec for the DOL FAQ API (man that is a lot of acronyms). I will take any other FAQ APIs that I find and consider any additional parameters, and definitions I might want to include in a common FAQ API definition for government agencies. This is another area that should have not just a common open API and underlying schemas defined, but also a wealth of server and client side code--so any government agency can immediately put it to work in any environment.

The Month At A Glance, Road Map, Support, And The Recent Posts For Your API Platform

I was playing with Microsoft's API Catalog, a tool to visualize and analyze the API overlap between standards specifications and type systems within browsers, and their footer caught my eye. I am always looking for quality examples of companies doing platform communications and support well, and I think their layout, and available building blocks in their footer, is worthy of showcasing.

For me, these numbers, and the available communication and support building blocks, send the right signals--that a platform is alive and active. These are the data points I tune into, to understand how well a platform is doing, or not doing. There are no absolutes when it comes to this type of monitoring, as anything can be gamed, but sign Github activity, road map evolution, and blog storytelling can provide a vital heartbeat for any healthy API platform. 

Managing The Support, Feedback, And Roadmap Using Github

Each of the Adopta.Agency project runs as a Github repository, with the main project site running using Github Pages. There are many reasons I do this, but one of the primary ones is that it provides me with most of what I need to provide support for the project.

Jekyll running on Github pages gives me the ability to have a blog, and manage the pages for the project, which is central to support. Next I use Github Issues for everything else. If anyone needs to ask a question, make a contribution, or report a bug, they can do so using Github Issues for the repository

I even drive the project road map, and change log using Github Issues. If I tag something as roadmap, it shows up on the road map, and if I tag something as changelog, and it is a closed issue, it will show up on the change log--this is the feedback loop that will help me move the clinical trials API forward.

Breaking Out API Support Into A Separate Research Area

Supporting your community is not unique to the API space, but supporting API operations does have some unique needs, and approaches that are proven by leading platforms. Like other areas of my research, I'm pulling out API support into its own area, so I can start shining a light on successful patterns I find in the area of API support.

Two things pushed me to spin out this research area. One, I was tagging more blog posts, and other resources as support, and without a dedicated research area, this information would rarely float to the surface for me. Two, my partners over at Cloud Elements have an API hub dedicated to "Help Desk". While their aggregate API solution is targeting beyond the API community, it is API driven, and can also be applied to providing an aggregate support solution for API communities.

As with most of the areas of the API space, there are several dimensions to how APIs are being applied to support customers, and online communities. With my research, I will focus on tracking on approaches to community support for API providers, and API service providers. There will also be that layer of tracking on help desk and support platforms who employ APIs, as well as API aggregate and API interoperability solutions from leaders (and my partners) in the space like Cloud Elements.

You can visit my API support research via its Github repository, and I will try to make sure and continue linking to it from my API management research, where it was born out of.

Update 265 Pages, and 175 Links On My Network To Support Swagger to OADF Shift

I have written 265 separate posts, across the API Evangelist network about Swagger, in the last three years. To reflect the recent shift of Swagger into the Open API Initiative (OAI), and the specification being reborn as Open API Definition Format (OADF), I wanted to update all the stories I've told over the years, to help educate my readers of the evolution, and provide the most relevant links possible.

Using my Linkrot API, which helps me manage the links across my network of sites, I've identified all the pages with Swagger relevant links, and made sure they are updated to point at the most recent material. I've also added a banner to each of the 265 posts, helping educate readers who come across these posts, regarding the transition from Swagger to OADF, and help them understand where to find the latest information.

My network of sites is meant to be my workbench for the API space, and provide the latest information possible about what drives the API sector. It is important to me that the information is as accurate as possible, and my readers stay in tune with the shifts of the APIs space, and where they can find what they need to be successful.

In the end though, all of this is really just business. 

Using Existing Online Forums vs Developing Your Own To Support API Operations

As I tune into the fallout around the Reddit community, I think it is a good time to pull a story out of my notebook, that I began writing a month or two ago. These thoughts are born out of my post Ask The Stack When You Need API Support, where my friend Jeremiah Lee (@JeremiahLee) commented, disagreeing with my recommendation that API providers use Stack Exchange as part of operations. 

Jeremiah shares his story about how hostile Stack Overflow can be (I'll let you read his comment on your own), something that has been re-enforced many times along the way. While I still endorse Stack Overflow as a valuable building block for some APIs, I completely agree with Jeremiah about the overall community tone. While Stack Overflow is definitely a different beast, it suffers from some of the similar systemic illnesses, that Reddit does. I find some very valuable information on Stack Overflow, which I use regularly, but if you are looking to develop an API community, I can envision the community potentially working against you, in several ways.

It really depends on your API, and the target audience you are trying to reach. Sometimes, the male dominated, "gamified community of meritocracy, where established members have many rules and politics", as Jermiah says, is exactly who you should be engaging, but you really need get to know the personae of your ideal customers, and decide on your own. For API Evangelist, both my storytelling, and the APIs I provide, I've long felt Stack Overflow is not my target audience.

Similar to Reddit, Hacker News, and DZone, I get very little value from these communities. While I do find nuggets of information at these places, I do not post my stories, and engage in conversations there, because the hostility that can come from these channels I have found outweighs any value they might bring in traffic. I seek a much wider audience, than the individuals who often dominate these tech hangouts.

I encourage you to think deeply about who you want to reach with your APIs, and while building your own community in your own wiki, forum, or other solution, might take a lot of time and work, it gives you greater control over the tone your forum takes--which might make the difference in attracting the right developer and business audience you seek.

@Broadcom, I Am Going To Need Your Switches To Support Virtualized Containers So I Can Deploy My Own APIs Too

While processing the news today over at API.Report, I came across a story about Broadcom delivering an API for managing their latest network infrastructure. The intersection of Software Defined Networking (SDN) and Application Programming Interface (API) is something I’m paying closer attention to lately. Hmmm. SDN + API = Brand New Bullshit Acronym? Meh. Onward, I just can’t slow down to care--{"packet keep moving"}.

At the networking level, I’m hearing Broadcom making a classic API infrastructure argument, "With the OpenNSL software platform, Broadcom is publishing APIs that map Broadcom's Software Development Kit (SDK) to an open north bound interface, enabling the integration of new applications and the ability to optimize switch hardware platforms.”, with examples of what you could build including "network monitoring, load balancing, service chaining, workload optimization and traffic engineering."

This new API driven approach to networking is available in the Broadcom Tomahawk and Trident II switches, looking to build up a developer community who can help deliver networking solutions, with Broadcom interested in giving, "users the freedom to control their technology, share their designs and boost application innovation.” Everything Broadcom is up to is in alignment with other valid Internet of Things (IoT) efforts I’m seeing across not just the networking arena, but almost any other physical object being connected to the Internet in 2015.

I think what Broadcom is doing, is very forward leaning effort, and providing native API support at the device level is definitely how you support “innovation” around your networking infrastructure. To keep in sync with the leading edge of the current API evolution as I'm seeing it, I would also recommend adding virtualized container support at the device level. As a developer I am thankful for the APIs that you are exposing, allowing me to develop custom solutions using your hardware, but I need you to take it one level further--I need to be able to deploy my own APIs using Docker, as well as working with your APIs, all running on your infrastructure.

I need your devices to support not just the web and mobile apps I will build around your around your hardware, and the API surface area you are providing with the new Tomahawk and Trident II switches, I need to also plugin my own microservice stack, and the microservices that vendors will be delivering to me. I need the next generation of switches to be API driven, but I also need to guarantee it is exactly the stack I need to achieve my networking objectives.

That concludes my intrusion into your road-map. I appreciate you even entertaining my ideas. I cannot share much more details on what I intend to do with your new SDN & API driven goodness, but if you work with me to let me innovate on your virtual and physical API stack—I feel that you will be surprised with what what the overall community around your hardware will deliver.

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.