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.06 Jun 2017
I have seen a number of research projects looking at API documentation, but this is the most detailed study into how people are seeing, or not seeing the API documentation and other resources we are providing. It is a dissertation for Robert Bennett Watson out of the University of Washington on the Effect of Visual Design and Information Content on Readers’ Assessments of API Reference Topics.
I gave the research paper a read through and it is some lofty academic stuff, but it touches on a number of the things I write about on API Evangelist when it comes to the cognitive load associated with understanding what an API does. I found the resulting conversation from the research to be the most interesting part, discussing how we can improve the flow with our API documentation and reduce interruption time, or as I often call it, “friction”. There are a wealth of ideas in there for helping us think more critically about our API documentation, which has been repeatedly identified as the number one problem area for our developers.
If you are in the business of creating any new API documentation startup your team should be digesting Mr. Watson’s work. This is the first official academic work I’ve seen on the subject of API documentation and is something I’ll be revisiting regularly, attempting to distil down any words of wisdom for my readers. I feel like this work is a sign of larger movements towards the API space beginning to get more coherent in how we approach our API operations. I’m hoping it is something that will lay the groundwork for some more useful API documentation services and tooling.
This post is a straight up copy and paste from an email newsletter I get from Peter Gruenbaum of SDK Bridge. I am a big supporter of API service providers like SDK Bridge, who has been doing API documentation the entire time I’ve been the API Evangelist. Peter isn’t looking to be the next big startup, he’s just operating a successful API service that addresses one of the biggest problems API providers face–documentation. Some of my readers might not be aware these types of services exist, which is why I’m copy / pasting this, and helping spread the good word.
People often ask me what the best tool for API documentation is. There is no simple answer to this question. It depends a lot on what your API looks like, who your developers are, and what kind of support you can give your content system. This is a quick newsletter to pass on a review of free and open source API documentation tools that you might consider using.
Also, there’s a 60% off sale on our Udemy courses for you newsletter readers for the first 10 students to sign up:
API Documentation 1: JSON and XML for Technical Writers: $10 (normally $25) API Documentation 2: REST for Technical Writers: $16 (normally $40) API Documentation 3: The Art of API Documentation: $10 (normally $25) Coding for Writers 1: Basic Programming: $18 (normally $45)
- Peter Gruenbaum, President, SDK Bridge
Free and Open Source API Documentation Tools Diána Lakatos has written an excellent description of several free and open source tools that can read the standard API definition formats OpenAPI, RAML, and API Blueprint. In addition, she covers API documentation tools that require non-standard formats, and general purpose open source documentation tools that can be used for API documentation that you may want to consider.
She provides screenshots and links to demos for each of these tools. If you want a quick overview of the tools, scroll to the bottom to read the summary table. You can find the article here: Free and Open Source API Documentation Tools.
ReDoc is the responsive, three-panel, OpenAPI specification driven documentation for your API that you were looking for. Swagger UI is still reigning king when it comes to API documentation generated using the OpenAPI Spec, but ReDoc provides a simple, attractive, and clean alternative to documentation.
ReDoc is deployable to any web page with just two tags--with the resulting documentation looking attractive on both web and mobile devices. Now you can have it all, your API documentation looking good, interactive, and driven by a machine-readable definition that will help you keep everything up to date.
All you need to fire up ReDoc is two lines of HTML on your web page:
The quickest way to deploy ReDoc is using the CDN step shown above, but they also provide bower or npm solutions, if that is your desire. There is also a Yeoman generator to help you share your OpenAPIs that are central of your web application operation, something we will write about in future posts here on the blog.
ReDoc leverages a custom HTML tag, and provides you with a handful of attributes for defining, and customizing their documentation, including specurl, scroll-y-offset, suppress-warnings, lazy-rendering, hid-hostname, and expand-responses--providing some quick ways to get exactly what you need, on any web page.
There is a handful of APIs who have put ReDocs to use as API documentation for their platform:
There also provide a live demo of ReDoc, allowing you to kick the tires some more before you deploy, and make sure it does what you will need it to before you fork.
ReDoc provides a simple, OpenAPI spec compliant way of delivering attractive, interactive, responsive and up to date documentation that can be deployed anywhere, including integration into your existing continuous integration, and API lifecycle. ReDoc reflects a new generation of very modular, plug and play API tooling that can be put to use immediately as part of an OpenAPI Spec-driven web, mobile, and device application development cycle(s).
I am working to update my OpenAPI definitions for AWS, Google, and Microsoft using some other OpenAPIs I've discovered on Github. When a new OpenAPI has entirely new paths available, I just insert them, but when it has an existing path I have to think more critically about what is next. Sometimes I dismiss the metadata about the API path as incomplete or lower quality than the one I have already. Other times the content is actually more superior than mine, and I incorporate it into my work. Now I'm also finding that in some cases I want to keep my representation, as well as the one I discovered, side by side--both having value.
This is one reason I'm not 100% sold on the fact that just API providers should be crafting their own OpenAPis--sure, the API space would be waaaaaay better if ALL API providers had machine readable OpenAPIs for all their services, but I would want it to end here. You see, API providers are good (sometimes) at defining what their API does, but they often suck at telling you what is possible--which is why they are doing APIs. I have a lot of people who push back on me creating OpenAPIs for popular APIs, telling me that API providers should be the ones doing the hard work, otherwise it doesn't matter. I'm just not sold that this is the case, and there is an opportunity for evolving the definition of an API by external entities using OpenAPI.
To help me explore this idea, and push the boundaries of how I use OpenAPI in my API storytelling, I wanted to frame this in the context of the Amazon EC2 API, which allows me to deploy a single unit of compute into the cloud using an API, a pretty fundamental component of our digital worlds. To make any call against the Amazon EC2 I send all my calls to a single base URL:
With this API call I pass in the "action" I'd like to be taken:
Along with this base action parameter, I pass in a handful of other parameters to further define things:
Amazon has never been known for superior API design, but it gets the job done. With this single API call I can launch a server in the clouds. When I was first able to do this with APIs, is when the light really went on in my head regarding the potential of APIs. However, back to my story on expressing what an API does, as well as what is possible using OpenAPI. AWS has done an OK job at expressing what Amazon EC2 API does, however they suck at expressing what is possible. This is where API consumers like me step up with OpenAPI and provide some alternative representations of what is possible with the highly valuable API.
When I define the Amazon EC2 API using the OpenAPI specification I use the following:
title: Amazon EC2
summary: The Amazon EC2 service
- in: query
The AWS API design pattern doesn't lend itself to reuse when it comes to documentation and storytelling, but I'm always looking for an opportunity to push the boundaries, and I'm able to better outline all available actions, as individual API paths by appending the action parameter to the path:
title: Amazon EC2
summary: Run a new Amazon EC2 instance
Now I'm able to describe all 228 actions you can take with the single Amazon EC2 API path as separate paths in any OpenAPI generated API documentation and tooling. I can give them unique summaries, descriptions, and operationId. OpenAPI allows me to describe what is possible with an API, going well beyond what the API provider was able to define. I've been using this approach to better quantify the surface area of APIs like Amazon, Flickr, and others who use this pattern for a while now, but as I was looking to update my work, I wanted to take this concept even further.
While appending query parameters to the path definition has allowed me to expand how I describe the surface area of an API using OpenAPI, I'd rather keep these parameters defined properly using the OpenAPI specification, and define an alternative way to make the path unique. To do this, I am exploring the usage of #bookmarks, to help make duplicate API paths more unqiue in the eyes of the schema validators, but invisible to the server side of things--something like this:
title: Amazon EC2
summary: Run a new Amazon EC2 instance
- in: query
I am considering how we can further make the path unique, by predefining other parameters using default or enum:
title: Amazon EC2
summary: Run a new Amazon EC2 website instance
description: The ability to launch a new website running on its own Amazon EC2 instance, from a predefined AWS AMI.
- in: query
- in: query
I am still drawing in the lines of what the API provider has given me, but I'm now augmenting with a better summary and description of what is possible using OpenAPI, which can now be reflected in documentation and other tooling that is OpenAPI compliant. I can even prepopulate the default values, or available options using enum settings, tailoring to my team, company, or other specific needs. Taking an existing API definition beyond its provider interpretation of what it does, and getting to work on being more creative around what is possible.
Let me know how incoherent this is. I can't tell sometimes. Maybe I need more examples of this in action. I feel like it might be a big piece of the puzzle that has been missing for me regarding how we tell stories about what is possible with APIs. When it comes to API definitions, documentation, and discovery I feel like we are chained to a provider's definition of what is possible, when in reality this shouldn't be what drives the conversation. There should be definitions, documentation, and discovery documents created by API providers that help articulate what an API does, but more importantly, there should be a wealth of definitions, documentation, and discovery documents created by API consumers that help articulate what is possible.
I've been an advocate for OpenAPI since it's release, writing hundreds of stories about what is possible. I do not support OpenAPI because I think it is the perfect solution, I support it because I think it is the scaffolding for a bridge that will get us closer to a suitable solution for the world we have. I'm always studying how people see OpenAPI, both positive and negative, in hopes of better crafting examples of it being used, and stories about what is possible with the specification.
When you ask people what OpenAPI is for, the most common answer is documentation. The second most common answer is for generating code and SDKs. People often associate documentation and code generation with OpenAPI because these were the first two tools that were developed on top of the API specification. I do not see much pushback from the folks who don't like OpenAPI when it comes to documentation, but when it comes to generating code, I regularly see folks criticizing the concept of generating code using OpenAPI definitions.
When I think about OpenAPI I think about a life cycle full of tools and services that can be delivered, with documentation and code generation being just two of them. I feel it is shortsighted to dismiss OpenAPI because it falls short in any single stop along the API lifecycle as I feel the most important role for OpenAPI is when it comes to API literacy--helping us craft, share, and teach API best practices.
OpenAPI, API Blueprint, and other API definition formats are the best way we currently have to define, share, and articulate APIs in a single document. Sure, a well-designed hypermedia API allows you to navigate, explore, and understand the surface area of an API, but how do you summarize that in a shareableÂ and collaborative document that can be also used for documentation, monitoring, testing, and other stops along the API life cycle.Â
I wish everybody could read the latest API design book and absorb the latest concepts for building the best API possible. Some folks learn this way, but in my experience, a significant segment of the community learn from seeing examples of API best practices in action. API definition formats allow us to describe the moving parts of an API request and response, which then provides an example that other API developers can follow when crafting their own APIs. I find that many people simply follow the API examples they are familiarÂ with, and OpenAPI allows us to easily craft and shares these examples for them to follow.
If we are going to do APIs at the scale we need to helpÂ folks craft RESTful web APIs, as well as hypermedia, GraphQL, and gRPC APIs. We need a way to define our APIs, and articulate this definition to our consumers, as well as to other API providers. This helps me remember to not get hung up on any single use of OpenAPI, and other API specification formats, because first and foremost, these formats help us with API literacy, which has wider implications than any single API implementation, or stops along the API life cycle.
I have had a number of requests from folks lately to write more about Github, and how they can use the social coding platform as part of their API operations. As I work with more companies outside of the startup echo chamber on their API strategies I am encountering more groups that aren't Github fluent and could use some help getting started. It has also been a while since I've thought deeply about how API providers should be using Github so it will allow me to craft some fresh content on the subject.
Github As Your Technical Social Network
Think of Github as a more technical version of Facebook, but instead of the social interactions being centered around wall posts, news links, photos, and videos, it is focused on engagement with repositories. A repository is basically a file folder that you can make public or private, and put anything you want into it. While code is the most common thing put into Github repositories, they often contain data file, presentations, and other content, providing a beneficial way to manage many aspects of API operations.
The Github Basics
When putting Github to use as part of your API operations, start small. Get your profile setup, define your organization, and begin using it to manage documentation or other simple areas of your operations--until you get the hang of it. Set aside any pre-conceived notions about Github being about code, and focus on the handful of services it offers to enable your API operations.
- Users - Just like other online services, Github has the notion of a user, where you provide a photo, description, and other relevant details about yourself. Avoid making a user accounts for your API, making sure you show the humans involved in API operations. It does make sense to have a testing, or other generic platform Github users accounts, but make sure your API team each have their own user profile, providing a snapshot of everyone involved.
- Organizations - You can use Github organizations to group your API operations under a single umbrella. Each organization has a name, logo, and description, and then you can add specific users as collaborators, and build your team under a single organization. Start with a single repository for your entire API operations, then you can consider the additional organization to further organize your efforts such as partner programs, or other aspects of internal API operations.
- Repositories - A repository is just a folder. You can create a repository, and replicate (check out) a repository using the Github desktop client, and manage its content locally, and commit changes back to Github whenever you are ready. Repositories are designed for collaborative, version controlled engagements, allowing for many people to work together, while still providing centralized governance and control by the designated gatekeeper for whatever project being managed via a repository--the most common usage is for managing open source software.
- Topics - Recently Github added the ability to label your repositories using what they call topics. Topics are used as part of Github discovery, allowing users to search using common topics, as well as searching for users, organizations, and repositories by keyword. Github Topics is providing another way for developers to find interesting APIs using search, browsing, and Github trends.
- Gists - A GitHub service for managing code snippets that allow them to be embedded in other websites, documentation -- great for use in blog posts, and communication around API operations.
- Pages - Use Github Pages for your project websites. It is the quickest way to stand up a web page to host API documentation, code samples, or the entire portal for your API effort.
- API - Everything on the Github platform is available through the Github API. Making all aspects of your API operations available via an API, which is the way it should be.
Managing API Operations With Github
There are a handful of ways I encourage API providers to consider using Github as part of their operations. I prefer to use Github for all aspects of API operations, but not every organization is ready for that--I encourage you to focus in these areas when you are just getting going:
- Developer Portal - You can use Github Pages to host your API developer portal--I recommend taking a look at my minimum viable API portal definition to see an example of this in action.
- Documentation - Whether as part of the entire portal or just as a single repository, it is common for API providers to publish API documentation to Github. Using solutions like ReDoc, it is easy to make your API documentation look good, while also easily keeping them up to date.
- Code Samples w/ Gists - It is easy to manage all samples for an API using Github Gists, allowing them to be embedded in the documentation, and other communication and storytelling conducted as part of platform operations.
- Software Development Kits (SDK) Repositories - If you are providing complete SDKs for API integrations in a variety of languages you should be using Github to manage their existence, allowing API consumers to fork and integrate as they need, while also staying in tune with changes.
- OpenAPI Management - Publish your APIs.json or OpenAPI definition to Github, allowing the YAML or JSON to be versioned, and managed in a collaborate environment where API consumers can fork and integrate into their own operations.
- Issues - Use Github issues for managing the conversation around integration and operational issues.
- Road Map - Also use Github Issues to help aggregate, collaborate, and evolve the road map for API operations, encouraging consumers to be involved.
- Change Log - When anything on the roadmap is achieved flag it for inclusion in the change log, providing a list of changes to the platform that API consumers can use as a reference.
Github is essential to API operations. There is no requirement for Github users to possess developer skills. Many types of users put Github to use in managing the technical aspects of projects to take advantage of the network effect, as well as the version control and collaboration introduced by the social platform. It's common for non-technical folks to be intimidated by Github, ad developers often encourage this, but in reality, Github is as easy to use as any other social network--it just takes some time to get used to and familiar it.
If you have questions about how to use Github, feel free to reach out. I'm happy to focus on specific uses of Github for API operations in more detail. I have numerous examples of how it can be used, I just need to know where I should be focusing next. Remember, there are no stupid questions. I am an advocate for everyone taking advantage of Github and I fully understand that it can be difficult to understand how it works when you are just getting going.
I read a lot of content about APIs. I read a lot of redundant and fluffy marketing and technical jargon, trying to understand exactly what an API does, or doesn't do. Before I criticize, I have to admit that crafting really good API marketing and documentation is hard. Only about 5% of what I read is good, a significant portion is just incomplete and lazily done by someone who doesn't care--the rest is actually incorrect, misleading, and straight up hype.
There are three layers to the API hype onion in my experience:
- Marketing - The fluff on the main page written by the marketing team who usually doesn't care about the API and has taken the time to get to know what it does.
- Documentation - The technical fluff in the API portal usually written by someone technical, and not quite possessing the skills to talk to humans, let alone coherently explain something to another human being.
- API - The actual naming, ordering, parameters, and overall request and response structure for an API that actually accomplishes something--it may not always accomplish exactly what I'm looking for, but at least it is.
While I still read marketing and documentation, because they provide me with clues about the intent behind API operations, when I actually want the honest take of what an API does, I always go straight to the API and get to work making API calls. This is a problem that is only increasing as we enter into the artificial intelligence and machine learning hype phase.
After you finish writing the marketing, documentation, and have your API up and running--step back, and re-read everything, and think about the synchronicity between these three areas of your operations. It takes a lot of practice and hard work to do right, but I think if you just take a moment, step back, and think about these layers to how you articulate what your APIs does--you will immediately find yourself in a better position to communicate what it is you are trying to accomplish to a much wider audience.
I am working on a project using the Youtube API, and came across their inline OAut 2.0 scopes, allowing you to explore what the API does as you are browsing the API docs. I am a huge fan of what interactive documentation like Swagger UI, and Apiary brought to the table, but I'm an even bigger fan of the creative ways people are evolving upon the concept, making learning about APIs a hands-on, interactive experience wherever possible.
To kick off my education of the YouTube API I started playing with the search endpoint for the Youtube Data API. As I was playing with I noticed the had an API explorer allowing me to call the search method and see the live data.
Once I clicked on the "Authorize requests using OAuth 2.0" slider I got a popup that gave me options for selecting OAuth 2.0s copes, that would be applied by the API explorer when I make API calls.
The inline OAuth is simple, intuitive, and what I needed to define my API consumption, in line within the Youtube API documentation. I didn't have to write any code or jump through a bunch of classic OAuth hoops. It gves me what I need for OAuth, right in the documentation--simple OAuth is something you don't see very often.
I'm a supporter of more API documentation being an attractive static HTML layout like this, with little interactive modules embedded throughout the API docs. I'm also interested in seeing more web literacy being thrown in at this layer as well, pulling common web concepts and specification details, and providing popups, tooltips, and other inline API design learning opportunities.
I'm adding YouTube's approach to OAuth to my list of approaches to a modular approach to delivering interactive API documentation, for use in future storytelling.
I had an exchange with Abhinav Asthana (@a85), the Co-founder and CEO of Postman on Twitter today. He was tweeting about API documentation, and I chimed in with my support, about how we need to keep evolving our approach to delivering API documentation so that they speak to a diverse audience.
An API description created by experts is probably not the right way for building docs meant for beginners.— Abhinav Asthana (@a85) March 7, 2016
While I think we have come along ways with the introduction of Swagger UI, making learning about APIs much more interactive, and hands on, I think its time to look at how we can further refine how we deploy API documentation for our users.
There is a lot going on with an API sometimes, and listing out all your endpoints, parameters, example requests, responses, and other elements can be overwhelming for new users who are just looking to learn the basics of an API, or possibly just get at s single resource, completing a specific action.
Swagger UI, and similar API definition driven documentation like Lucybot API Console, do well in providing a comprehensive set of documentation for a potentially wide variety of API docs, but we need to keep scratching. I'm not exactly sure what the answer here is, but I'd love to see much more simpler, embeddable, API documentation emerge. Solutions that allow API providers to display a small set of precise APIs, or possibly come up with some sort of slick user interface (UI), that delivers a simpler, more meaningful user experience (UX) that speaks to what a specific group of users is needing.
This is not a well-formed idea of mine, but is something I want to get out early. I'm seeing an increase in the number of new API documentation resources lately, and hopefully I can influence at least one or two of their road maps with my ideas. This is one reason I've broke out my API documentation research out of my API management research. I have numerous ideas for new types of smaller, more bite-size API docs, as well as more embeddable, and visual API docs as well--having a research project setup gives me a single repo to think about, and publish these ideas.
The reasons for having an OpenAPI Spec for the ClinicalTrials.gov data are many, but one of the most obvious benefits is the ability to generate interactive API documentation for the platform. I am using Swagger UI, as the interactive API documentation across my Adopta.Agency projects.
This approach to delivering documentation is a far more hands-on approach than earlier, more static API documentation. This documentation will evolve along with the project, when I require API keys to work with the API, saving valuable compute, storage, and bandwidth resources. All I have to do is keep the OpenAPI Spec up to date, and the SwaggerUI does the rest.
It is important to have up to date API documentation, helping explain what the API does, but it is even more important to have the machine readable OpenAPI spec, because it drives so many aspects of the API operations, something which acts as the contract for what is expected of the clinical trials API.
API driven embeddable tools comes in many shapes and sizes, but is something I work hard to understand, and track on in the space. I have several new embeddable stories to talk about this week, but today's is from my friends over at APIMATIC, as well as Apiary. The two service providers now offer the ability to embed your APIMATIC driven SDKs, into your Apiary driven API documentation. All you do, is plug in the URL of your Apiary portal page for your API, into your APIMATC account, and you are returned embeddable markdown you can paste into your Apiary API documentation--Apiary addresses your API design, documentation, testing and virtualization needs, and APIMATIC comes is with the API SDK assist.
I like API service providers working together like this, it is something that makes API provider's and API consumer's lives easier. This approach to API service interoperability is what it will take to weave together the patchwork of API services that will be needed across the API life cycle. As more API service providers emerge to fill gaps in the life cycle, the ability to stitch these stops will grow more critical, something embeddability will contribute to. Depending on a single provider in 2016, is just not a reality, and I need the services that I depend on to work together.
I am happy to be showcasing a new open source, OpenAPI Spec driven, interactive API documentation, from the LucyBot team. The API definition driven documentation solution is one of the best implementations I've seen to date, and reflects the future of where API documentation should be going in my opinion. While the Swagger UI has significantly moved the API documentation conversation forward, it has never been the most attractive solution, pushing some API providers to use a more attractive, less interactive, open source solution from Slate.
The LucyBot API Console is both! It is API definition driven, using the OpenAPI Spec as its engine, but also provides a conversion tool for RAML, WADL, or API Blueprint. The LucyBot API Console is also very attractive, responsive, and flows much like Slate does, but goes much further by being an actual interactive API console, not just good looking, static docs. You can see Lucy Console in action over at AnyAPI, or as a small set that demonstrates different CSS variations.
I have forked, and started playing with the LucyBot API Console more--I encourage you to do the same. There are a number of features I'd like to see in there, like more embeddability, and templability of the UI, as well as some APIs.json support, and D3.js visualization integration--so I wil be getting more knowledgeable of the code base, and in tune with the road map. I know the LucyBot team is open sourcing the code to encourage contributions, and are looking for investment in dev and business resources to move the project forward--so get involved!
I was just talking API documentation with Brent Baker (@norcaljhawk), and Jordan Lampe (@JsLampe) from Dwolla. As we were going through their API documentation, they mentioned how they were using Slate for the version 1.0 of their API documentation, but for this round they took what they felt were just the best parts of Slate, and were looking to craft a new experience.
Interestingly I had written about their use of Slate for API docs back in 2014, so it makes sense for me to keep tracking on, but more importantly I think the move reflects the wider evolution of API documentation. If you aren't familiar with Slate, it is a very attractive way to document your APIs, that many API providers and consumers have latched on to. Slate, in contrast to the very utilitarian style of Swagger UI, has certain elements developer prefer--something I can see why, after looking at a lot of API docs.
Dwolla's evolution from their old static API docs to Slate, and then to their current version highlighted two important aspects of the modern API documentation evolution for me. First, the feedback to the Dwolla team revealed that the three column format which Slate used for documentation, made the documentation seem like it was not part of the overall Dwolla experience--it was separate. Which is one unique thing Swagger UI did, is that allowed it to be embedded within any API portal, even though the look was not as attractive as Slate is.
For me this highlights some of the elements, the latest wave of API documentation developers, like Any API, may want to consider as they help push forward the overall API documentation conversation. Any API did what I wanted to see, and combined the interactive functionality of Swagger UI, and the clean UI / UX that Slate brought to the table. I recommend to anyone crafting the next generation of API documentation solutions, consider the overall layout, making things more decoupled, responsive, and allowing of more embeddability of all, or even just portions of the API documentation--making the API documentation experience more portable, and re-mixable.
Even though I'm not seeing everything I would like to when it comes to the evolution of API documentation, I am optimistic about what I am seeing, and my conversation with the Dwolla team shows me there is a lot of positive momentum forward in how leading API providers are really thinking about what matters, when it comes to API documentation.
I had a follower tweet out an interesting question about successful patterns for multi-linguarl APIs, which I thought was interesting enough to share as a story, adding to my research, and helping me tune into the topic better.
As the API economy unfolds, and APIs make their way into more countries around the globe, the need to standardize how we internationalize different layers of our API operations is only going to increase--making these types of conversation starters very important.
Here is the Twitter thread:
I see two key building block that I can extract from this conversation. One being Accept-Language for dictating which language your API should be speaking, and two, using a query string lang= to tell your documentation what language it should be speaking. I've added both as API design building blocks, and the documentation reference to my API management building blocks.
I love questions like this, because it puts these topics on my radar, and after writing a post about it, and adding as some common building blocks, the chances I will explore further dramatically increases. This is the side of my research that keeps me getting up and sitting down at the pooter each day.
I started playing with the possibilities when it comes to API deployment using virtual containers like Docker early this year, exploring the constraints this approach to API deployment introduced, on my own infrastructure. The process got my gears turning, when it comes to deploying very simple data, content, and algorithmic APIs into any environment that runs Docker.
As 2015 has progressed, I'm seeing containers emerge as part of more stops along the API life-cycle, specifically in deployment and virtualization. A new one that just came across my radar is API PLUG. I haven't played with the containerized API deployment solution yet, but after watching video, and looking through site it seems in line with what I'd expect to see from a next generation, containerized, API deployment solution.
Overlapping with my previous post on reconciling API orchestration, I'm seeing several stops along API lifecycle present in API PLUG, beyond just API deployment, it allows you to design, deploy, and document your API which moves well into the world of API management. As I'm seeing with other emerging solutions like API Studio from Apigee, I predict we will see testing, monitoring, and other critical layers of the API life-cycle emerge as orchestration layers of API PLUG.
I've added API PLUG to my API deployment research, and I am still considering the best way to include them in other areas of my API research. I'm increasingly finding that modern API management solutions are spanning multiple areas of the API life-cycle, which further encourages me to modularize my research, but also tells me I'm going to need to create some sort of Venn Diagram visualization to help me better understand the reach of emerging API products and services.
Anyways, more to come on API PLUG as I play with, and listen to the stories they tell via their blog, Twitter, and Github accounts (I can only find a Twitter account, but I'm sure they are working on that! ;-).
I wrote that we should be generating Slate API documentation from Swagger so we maintain a machine readable core the other day--while I love the look of Slate, I want to make sure all API meta data is machine readable by default. Shortly after publishing my post, someone kindly pointed me to a version of Swagger that was developed by Jens-Ole Graulund, which was exactly the evolution that I was looking for.
The more response, Swagger driven version of Slate API document is perfect! Giving API providers a more attractive, response version of Swagger UI (sorry Tony), while also keeping the core machine readable.--it is the best of both worlds! I plugged in one of my other complete Swagger definitions, and boom...I had a new version of my API docs.
Tips like this from my readers is why I blog about all my ideas out loud. If I kept my thoughts locked up, this type of discovery would never occur. I am going to play with deploying this version of the Swagger UI for my API stack, to see how versatile it is, and how well it works with my own site template.
I just wanted to put it out there that this new option for Swagger UI exists, in case you were looking for an alternate version of the Swagger UI. I predict this is the beginning of many different iterations on Swagger UI, resulting in one eventually that is themable. ;-)
This is a topic I’ve had an increasing number of conversation with folks about in the last couple months, and a friend of mine Tweeted in response to today, resulting in this lovely rant. This is about two very separate problems, in which the solutions are what I'd consider significantly overlapped. I’m talking about the need to make sure the valuable metadata, as well as underlying resources made available via an API is accessible to search engines, while also making sure the it is all Section 508 compliant, providing critical access to people with disabilities.
In response to my recent post, on "Why The New API Blueprint Sharing Button From Apiary Is So Important”, said:
First, this is another reason why the API Blueprint being more open is important, anyone can now come along and not just build an SEO API documentation solution, they can get access to Apiary.io users who desire such a solution. Ok, that might seem bad for Apiary, but in situations that Apiary is not concerned with, this allows the community to step up and serve the long tail, and if it is something that concerns Apiary, it lights the fire under their ass to consider adding to the road map (sorry Jakub & Z, I know I"m a pain ;-).
Second, it allows the community to step up and serve what I'd consider the critical long tail—like Section 508. In our rush to deliver the latest in technological innovations, we often forget about significant portions of our society who, well, aren’t like us. How many leading apps and platforms that you use are Section 508 compliant? I guarantee almost all API tooling is not—something we need to address now, and is a topic where discussion is currently happening the federal government circles.
I am a big fan of Swagger UI, and Apiary, and what they have done for API design, deployment, management, discovery, and evangelism, but we need to keep working on the next generation of UI, and UX that is easily indexed, and works well with assistive technologies. Ok, at this point the hypermedia folks want to kick my ass--bring it! ;-) Kidding. What I am talking about should happen in conjunction with well designed, hypermedia fueled clients, not instead--both camps should be addressing making sure all clients or SEO and 508 friendly.
I guarantee if you made an open source set of tools to support this, you'd get the attention of government at all levels, around the world, something that would open up significant other opportunities.
I'm on the hunt for new ways to deploy attractive, interactive API documentation, from machine readable API definition formats like Swagger and API Blueprint. I am advocating for the development of new approaches to deploy UI documentation, and part of this showcasing what I find along the way.
In the spotlight today is Aglio, which they describe as:
An API Blueprint renderer that supports multiple themes and outputs static HTML that can be served by any web host. API Blueprint is a Markdown-based document format that lets you write API descriptions and documentation in a simple and straightforward way.
Aglio is significant because it is driven from the machine readable format API Blueprint, and produces static HTML that can be served up anywhere, specifically on Github or Amazon S3 deployed using Jekyll. Additionally it just makes your document simple, easy to follow, and just damn sexy.
I’d love to see a Swagger generated version of Aglio, allowing you to deploy the attractive API documentation from both Swagger or API Blueprint. If more API documentation looked like Aglio, I would be a seriously happy camper.
There are other UI solutions to API documentation, projects like Slate from Tripit, from Readme.io, and some cool UI stuff over at OpenFDA, but really I haven’t seen much evolution beyond Swagger UI. Sure, Apiary.io has a great UI, but it isn’t the portable, customizable vision I have in my head (they are working on this, BTW). I envision a whole gallery of simple, UI templates that you can choose from, driven by machine readable Swagger or API Blueprint API definitions.
Looks like the gov hackers over at 18F feel the same way, and are working on something like this—"a suite of tools and templates that faciliate the generation of static, human-readable documentation to replace SwaggerUI”. Shawn Allen, has created two repos:
- swagger-template, just some HTML files that should theoretically be useful for generating static HTML documentation for a Swagger-compliant API.
- swagger-enhance, a little Node utility for grabbing a Swagger API's JSON and "enhancing" it with JSON data from each of its own endpoints (confusingly, "apis", in Swagger parlance).
It makes me happy to see some brainstorming to push the conversation forward. I’m able to deploy Swagger UI pretty quickly to support my APIs, using Github Pages, but when it comes to extending, and transforming the UI, I hit a wall pretty quickly. I've created some custom UI solutions, to help me manage my own infrastructure, driven by Swagger, but nothing that contributes to the larger conversation.
I’d love to see API design, deployment, and integration tools I depend on like Restlet Studio, and Postman provide more support for easy deployment of UI elements, driven by machine readable API formats like Swagger and API Blueprint. Making API documentation more interactive with Swagger UI was an important step forward, but we are ready for the next step in the evolution of API UI generation.
I talked about Twitter's inclusion of rate limits inline with documentation the other day, which is something I added as a new building block, that API providers can consider when crafting their own strategy. Another building block I found while spending time in the Twitter ecosystem, was an oAuth signature generator inline within the documentation.
While browsing the Twitter documentation, right before you get to the example request, you get a little dropdown that lets you select from one of your own applications, and generate an oAuth signature without leaving the page.
I am seeing oAuth signature generators emerge in a number of API platforms, but this is the first inline version I’m seeing. I’ve added this to my tentative list of oAuth and security building blocks I recommend, but will give some time before I add. I like to see more than one provider do something before I put it in there, but sometimes when it is just Twitter, that can be enough.
As I look through the API efforts of various providers, I’m always looking for the little things that can make on-boarding, and sustained integration with an API as frictionless as possible. One of the building blocks that I recommend API providers employ in their operations, is a page that explains API rate limits—providing vital information on how API resources are throttled (or not).
An improvement on the standard rate limit building block, can be seen at Twitter. Inline in the Twitter API documentation, there are details about rate limiting for that specific endpoint. This way, as you are learning about each endpoint, you can also understand what limitations are in place. A small addition that could prove critical, for any API provider, especially Twitter, who has some of the most complex rate limiting of any API I know of.
At first glance, something small like including rate limit information within each API endpoint documentation may seem insignificant, but think of it like bobsledding or swimming in the olympics, where the slightest adjustment can reduce friction in just the right place—giving you the competitive advantage you need. Taking a fresh look at the building block(s) Twitter uses around API rate limiting, is expanding my own thoughts on how any API provider can approach their own rate limiting, and represents why I keep an eye on API pioneers like Twitter, even if I don’t always agree with 100% of their decisions around platform operations.
P.S. Did you notice the picture is of the rate limiting information, within the rate limit API endpoint? That will be another story, as part of my expansion of thought in the area of rate limiting.
I wrote about visual API documentation a few months back, after I looked at the approach from OpenFDA, and now after taking a look at the value Slate brings to API providers like Dwolla, these feelings are re-surfacing in my mind. Since I have limited time, I’m getting pretty good at putting my ideas out there, allowing anyone to step up and execute on opportunities I’m seeing across the API space—I just do not need the extra work.
I love me some Swagger UI, as you can tell from the fact that all of my APIs use Swagger as the API definition format, as well Swagger UI for the interactive documentation. I’m pretty convinced of the importance of documentation being a hands-on experience, but after looking at approaches like OpenFDA, and Dwolla with their Slate driven API docs, I’m convinced they should also be more beautiful and functional.
Let me explain what I would like to see developed for the API space:
- API Definition Core - As we are beginning to see across the space with current interactive API documentation practices, everything needs to be driven by a machine readable API definition, providing a set of instructions for how any user will engage with an API.
- Interactive - In 2014 the bar is already set, and API documentation should be interactive, allowing users to make live calls to a demo, or production API, making learning about an API hands-on experience.
- Inline Code - The tools are available to generate code samples from Swagger and API Blueprint, and wherever we make an API call, we should also be able see the code for making the call inline, side-by-side with wherever I am engaging with the API—in my language of choice please!
- Visualizations - I don’t want just to get back a response from the API, I want to be able to visualize the value returned from an API. I would like a suite of D3.js visualizations for each API endpoint I’m interacting with, allowing me to immediately see the value generated by each API.
- Spreadsheet - Allow me to export a CSV, or more robust Excel or Google Spreadsheet representation of an API. Sure, this would not be applicable to all APIs, but would bring a lot of value to many APIs out there. APIs aren’t just for developers in 2014. Oh, and make me the D3.js code for any visualization too copy & paste as well.
- Embeddable - I enjoy being able to deploy my Swagger UI to any Github repository using Github Pages, and I think portability is essential for the success of API engagement. I want to be able to copy & paste API expressions, visualizations, and other simple, easy to use widgets to any site, anywhere—no coding experience necessary.
- Open Source - If you are building something like what I’m describing, it really should be open source so that all aspects of it can be reused, by anyone, anywhere. It just doesn’t make sense to be a proprietary, closed solution, and you if are building something in this way you owe me $1 million dollars for my ideas. ;-)
API docs have become much more than just API documentation, they have become about API discovery, education, expression, collaborations, and interactions, going way beyond just our grandfathers way of documenting an API. We have the language (Swagger & API Blueprint) to describe our APIs, lets begin providing more meaningful ways to engage with them as well.
If you would like to, or are already building any of these features I’m laying out, feel free to connect with me, and I'm happy to provide feedback anywhere during the design, development, and implementation—just let me know what you need.
I know I’m a demanding bitch in the API space, expecting people to do this work for me, but the space needs it. Thanks for building it! ;-)
I'm seeing the enterprise wake up to the potential of an API centric approach to doing business, slowly evolving beyond a Service Oriented Architectural (SOA) approach, and trying to understand why APIs are superior for delivering resources to the web, mobile, and Internet of thing (Iot) apps they are delivering, and increasingly depending on. Even though we are clearly in an enterprise phase of the API evolution, I’m watching many leading enterprise entities struggle with their early API efforts, producing some pretty weak solutions, that developers are not finding useful, and hurting their efforts right out of the gate.
I know that many enterprise API architects will dismiss my advice, because they know better than I do, but I feel compelled to share my thoughts, in hopes that even a handful will be more successful with their API efforts, which I think will also help the overall space as well. When embarking on your API journey, you are going to be handicapped right out of the gate, because as a large enterprise organization, you do not have many of the essential characteristics necessary in your DNA to be successful with APIs, but this is why it will require an API journey, to reprogram your DNA, and better operate on the open Internet.
Before you start planning your APIs, and the supporting developer area, you need to play with other public APIs, to better understand what makes APIs different. I am always amazed at how many enterprise API architects that I engage with, when I ask them what public APIs they have used, admit that they have never used one. They just have heard of many of the common APIs out there, so to prime the API pump, let’s hack on a couple of the most popular API solutions out there:
- Twitter - Hacking on the Twitter API provides some very important lessons when it comes to API design, as well as developer support.
- Github - Github is an essential tool in an API providers toolbox on so may levels, but using their API for managing code is an important experience.
- Twilio - Twilio is a god when it comes to API providers, and we all look up to them, so if you aren’t familiar make sure and hack together a simple API.
Do not skip this section, you may think you understand how these APIs operate, by visiting their developer areas, and I know you come to the table with a wealth of experience, and this is your handicap. You have a serious amount of technical experience, way more than I do, but what you are missing is an understanding of many of the business and political building blocks that are making all of this work, ares that you have very little experience within the enterprise.
- Simple, Simple, Simple
- Begin With API Definition
- Interactive Documentation
- Self-Service Registration
- Play With Service Composition
- Telling Meaningful Stories
- Showcase Your Developers
- Establish Feedback Loops
- Flexible Terms of Service
- Invest In Your Developers
- Internal Evangelism
Technology is part of all of these suggestions, but ultimately APIs represent a new way of doing business that you just aren't used to, and you will have to learn it—something that will take time. Even once you launch your API, you won’t be ready, you will have to learn over time, and this is what the API journey is all about, in addition to the core proposition of making vital company resources available to the public, partners, and internally across the enterprise.
Your biggest challenge, beyond the ones listed above will be what you face internally. Getting developers to use your API resources is tough, getting them to deeply integrate them into applications is even harder, but changing culture at your company and getting the support and resources you will need will be a massive undertaking!
Bottom Up Change
Your senior leadership will most likely not be on board with an API way of operating, and will need a lot of convincing, and most likely ask you for more evidence of why this will work, before they will give you any resources to embark on your journey. They will want the type of ROI that can kill any API effort before it even gets going, so you will have start small, produce results, and demonstrate the value an API delivers in small, bit-size chunks, week by week. This is not field of dreams, nobody will come once you build it, but this is why you start small, iterate, tell stories, showcase what has been done, and evangelize heavily internally to change senior leaderships view, and win hearts and minds with every integration.
Top Down Change
Even if you have the luxury of having the buy-in of senior leadership, which is extremely unusual, this doesn't mean that your API effort will be a gravy train. Chances are you will hit obstacles, and resistance all along the way. All the advice listed above is meant for your public, and partner audience, but also needs to target your senior, and mid-level management. If you don't have the buy in of the people in the trenches, your API efforts will stumble, and probably fail. The growing number of reasons API fail, are not technical. APIs fail because they do not deliver the value developers actually need, and fail to get the internal change needed to maintain the resources you will need to be successful.
The Enterprise In Age Of Internet
APIs are not just about the enterprise exposing technical endpoints that provide access to your vital resources, and giving you the control you need to govern the usage of these resources. APIs are about the enterprise learning to operate in the age of the Internet, a world that is much more open, global, and distributed, requiring a different approach to business that is about investing in innovation, and less about governance and control. The reason you are probably looking at APIs, is the desire to be more agile, nimble, and deliver web, mobile, and Iot applications faster, better, and cheaper than your competitor—something that takes a shift from your legacy approaches, and slowly shift your culture to reflect the Internet.
You will not be able to master plan your API strategy, and ensure success. You will need to open up a simple, useful API developer area, with a handful of valuable API resources that can be applied internal, bring value to your partners, and quite possibly the public, and get the wheels of change rolling forward. Only then will then will you start to understand the world of APIs, and if you neglect the simplicity, storytelling, showcasing, and other critical elements needed to develop the feedback loops that are necessary to keep the wheels rolling, you will doom your efforts. APIs don’t fail because they are public, or not what is relevant, they fail because you don't see the elements that make them successful, and lack the culture necessary to be an API driven company—get started making the change that will give your organization the tools it needs to not just be competitive, but lead in the Internet age.
I tag a lot of interesting companies that show up during my weekly API monitoring. When I see a tag go from 1 or 2, to over 5 companies--I take a closer look to see what is going on. An increase in the number of companies focusing in a specific area could be a trend, or it could be nothing.
The tag "API Agency" ticked over to 6 today, when I added Aquevix, an indian company that is focusing on API development. As of August 2014 I now have six separate agency style companies that I've found who have a focus on API design and development:
Developer Support Beyond FAQ, Forums and Documentation. First class support for your API. Processing an API request often means directly or indirectly interacting with 2 or more systems. Is your support team equipped with the necessary training, tools, information and support infrastructure to be successful? IT Assist helps you design and implement your API support strategy and infrastructure, offer training to your support team and as needed handle your developer support.
We are a small Independent software business specialising in the. Enhancement of existing software. We use standalone applications and APIs to extend the functionality of existing systems. Integration of separate systems. We connect disparate online SaaS applications together to create an integrated system. Automation of business processes. We convert manual menial tasks into automated business processes, reclaiming time and costs.
We design market strategies for companies looking to extend their APIs into digital partnerships. API Strategies to accelerate social and mobile content and digital partnerships. Big data asset definitions and valuations to define API approaches. API pricing and tier strategies to monetize data. Developer and partner outreach strategies to expand mobile success and "mash-ups”. Business model development for emerging start ups and matching them to enterprise clients and needs. Best practices to compete and win in the social, mobile, and big data marketplaces.
Aquevix is the go to company that can weave the abstract into a finished product. We are a software company that provides innovative, business solutions worldwide. Need an API? We got you covered. We provide full REST/JSON based API implementation and related apps with best practices! We are capable of developing highly specialized APIs that integrate seamlessly with powerful apps and increase overall performance of applications.
|Blue Jazz Consulting
Blue Jazz Consulting is focused on guiding product companies from idea to revenue using Ruby and Rails and Java-based technologies. Based in Austin,TX, we bring experienced professionals and a history of successful projects to the community. We offer expert consulting services for existing products and early-stage startups. We offer expert consulting and development in software architecture, specifically on the backend requirements of complex B2C and B2B applications. We love to model, design, and build web and mobile APIs to ensure that your business capabilities can be consumed successfully by internal developers, devices, and third-parties using a Ruby or Java platform.
At Stateless we employ our specialist experience, design processes and tools to ensure our clients realise the most value from their APIs. We're making the world of APIs beautiful.We work with you to surface the business goals for the API. We decide on the metrics to measure and track. These will help in understanding whether we are achieving our goals. We create developer personas to represent the various types of consumer, and a roadmap to deliver features tailored to them. We offer engineering and product management resources delivered using the best modern processes and tools. We employ Lean practice by tracking important metrics and constantly feeding that insight back into the live roadmap. We provide technical writers, and use the latest tools and techniques to interlace your test suite and your documentation.
We'll see how many more dev shops I find in the next couple months. Sometimes when I start focusing in a new area I will find more companies working in the same area, purely because I'm looking harder, and sometimes it takes time for things to actually heat up.
As I'm looking at local Chicago web and mobile development shops during the lead up to API Strategy & Practce in Chicago next month, and I'm learning that many small shops like SYDCON and Blaze Portfolio are using APIs, they just havn't shifted their marketing and web site content to reflect the evolution.
It won't take much for many of these web and mobile development shops to standardize their API design and development services, much like the evolution we saw occur from web to mobile development, shifting the focus of the small dev shop to better serve a growing demand for API design, and development. I think by 2015 I'll see over 50 development shops, who are heavily focused on API design and developmennt in my API tracking system.
P.S. I REALLY like the API Chappies, and Mike @ Stateless is the freak'n man!
I spoke with Phil Windley (@windley) over at Brigham Young University (BYU) about their API strategy this morning. BYU is bringing together API providers and consumers, to establish a coordinated strategy for delivering designing, deploying, managing, and integrating with APIs across campus--an effort being led by CIO Kelly Flannagan (@kelflanagan).
As part of their latest API effort, BYU is focusing in on the lowest hanging fruit when it comes to campus resources:
The API team is still struggling with a handful of technical details like how to deal with unique identifiers, and relationship between resources, but overall they are on a healthy path when it comes to getting their API designed, and deployed for use at the institution. I’m interested in seeing how fast they progress with a top down approach to APIs, vs the bottom up efforts I’m seeing at institutions like UC Berkeley.
I will be talking their team regularly, about their design, deployment, management, and integration strategy. I want to make sure and document the process all along the way, and share real-time updates that other universities can follow along, or possibly collaborate with us when it comes to establishing some common API patterns we can share and re-use across higher educational institutions.
Look for any stories out of BYU, here on API Evangelist, or over at my university API research site, and if you are doing any API work at your school, I'd love to know more about it.
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.