{"API Documentation"}

OpenAPI-Driven Documentation For Your API With ReDoc

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).

ReDoc is available on Github: https://github.com/Rebilly/ReDoc, as an open source solution brought to you by Rebilly, “the world's first subscription and recurring profit maximization company".

See The Full Blog Post


Expressing What An API Does As Well As What Is Possible Using OpenAPI

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:

ec2.amazonaws.com

With this API call I pass in the "action" I'd like to be taken:

?Action=RunInstances

Along with this base action parameter, I pass in a handful of other parameters to further define things:

&ImageId=ami-60a54009&MaxCount=1&KeyName=my-key-pair&Placement.AvailabilityZone=us-east-1d

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:

swagger: '2.0'
info:
title: Amazon EC2
host: ec2.amazonaws.com
paths:
/:
     get:
          summary: The Amazon EC2 service
          operationId: ec2API
     parameters:
          - in: query
            name: action

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:

swagger: '2.0'
info:
title: Amazon EC2
host: ec2.amazonaws.com
paths:
/?Action=RunInstances/:
     get:
          summary: Run a new Amazon EC2 instance
          operationId: runInstance

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:

swagger: '2.0'
info:
title: Amazon EC2
host: ec2.amazonaws.com
paths:
/#RunInstance/:
     get:
          summary: Run a new Amazon EC2 instance
          operationId: runInstance
  parameters:
     - in: query
               name: action
               default: RunInstances 

I am considering how we can further make the path unique, by predefining other parameters using default or enum:

swagger: '2.0'
info:
title: Amazon EC2
host: ec2.amazonaws.com
paths:
/#RunWebSiteInstance/:
     get:
          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. 
          operationId: runWebServerInstance
  parameters:
     - in: query
               name: action
               default: RunInstances
 
     - in: query
               name: ImageId
               default: ami-60a54009
 

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. 

See The Full Blog Post


OpenAPI As An API Literacy Tool

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.

See The Full Blog Post


An Introduction To Github For API Providers

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. 

See The Full Blog Post


The Three Layers Of API Hype

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.

See The Full Blog Post


Defining OAuth Scope Inline Within The API Documentation

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.

See The Full Blog Post


It Would Be Nice To Have Some Simpler Interactive API Documentation In Addition To What We Have Now

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.

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.

See The Full Blog Post


Use The ClinicalTrials.gov OpenAPI Spec To Drive The Interactive API Documentation

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.

See The Full Blog Post


Embedding Your Language SDK(s) In Your Apiary Documentation Using APIMATIC

I'm seeing a resurgence in my embeddable API research lately, based upon signals I'm seeing across the space, and conversations I'm having with folks. The interesting part for me is that this wave isn't about API providers like Twitter and Faceobok using JavaScript to create buttons, badges, and widgets. This latest round is about API service providers making their services more accessible to both API providers, and API consumers, using embeddable tooling, and most importantly, API definitions.

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.

As I will work to showcase in future stories, embedability comes in many shapes and sizes. I'm hoping we are on the cusp of a new wave of API driven embeddability, one that is exponentially more fruitful, and easier to implement for each individual API provider. An approach to using JavaScript and image driven embeddability, that uses APIs like previous waves, but this one is more designed for API providers, API consumers, as well as for end-users, like historical approaches to embed like Twitter tweet buttons, and Facebook share and login buttons were.

See The Full Blog Post


A New Open Source Interactive API Documentation From Folks Over At Lucybot

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!

It is good to see the API definition driven API documentation conversation moving forward in 2016!

See The Full Blog Post


Just The Best Parts Of The API Documentation Please

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.

As they evolve overall their portal experience, Dwolla was sure they wanted to keep the code sample viewer, which allows for inline viewing of raw, PHP, Ruby, Python, and JavaScript samples for each API. In rethinking their API docs, the Dwolla team wanted to decouple the three-pane experience, but keep the attractiveness, flowing navigation, and inline language sample experience that Slate delivered--keeping just the best parts of the increasingly ubiquitous API documentation format.

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.

See The Full Blog Post


Successful Patterns For Multi-Lingual APIs and 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.

See The Full Blog Post


API PLUG, A New Containerized API Design, Deployment, and Documentation Solution

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! ;-).

See The Full Blog Post


The Responsive Swagger Driven Version of Slate API Documentation I Was Looking For

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. ;-)

See The Full Blog Post


Working Toward An API Definition Driven, SEO, and Section 508 Compliant API Documentation Interface

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’ll close with a note on the opportunity here. There is huge potential to develop an open source API UI component that can use Swagger and API Blueprint as the core definition, implementing a more SEO and 508 compatible experience, something akin to Slate from Trippit. I’m thinking rather than a pull technology like Swagger UI does with its JS interface pulled from a Swagger definition, and I’m guessing Apiary does a similar pull from API Blueprint docs?? A more of an HTML, CSS push or publish of functional, static API documentation, that uses JavaScript and APIs to operate—just some raw thoughts on how to take next steps, its now up to you.

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. 

See The Full Blog Post


Static HTML Documentation Generated From Machine Readable API Blueprint Definitions Using Aglio

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.

See The Full Blog Post


We Need Better API Documentation And UI Deployment Options

I was having a Twitter conversation with John Sheehan(@johnsheehan) about the easiest way to generate interactive API documentation this weekend, without getting all tangled up in having to get into the weeds of Swagger UI. I love me some Swagger UI, something I think has transformed how we engage with APIs, but the JavaScript for it can be inaccessible, and difficult to customize--to say the least.

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.

See The Full Blog Post


Providing An oAuth Signature Generator Inline In Documentation

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.

See The Full Blog Post


Adding Rate Limits For APIs In The Documentation For Each Endpoint

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.

See The Full Blog Post


Someone Please Build My Open, Interactive, Portable, And Visual API Documentation Toolkit

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! ;-)

See The Full Blog Post


Some Advice For The Enterprise When Beginning Your API Journey

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.

See The Full Blog Post


The API Focused Dev Shop

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:

6 Companies
API Support

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.

APIChappies

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.

Apinomic

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

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.

Stateless

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!

See The Full Blog Post


Student, Instructor, Classroom, Class, And Course API Planning At BYU

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:

  • Students
  • Instructors
  • Classrooms
  • Classes
  • Courses

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.

See The Full Blog Post


Providing The Resources API Consumers Depend On

The current web API movement has been building for almost 14 years, started by API pioneers like SalesForce and Amazon, resulting in some pretty proven models for what types of resources API consumers need for a successful integration. When you look at the central developer areas for SalesForce and Amazon, but also for new players like Twilio and SendGrid, you see some consistent resources present between all of them, ensuring API consumers have what they need for building web, mobile, and single page applications, and increasingly to connect to physical devices in our every day world.

The minimum viable resources you need to support a central API developer program are:

  • Overview - A simple, clear, and concise description of what a developer program is intended to do, with introduction to the API resources that are available within a developer program.
  • Getting Started - Easy to follow, step by step instructions on how to get started using an API, and to take an application from idea to production with as little friction as possible.
  • Self Service Registration - Even if developers need further approval to get full access, some sort of self-service, 24/7 access to a developer area is the standard protocol for most API platforms--requiring developers to register, but can get at least limited access to APIs at any time.
  • API Reference / Documentation - Intuitive, simple, and up to date documentation of all API endpoints, and the authentication process is standard procedure, with many APIs providing also delivering some sort of interactive documentation using formats like Swagger or API Blueprint.
  • Code Samples & SDKs - An suite of code samples, libraries, and SDKs should be made available in top programming languages like PHP, Python, Ruby, JavaScript, Java, C#, and possibly leading languages like Go, for developers to put to use in their integrations.
  • Blog - An active blog, with RSS, provides a single communication channel that API consumers can depend on to receive updates about API and its parent companies operation.
  • Forum - Forums, either self-hosted by the API provider, or taking advantage of existing public forums like Stack Exchange, provide an indirect channel for developers to obtain support from the API provider, or from their community of peers.
  • Access Levels & Pricing  - Providing a transparent summary of API access levels, alongside any pricing that applies to the levels of API access available, provides clear information for API consumers to consider as they plan their integrations.
  • Terms and Conditions - Covering the legal aspects of API operations in a way that protects the API providers interests, as well as allowing API consumers enough room to build and operate businesses around their API integrations, is a standard practice within all API developer programs.

There are other bells and whistles you can add in, like a Twitter account or putting Github to work, but API pioneers like SalesForce, Flickr, Twitter and Google have established a common set of essential API building blocks through trial and error over the last decade—leaving this simple checklists that thousands of other API providers follow, making it a default for all APIs.

Internal, student, or external vendors will look to a centralized developer program, containing a consistent number of resources, delivered in a way that matches what people have grown accustom to, when integrating with APIs across the public and private sector over the last decade. 

See The Full Blog Post


Three APIs For www.usa.gov

After working on the federal agency domain API, under the explore.data.gov domain, there were three high value API from usa.gov I wanted to tackle next. I'm looking for the lowest hanging fruit when it comes to demonstrating the potential of APIs.json, for API discovery across the federal government.

The GSA has three pretty valuable API resources hosted at www.usa.gov:

My end goal here is to create an APIs.json for the www.usa.gov domain, so I needed machine readable definitions for each of these three APIs. I wanted the APIs.json to reference all three API pages at www.usa.gov, as well as Swagger definition for each one.

As I do with all my projects, I started a Github repository to track all my work, this is the result...

See The Full Blog Post


Low Hanging Fruit For API Discovery In The Federal Government

I looked through 77 of the developer areas for federal agencies, resulting in reviewing approximately 190 APIs. While the presentation of 95% of the federal government developer portals are crap, it makes me happy that about 120 of the 190 APIs (over 60%) are actually consumable web APIs, that didn't make me hold my nose and run out of the API area. 

Of the 190, only 13 actually made me happy for one reason or another:

Don't get me wrong, there are other nice implementations in there. I like the simplicity and consistency in APIs coming out of GSA, SBA, but overall federal APIs reflect what I see a lot in the private sector, some developer making a decent API, but their follow-through and launch severeley lacks what it takes to make the API successful. People wonder why nobody uses their APIs? hmmmmm....

A little minimalist simplicity in a developer portal, simple explanation of what an API does, interactive documentation w/ Swagger, code libraries, terms of service (TOS), wouild go a looooooooooooong way in making sure these government resources were found, and put to use. 

Ok, so where the hell do I start? Let's look through theses 123 APIs and see where the real low hanging fruit for demonstrating the potential of APIs.json, when it comes to API discovery in the federal government.

Let's start again with the White House (http://www.whitehouse.gov/developers):

Only one API made it out of the USDA:

Department of Commerce (http://www.commerce.gov/developer):

  • Census Bureau API - http://www.census.gov/developers/ - Yes, a real developer area with supporting building blocks. (Update, News,( App Gallery, Forum, Mailing List). Really could use interactive document though. There are urls, but not active calls. Would be way easier if you could play with data, before committing. (B)
  • Severe Weather Data Inventory - http://www.ncdc.noaa.gov/swdiws/ - Fairly basic interface, wouldn’t take much to turn into modern web API. Right now its just a text file, with a spec style documentation explaining what to do. Looks high value. (B)
  • National Climatic Data Center Climate Data Online Web Services - http://www.ncdc.noaa.gov/cdo-web/webservices/v2Oh yeah, now we are talking. That is an API. No interactive docs, but nice clean ones, and would be some work, but could be done. (A)
  • Environmental Research Division's Data Access Program - http://coastwatch.pfeg.noaa.gov/erddap/rest.html - Looks like a decent web API. Wouldn’t be too much to generate a machine readable definition and make into a better API area. (B)
  • Space Physics Interactive Data Resource Web Services - http://spidr.ngdc.noaa.gov/spidr/docs/SPIDR.REST.WSGuide.en.pdf - Well its a PDF, but looks like a decent web API. It would be some work but could turn into a decide API with Swagger specs. (B)
  • Center for Operational Oceanographic Products and Services - http://tidesandcurrents.noaa.gov/api/ - Fairly straightforward API, Simple. Wouldn’t be hard to generate interactive docs for it. Spec needed. (B)

Arlington Cemetary:

Department of Education:

  • Department of Education - http://www.ed.gov/developers - Lots of high value datasets. Says API, but is JSON file. Wouldn’t be hard to generate APIs for it all and make machine readable definitions. (B)

Energy:

  • Energy Information Administration - http://www.eia.gov/developer/ - Nice web API, simple clean presentation. Needs interactive docs. (B)
  • National Renewable Energy Laboratory - http://developer.nrel.gov/ - Close to a modern Developer area with web APIs. Uses standardized access (umbrella). Some of them have Swagger specs, the rest would be easy to create. (A)
  • Office of Scientific and Technical Information - http://www.osti.gov/XMLServices - Interfaces are pretty well designed, and Swagger specs would be straightforward. But docs are all PDF currently. (B)

Department of Health and Human Services (http://www.hhs.gov/developer):

Food and Drug Administration (http://open.fda.gov):

Department of Homeland Security (http://www.dhs.gov/developer):

Two losse cannons:

 Department of Interior (http://www.doi.gov/developer):

Department of Justice (http://www.justice.gov/developer):

Labor:

  • Department of Labor - http://developer.dol.gov/ - I love their developer area. They have a great API, easy to generate API definitions. (A)
  • Bureau of Labor Statistics - http://www.bls.gov/developers/ - Web APIs in there. Complex, and lots of work, but can be done. API Definitions Needed. (B)

Department of State (http://www.state.gov/developer):

Department of Transportation (http://www.dot.gov/developer):

Department of the Treasury (http://www.treasury.gov/developer):

Veterans Affairs (http://www.va.gov/developer):

Consumer Finance Protectection Bureau:

Federal Communications Commission (http://www.fcc.gov/developers):

Lone bank:

  • Federal Reserve Bank of St. Louis - http://api.stlouisfed.org/ - Good API and area, would be easy to generate API definitions. (B)

General Services Administration (http://www.gsa.gov/developers/):

National Aeronautics and Space Administration http://open.nasa.gov/developer:

Couple more loose cannons:

Recovery Accountability and Transparency Board (http://www.recovery.gov/arra/FAQ/Developer/Pages/default.aspx):

Small Business Administration (http://www.sba.gov/about-sba/sba_performance/sba_data_store/web_service_api):

Last but not least.

That is a lot of potentially valuable API resource to consume. From my perspective, I think that what has come out of GSA, SBA, and White House Petition API, represent probably the simplest, most consistent, and high value targets for me. Next maybe the wealth of APis out of Interior and FDA. AFter that I'll cherry pick from the list, and see which are easiest. 

I'm lookig to create a Swagger definition for each these APIs, and publish as a Github repository, allowing people to play with the API. If I have to, I'll create a proxy for each one, because CORS is not common across the federal government. I'm hoping to not spend to much time on proxies, because once I get in there I always want to improve the interface, and evolve a facade for each API, and I don't have that much time on my hands.

See The Full Blog Post


Looking At 77 Federal Government API Developer Portals And 190 APIs

I spent most of the day yesterday, looking through 77 of the developer portals listed on the 18F Github portal. While I wanted to evaluate the quality and approach of each of the agencies, my goal for this review cycle was to look for any APIs that already had machine readable API definitions, or would be low hanging fruit for the creation of Swagger definitions, as part of my wider API discovery work.

I had just finished updating all my API Evangelist Network APIs to use verion 0.14 of APIs.json, and while I wait for the search engine APIs.io to update to support the new version, I wanted to see if I could start the hard work of applying API discovery to federal government APIs. 

Ideally all federal agencies would publish APIs.json on their own, placing it within the root of their domain, like they do with data.json, and provide an index of all of their APIs. Being all to familiar with how this stuff work, I know that if I want this to happen, I will have to generate APIs.json for many federal agencies first. However for the APis.json to have their intended impact, I need many of the APIs to have machine readable API definitions that I can point to--which equals more work for me! yay? ;-(

My thinking is that I will look through all of the 77 developer areas, and resulting APIs looking for the low hanging fruit. Basically I would grade each API on its viability to be included in my federal government API discovery work. I spent minimal amount of time look at each API, and in some cases looking for the API, before giving up. I would inspect the supporting developer area, and the actual interface for complexity, helping me understand how hard it would be to hand craft a Swagger spec, and APIs.json for each agency and their APIs. 

(warning contains my raw un-edited notes from doing this research, not suitable for children)

As I went through, I wrote a couple of notes:

  • National Climate Data Center is nice looking, and is a high profile--they should have a kick ass API!
  • Inversely NOAAA Climate Data Online very simple, clean and well done.
  • Department of Education is acceptable as dev area, only because of Socrata
  • National Renewable Energy Laboratory just gets it. They just get it.
  • Some of these are billed as developer areas, but really just a single API. It is a start I guess. 
  • I love me some Department of Labor. Their developer area and API is freak'n cool!
  • MyUSA citizen API has oAuth!!! WTF. How did I not notice this before? Another story, and work here.
  • MyUSA has really good, simple, high value, API resources. 
  • NASA ExoAPI not just API cool, but space cool!!
  • FOIA needs a fucking API. No excuses. FOIA needs an API!
  • Some APIs it might be better to go back to data source and recreate API from scratch, they are so bad.

I wanted to share some of my notes, before the long list of developer areas, and their APIs. There are some specific notes for each APIs, but much of it is very general, helping grade each API, so I can go back through the list of B grade or higher APIs, and figure out which are candidates for me to create a Swagger API definition, APIs.json and ultimately adding to APIs.io. 

For this work I went down the 77 federal agency links, which were billed as developer areas, but many were single APIs. So when a developer area resulted in multiple APIs, I grouped them together, and many of the agencies who have a single API I will group together, and include my commentary as necessary. I'm leaving the URLs visible to help as a reference, show the craziness of some of them, and because it would have been sooooo much work to apply all of them.

Let's start with the White House(http://www.whitehouse.gov/developers):

Next up is the USDA (http://www.usda.gov/wps/portal/usda/usdahome?navid=USDA_DEVELOPER), which is a hodgepodge of service, no consistency whatsoever between services in interface, supporting content or anything. 

Overall I give USDA a D on all their APIs. A couple might be high value sources, and going after, but definitely not low hanging fruit for me. It would be easier to tackle as independent project for generating brand new APIs.

Next up is Department of Commerce (http://www.commerce.gov/developer), who definitely high some higher value resources, as well as some health API initiatives. 

Next with the Department of Defense (http://www.defense.gov/developer/)There are 8 things billed as aPIs, with a variety of datasets, API like things, and web services available.  Not really sure whats up? (D)

We have one by itself here:

Then the department of education who is just riding their data.gov work as API area:

  • Department of Education - http://www.ed.gov/developers - Lots of high value datasets. Says API, but is JSON file. Wouldn’t be hard to generate APIs for it all and make machine readable definitions. (B)

Next some energy related efforts:

  • Department of Energy - http://www.energy.gov/developers - Lots of datasets. Pretty presentation.  Could use some simple APIs,. Wouldn’t be much to pick high value data sets and create cache of them. (C)
  • Energy Information Administration - http://www.eia.gov/developer/ - Nice web API, simple clean presentation. Needs interactive docs. (B)
  • National Renewable Energy Laboratory - http://developer.nrel.gov/ - Close to a modern Developer area with web APIs. Uses standardized access (umbrella). Some of them have Swagger specs, the rest would be easy to create. (A)
  • Office of Scientific and Technical Information - http://www.osti.gov/XMLServices - Interfaces are pretty well designed, and Swagger specs would be straightforward. But docs are all PDF currently. (B)

Moving on to the Department of Health and Human Services (http://www.hhs.gov/developer), which all of their APis are somewhat cosistent, and provide simple resources:

The Food and Drug Administration (http://open.fda.gov) is one of the agencies that is definitely getting on board with APIs, they have some pretty nice implementations, but there there are some not so nice ones that need a lot of work:

Next up the Department of Homeland Security (http://www.dhs.gov/developer), where they have three APIs (its a start):

Then we have two agencies that have pretty simple API operations, so I'll group together:

Then we have several API developer efforts under the Department of Interior (http://www.doi.gov/developer):

Now we have some APIS coming out of law enforcement side of government, starting with Department of Justice (http://www.justice.gov/developer):

Now we get to one of my favorite afforts in the federal government

  • Department of Labor - http://developer.dol.gov/ - I love their developer area. They have a great API, easy to generate API definitions. (A)
  • Bureau of Labor Statistics - http://www.bls.gov/developers/ - Web APIs in there. Complex, and lots of work, but can be done. API Definitions Needed. (B)

Next we have the API efforts from Department of State (http://www.state.gov/developer):

Moving on to the Department of Transportation (http://www.dot.gov/developer):

Now let's head over to the Department of the Treasury (http://www.treasury.gov/developer):

The Department of Veterans Affairs (http://www.va.gov/developer) has some hope, because of the work I did in the fall.

Moving to another on of my favorite agencies, well quasi gov agencies:

One agency that appears to be on radar, but I really can't tell what is going on API wise:

  • Environmental Protection Agency - http://www.epa.gov/developer/ - There is a really nice layout to the area, with seemingly a lot of APIs, and they look like web APIs, but it looks like one API being represented as a much of methods? Would be too much work, but still hard to figure out WTF. (C)

The the Federal Communications Commission (http://www.fcc.gov/developers) has a lot of APIs going on, in various states of operation:

All by itself on the list, we have a bank one lonely bank:

  • Federal Reserve Bank of St. Louis - http://api.stlouisfed.org/ - Good API and area, would be easy to generate API definitions. (B)

The General Services Administration (http://www.gsa.gov/developers/) definitely is ahead of the game when it comes to API design and deployment:

Once I reached the National Aeronautics and Space Administration http://open.nasa.gov/developer I found some really, really cool APIs:

Grouping a couple loose agencies together:

The Recovery Accountability and Transparency Board (http://www.recovery.gov/arra/FAQ/Developer/Pages/default.aspx) has some APIs to look at: 

The Small Business Administration (http://www.sba.gov/about-sba/sba_performance/sba_data_store/web_service_api) has some nice APIs that are consistent and well presented:

Lasty, we have a couple of loose agencies to look at (or not):

Ok that was it. I know there are more APIs to look at, but this is derived from the master list of federal government developer portals. This gives me what I need. Although, I'm a little disappointed I have less than 5 Swagger definitions, after looking at about 190 APIs. 

After looking at all of this, I'm overwhelmed. How do you solve API discovery for a mess like this? Holy shit!

I really need my fucking head examined for taking this shit on. I really am my own worst enemy, but I love it. I am obsessed with contributing to a solution for API discovery that will work in private sector, as well as a public sector mess like this. So where the hell do I start?  More to come on that soon...

See The Full Blog Post


Building Blocks Of API Deployment

As I continue my research the world of API deployment, I'm trying to distill the services, and tooling I come across, down into what I consider to be a common set of building blocks. My goal with identifying API deployment building blocks is to provide a simple list of what the moving parts are, that enable API providers to successfully deploy their services.

Some of these building blocks overlap with other core areas of my research like design, and management, but I hope this list captures the basic building blocks of what anyone needs to know, to be able to follow the world of API deployment. While this post is meant for a wider audience, beyond just developers, I think it provides a good reminder for developers as well, and can help things come into focus. (I know it does for me!)

Also there is some overlap between some of these building blocks, like API Gateway and API Proxy, both doing very similiar things, but labeled differently. Identifying building blocks for me, can be very difficult, and I'm constantly shifting definitions around, until I find a comfortable fit--so some of these will evolve, especially with the speed at which things are moving in 2014.

CSV to API - Text files that contain comma separate values or CSVs, is one of the quickest ways to convert existing data to an API. Each row of a CSV can be imported and converted to a record in a database, and easily generate a RESTful interface that represents the data stored in the CSV. CSV to API can be very messy depending on the quality of the data in the CSV, but can be a quick way to breathe new life into old catalogs of data lying around on servers or even desktops. The easiest way to deal with CSV is to import directly into database, than generate API from database, but the process can be done at time of API creation.
Database to API - Database to API is definitely the quickest way to generate an API. If you have valuable data, generally in 2013, it will reside in a Microsoft, MySQL, PostgreSQL or other common database platform. Connecting to a database and generate a CRUD, or create, read, updated and delete API on an existing data make sense for a lot of reason. This is the quickest way to open up product catalogs, public directories, blogs, calendars or any other commonly stored data. APIs are rapidly replace database connections, when bundled with common API management techniques, APIs can allow for much more versatile and secure access that can be made public and shared outside the firewall.
Framework - There is no reason to hand-craft an API from scratch these days. There are numerous frameworks out their that are designed for rapidly deploying web APIs. Deploying APIs using a framework is only an option when you have the necessary technical and developer talent to be able to understand the setup of environment and follow the design patterns of each framework. When it comes to planning the deployment of an API using a framework, it is best to select one of the common frameworks written in the preferred language of the available developer and IT resources. Frameworks can be used to deploy data APIs from CSVs and databases, content from documents or custom code resources that allow access to more complex objects.
API Gateway - API gateways are enterprise quality solutions that are designed to expose API resources. Gateways are meant to provide a complete solution for exposing internal systems and connecting with external platforms. API gateways are often used to proxy and mediate existing API deployments, but may also provide solutions for connecting to other internal systems like databases, FTP, messaging and other common resources. Many public APIs are exposed using frameworks, most enterprise APIs are deployed via API gateways--supporting much larger ideployments.
API Proxy - API proxy are common place for taking an existing API interface, running it through an intermediary which allows for translations, transformations and other added services on top of API. An API proxy does not deploy an API, but can take existing resources like SOAP, XML-RPC and transform into more common RESTful APIs with JSON formats. Proxies provide other functions such as service composition, rate limiting, filtering and securing of API endpoints. API gateways are the preffered approach for the enterprise, and the companies that provide services support larger API deployments.
API Connector - Contrary to an API proxy, there are API solutions that are proxyless, while just allowing an API to connect or plugin to the advanced API resources. While proxies work in many situations, allowing APIs to be mediated and transformed into required interfaces, API connectors may be preferred in situations where data should not be routed through proxy machines. API connector solutions only connect to existing API implementations are easily integrated with existing API frameworks as well as web servers like Nginx.
Hosting - Hosting is all about where you are going to park your API. Usual deployments are on-premise within your company or data center, in a public cloud like Amazon Web Services or a hybrid of the two. Most of the existing service providers in the space support all types of hosting, but some companies, who have the required technical talent host their own API platforms. With HTTP being the transport in which modern web APIs put to use, sharing the same infrastructure as web sites, hosting APIs does not take any additional skills or resources, if you already have a web site or application hosting environment.
API Versioning - There are many different approaches to managing different version of web APIs. When embarking on API deployment you will have to make a decision about how each endpoint will be versioned and maintained. Each API service provider offers versioning solutions, but generally it is handled within the API URI or passed as an HTTP header. Versioning is an inevitable part of the API life-cycle and is better to be integrated by design as opposed to waiting until you are forced to make a evolution in your API interface.
Documentation - API documentation is an essential building block for all API endpoints. Quality, up to date documentation is essential for on-boarding developers and ensuring they successfully integrate with an API. Document needs to be derived from quality API designs, kept up to date and made accessible to developers via a portal. There are several tools available for automatically generting documentation and even what is called interactive documentation, that allows for developers to make live calls against an API while exploring the documentation. API documentation is part of every API deployment.
Code Samples - Second to documentation, code samples in a variety of programming languages is essential to a successful API integration. With quality API design, generating samples that can be used across multiple API resources is possible. Many of the emerging API service providers and the same tools that generate API documentation from JSON definitions can also auto generate code samples that can be used by developers. Generation of code samples in a variety of programming languages is a requirement during API deployment.
Scraping - Harvesting or scraping of data from an existing website, content or data source. While we all would like content and data sources to be machine readable, sometimes you have just get your hands dirty and scrape it. While I don't support scraping of content in all scenarios, and business sectors, but in the right situations scraping can provide a perfectly acceptable content or data source for deploying an API.
Container - The new virtualization movement, lead by Docket, and support by Amazon, Google, Red Hat, Microsoft, and many more, is providing new ways to package up APIs, and deploy as small, modular, virtualized containers.
Github - Github provides a simple, but powerful way to support API deployment, allowing for publsihing of a developer portal, documentation, code libraries, TOS, and all your supporting API business building blocks, that are necessary for API effort. At a minimum Github should be used to manage public code libraries, and engage with API consumers using Github's social features.
Terms of Use / Service - Terms of Use provide a legal framework for developers to operate within. They set the stage for the business development relationships that will occur within an API ecosystem. TOS should protect the API owners company, assets and brand, but should also provide assurances for developers who are building businesses on top of an API. Make sure an APIs TOS pass insepection with the lawyers, but also strike a healthy balance within the ecosystem and foster innovation.

If there are any features, service or tools you depend on when deploying your APIs, please let me know at @kinlane. I'm not trying to create an exhaustive list, I just want to get idea for what is available across the providers, and where the gaps are potentially. 

I'm feel like I'm finally getting a handle on the building blocks for API design, deployment, and management, and understanding the overlap in the different areas. I will revisit my design and management building blocks, and evolve my ideas of what my perfect API editor would look like, and how this fits in with API management infrastructure from 3Scale, and even API integration.

Disclosure: 3Scale is an API Evangelist partner.

See The Full Blog Post


APIs.json API Property Types

I’m working the great feedback we've had on APIs.json, an adding everything to the Github issues for consideration in the next version. Today I’m spending a little time thinking through the big picture of APIs.json, and some of the building blocks I'd like to see reflected when API providers generate their APIs.json.

Each API listed in an APIs.json has what we are calling: "Properties Elements”. The properties element is a collection, with two values: type and url. While we provide you with a base set of property element types you can reference:

  • Swagger
  • RAML
  • Blueprint
  • WADL
  • WSDL
  • TermsOfService
  • InterfaceLicense
  • StatusPage
  • Pricing
  • Forums
  • AlertsTwitterHandle

Our goal is to continue providing, “reserved” types that we recognize, while also leaving properties elements, being as organic as possible—meaning you can define your own references, and tell the story of why these are important building blocks in your own API strategy. We will continue adding the best properties we see being used, to the APIs.json spec.

To prepare for the next version of APIs.json, I want to have the next list of reserved property types. Working from my list of API management building blocks I’ve identified X I’d like to see in the next version:

  • GettingStarted
  • FrequentlyAskedQuestions
  • Signup
  • BestPractices
  • ServiceAccord
  • Documentation
  • Explorer
  • ErrorCodes
  • AuthenticationOverview
  • AuthenticationTester
  • CodeLibraries
  • ApplicationGallery
  • SoftwareDevelopmentKits
  • StackExchange
  • Calendar
  • OfficeHours
  • Blog
  • BlogRSS
  • LinkedIn
  • Twitter
  • Github
  • Facebook
  • GooglePlus
  • Roadmap
  • ChangeLog
  • RateLimits
  • Affiliate
  • Advertising
  • CaseStudies
  • WhitePapers
  • HowToGuides
  • Webinars
  • Ideas
  • Labs
  • Opportunities
  • Branding
  • PrivacyPolicy
  • ServiceLevelAgreement
  • DataLicense
  • CodeLicense
  • DeprecationPolicy
  • Widgets
  • Buttons
  • Badges

These are the building blocks I think are important to API operations. Currently all of these will be links to human readable pages, within an APIs developer portal, but eventually I envision all of these potentially being machine readable.

I know, this is a big vision, but I intend to make it a reality. The first machine readable element on this list is the InterfaceLicense, which will reference the machine readable JSON manifest for API Commons.

Next on the list is TermsOfService, which I will be using Terms of Service Didn’t Read’s machine readable format, and applying it to the world of APIs. If there are any types you’d like to see in the next version of APIs.json, head over to the Github issue I created for this discussion, and make sure it is on the list.

See The Full Blog Post


If I Could Design My Perfect API Design Editor

I’ve been thinking a lot about API design lately, the services and tooling coming from Apiary, RAML and Swagger, and wanted to explore some thoughts around what I would consider to be killer features for the killer API design editor. Some of these thoughts are derived from the features I’ve seen in Apiary and RAML editor, and most recently the Swagger Editor, but I’d like to *riff* on a little bit and play with what could be the next generation of features.

While exploring my dream API design editor, I’d like to walk through each group of features, organized around my indentations and objectives around my API designs.

Getting Started
When kicking off the API design process, I want to be able to jumpstart the API design lifecycle from multiple sources. There will be many times that I want to start from a clean slate, but many times I will be working from existing patterns.

  • Blank Canvas - I want to start with a blank canvas, no patterns to follow today, I’m painting my masterpiece. 
  • Import Existing File - I have a loose API design file laying around, and I want to be able to open, import and get to work with it, in any of the formats. 
  • Fork From Gallery - I want to fork one of my existing API designs, that I have stored in my API design taller (I will outline below). 
  • Import From API Commons - Select an existing API design pattern from API Commons and import into editor, and API design gallery.

My goals in getting started with API design, will be centered around re-use the best patterns across the API space, as well as my own individual or company API design gallery. We are already mimicking much of this behavior, we just don’t have a central API design editor for managing these flows.

Editing My API Design
Now we get to the meat of the post, the editor. I have several things in mind when I’m actually editing a single API definition, functions I want, actions I want to take around my API design. These are just a handful of the editor specific features I’d love to see in my perfect API design editor.

  • Multi-Lingual - I want my editor to word with API definitions in API Blueprint, RAML and Swagger. I prefer to edit my API designs in JSON, but I know many people I work with will prefer markdown or YAML based, and my editor needs to support fluid editing between all popular formats. 
  • Internationalization - How will I deal with making my API resources available to developers around the world? Beyond API definition langugages, how do I actually make my interfaces accessible, and understood by consuers around the glob.e
  • Dictionary - I will outline my thoughts around a central dictionary below, but I want my editor to pull from a common dictionary, providing a standardized language that I work from, as well as my company when designing interfaces, data models, etc. 
  • Annotation - I want to be able to annotate various aspects of my API designs and have associated notes, conversation around these elements of my design. 
  • Highlight - Built in highlighting would be good to support annotations, but also just reference various layers of my API designs to highlighting during conversations with others, or even allowing the reverse engineer of my designs, complete with the notes and layers of the onions for others to follow. 
  • Source View - A view of my API design that allows me to see the underlying markdown, YAML, or JSON and directly edit the underlying API definition language. 
  • GUI View - A visual view of my API design, allowing for adding, editing and removing elements in an easy GUI interface, no source view necessary for designing APIs. 
  • Interactive View - A rendered visual view of my API, allowing me to play with either my live API or generated mock API, through interactive documentation within my editors. 
  • Save To Gallery - When I’m done working with my API designs, all roads lead to saving it to my gallery, once saved to my working space I can decide to take other actions. 
  • Suggestions - I want my editor to suggest the best patterns available to me from private and public sources. I shouldn't ever design my APIs in the dark.

The API design editor should work like most IDE’s we see today, but keep it simple, and reflect extensibility like GIthub’s Atom editor. My editor should give me full control over my API designs, and enable me to take action in many pre-defined or custom ways one could imagine.

Taking Action
My API designs represent the truth of my API, at any point within its lifecycle, from initial conception to deprecation. In my perfect editor I should be able to take meaningful actions around my API designs. For the purposes of this story I’m going to group actions into some meaningful buckets, that reflect the expanding areas of the API lifecycle. You will notice the four areas below, reflect the primary areas I track on via API Evangelist.

Design Actions
Early on in my API lifecycle, while I’m crafting new designs, I will need to take action around my designs. Designs actions will help me iterate on designs before I reach expensive deployment and management phases.

  • Mock Interface - With each of my API designs I will need to generate mock interfaces that I can use to play with what my API will deliver. I will also need to share this URL with other stakeholders, so that they can play with, and provide feedback on my API interface. 
  • Copy / Paste - API designs will evolve and branch out into other areas. I need to be able to copy / paste or fork my API designs, and my editor, and API gallery should keep track of these iterations so I don’t have to. The API space essentially copy and pastes common patterns, we just don’t have a formal way of doing it currently. 
  • Email Share - I want to easily share my API designs via email with other key stakeholders that will be part of the API lifecycle. Ideally I wouldn’t be emailing around the designs themselves, just pointers to the designs and tools for interacting within the lifecycle. 
  • Social Share - Sometimes the API design process all occur over common social networks, and in some cases be very public. I want to be able to easily share all my API designs via my most used social networks like Github, Twitter and LinkedIn. 
  • Collaboration - API design should not be done in isolation, and should be a collaborative process with all key stockholders. I would like to to even have Etherpad style real-time interactions around the design process with other users.

API design actions are the first stop, in the expanding API design lifecycle. Being able to easily generate mocks, share my interfaces and collaborate with other stakeholders. Allowing me to quickly, seamlessly take action throughout the early design cycles will save me money, time and resources early on—something that only become more costly and restrictive later on in the lifecycle.

Deployment Actions
Next station in the API design lifecycle, is being able to deploy APIs from my designs. Each of the existing API definition formats provide API deployment solutions, and with the evolution in cloud computing, we are seeing even more complete, modular ways to take action around your API designs.

  • Server - With each of my API designs, I should be able to generate server side code in the languages that I use most. I should be able to register specific frameworks, languages, and other defining aspects of my API server code, then generate the code and make available for download, or publish using Github and FTP. 
  • Container - Cloud computing has matured, producing a new way of deploying very modular architectural resources, giving rise to a new cloud movement, being called containers. Container virtualization will do for APIs, what APIs have done for companies in the last 14 years. Containers provide a very defined, self-contained way of deploying APIs from API design blueprints, ushering a new ay of deploy API resources in coming years.

I need help to deploy my APIs, and with container solutions like Docker, I should have predefined packages I can configure with my API designs, and deploy using popular container solutions from Google, Amazon, or other coud provider.

Management Actions
After I deploy an API I will need to use my API definitions as a guide for an increasing number of areas of my management process, not just the technical, but the business and politics of my API operations.

  • Documentation - Generating of interactive API documentation is what kicked off the popularity of API design, and importance of API definitions. Swagger provider the Swagger UI, and interactive, hands-on way of learning about what an API offered, but this wasn’t the only motivation—providing up to date documentation as well, added just the incentives API providers needed to generate machine readable documentation.
  • Code - Second to API documentation, providing code samples, libraries, and SDKS is one of the best ways you can eliminate friction when on boarding new API users. API definitions provide a machine readable set of instructions, for generating the code that is necessary throughout the API management portion of the API lifecycle. 
  • Embeddable - JavaScript provides a very meaningful way to demonstrate the value of APis, and embeddable JavaScript should always be part of the API lifecycle. Machine readable API definitions can easily generate visualizations that can be used in documentation, and other aspects of the API lifecycle.

I predict, with the increased adoption of machine readable API formats like API Blueprint, RAML and Swagger, we will see more layers of the API management process be expanded on, further automating how we manage APis.

Discovery Actions
Having your APIs found, and being able to find the right API design for integration, are two sides of an essential coin in the API lifecycle. We are just now beginning to get a handle on what is need when it comes to API discovery.

  • APIs.json - I should be able to organize API designs into groupings, and publish an APIs.json file for these groups. API designs should be able to be organized in multiple groups, organized by domain and sub-domain. 
  • API Commons - Thanks to Oracle, the copyright of API of API definitions will be part of the API lifecycle. I want the ability to manage and publish all of my designs to the API Commons, or any other commons for sharing of API designs.

The discovery of APIs has long been a problem, but is just now reaching the critical point where we have to start develop solutions for not just finding APIs, but also understanding what they offer, and the details of of the interface, so we can make sense of not just the technical, but business and political decisions around API driven resources.

Integration Actions
Flipping from providing APIs to consuming APIs, I envision a world where I can take actions around my API designs, that focus on the availability, and integration of valuable API driven resources. As an API provider, I need as much as assistance as I can, to look at my APIs from an external perspective, and being able to take action in this area will grow increasingly important.

  • Testing - Using my machine readable API definitions, I should be able to publish testing definitions, that allow the execution of common API testing patterns. I’d love to see providers like SmartBear, Runscope, APITools, and API Metrics offer services around the import of API design generated definitions. 
  • Monitoring - Just like API testing, I want to be able to generate definition that allow for the monitoring of API endpoints. My API monitoring tooling should allow for me to generate standard monitoring definitions, and import and run them in my API monitoring solution.

I’d say that API integration is the fastest growing area of the AP space, second only to API design itself. Understanding how an API operates, from an integrators perspective is valuable, not just to the integrator, but also the provider. I need to be thinking about integration issues early on in the API design lifecyle to minimize costly changes downstream.

Custom Actions
I’ve laid out some of the essential actions I’d like to be able to take around my API definitions, throughout the API lifecycle. I expect the most amount of extensibility from my API design editor, in the future, and should be able to extend in any way that I need.

  • Links - I need a dead simple way to take an API design, and publish to a single URL, from within my editor. This approach provides the minimum amount of extensibility I will need in the API design lifecycle. 
  • JavaScript - I will need to run JavaScript that I write against all of my API designs, generating specific results that I will need throughout the API design process. My editor should allow me to write, store and execute JavaScript against all my API designs. 
  • Marketplace - There should be a marketplace to find other custom actions I can take against my API designs. I want a way to publish my API actions to the marketplace, as well as browse other API actions, and add them to my own library.

We’ve reached a point where using API definitions like API Blueprint, RAML, and Swagger are common place, and being able to innovate around what actions we take throughout the API design lifecycle will be critical to the space moving forward, and how companies take action around their own APIs.

API Design Gallery
In my editor, I need a central location to store and manage all of my API designs. I’m calling this a gallery, because I do not want it only to be a closed off repository of designs, I want to encourage collaboration, and even public sharing of common API design patterns. I see several key API editor features I will need in my API design gallery.

  • Search - I need to be able to search for API designs, based upon their content, as well as other meta data I assign to my designs. I should be able to easily expose my search criteria, and assist potential API consumers in finding my API designs as well. 
  • Import - I should be able to import any API design from a local file, or provide a public URL and generate local copy of any API design. Many of my Api designs will be generated from an import of existing definition. 
  • Versioning - I want the API editor of the future to track all versioning of my API designs. Much like managing the code around my API, I need the interface definitions to be versioned, and the standard feature set for managing this process. 
  • Groups - I will be working on many API designs, will various stakeholders in the success of any API design. I need a set of features in my API design editor to help me manage multiple groups, and their access to my API designs. 
  • Domains - Much like the Internet itself, I need to organize my APIs by domain. I have numerous domains which I manage different groups of API resources. Generally I publish all of my API portals to Github under a specific domain, or sub-domain—I would like this level of control in my API design editor. 
  • Github - Github plays a central role in my API design lifecycle. I need my API design editor to help me manage everything, via public and private Github repository. Using the Github API, my API design editor should be able to store all relevant data on Github—seamlessly. 
  • Diff - What are the differences between my API designs? I would like to understand the difference between each of my API resource types, and versions of each API designs. It might be nice if I could see the difference between my API designs, and other public APIs I might consider as competitors. 
  • Public - The majority of my API designs will be public, but this won’t be the case with every designer. API designers should have the control over whether or not their API designs are public or private.

My API design gallery will be the central place i work from. Once I reach a critical mass of designs, I will have many of the patterns I need to design, deploy and manage my APIs. It will be important for me to have access to import the best patterns from public repositories like API Commons. To evolve as an API designer, I need to easily create, store, and evolve my own API designs, while also being influenced by the best patterns available in the public domain.

Embeddable Gallery
Simple visualization can be an effective tool in helping demonstrate the value an API delivers. I want to be able to manage open, API driven visualizations, using platforms like D3.js. I need an arsenal of embeddable, API driven visualizations to help tell the store of the API resources I provide, give me a gallery to manage them.

  • Search - I want to be able to search the meta data around the API embeddable tools I develop. I will have a wealth of graphs, charts, and more functional, JavaScript widgets I generate. 
  • Browse - Give me a way to group, and organize my embeddable tools. I want to be able to organize, group and share my embeddable tools, not just for my needs, but potentially to the public as well.

A picture is worth a thousand words, and being able to easily generate interactive visualizations, driven by API resources, that can be embedded anywhere is critical to my storytelling process. I will use embeddable tools to tell the story of my API, but my API consumers will also use these visualizations as part of their efforts, and hopefully develop their own as well.

API Dictionary
I need a common dictionary to work from when designing my APIs. I need to use consistent interface names, field names, parameters, headers, media types, and other definitions that will assist me in providing the best API experience possible.

  • Search - My dictionary should be available to me in any area of my API design editor, and in true IDE style, while I’m designing. Search of my dictionary, will be essential to my API design work, but also to the groups that I work with. 
  • Schema.org - There are plenty of existing patterns to follow when defining my APIs, and my editor should always assist me in adopting, and reusing any existing pattern I determine as relevant to my API design lifecycle, like Schema.org.
  • Dublin Core - How do I define the metadata surrounding my API designs? My editor should assist me to use common metadata patterns available like Dublin Core.
  • Media Types - The results of my API should conform to existing document representations, when possible. Being able to explore the existing media types available while designing my API would help me emulate existing patterns, rather than reinventing the wheel each time I design an API. 
  • Custom - My dictionary should be able to be driven by existing definitions, or allow me to import and and define my own vocabulary based upon my operations. I want to extend my dictionary to meet the unique demands of my API design lifecycle.

I want my API design process to be driven by a common dictionary that fits my unique needs, but borrows from the best patterns already available in the public space. We already emulate many of the common patterns we come across, we just don’t have any common dictionary to work from, enforcing healthy design via my editor.

An Editor For Just My Own API Design Process
This story has evolved over the last two weeks, as I spent time in San Francisco, discussing API design, then spending a great deal of time driving, and thinking about the API design lifecycle. This is all part of my research into the expanding world of API design, which will result in a white paper soon, and my intent is to just shed some light on what might be some of the future building blocks of the API design space. My thoughts are very much based in my own selfish API design needs, but based upon what i’m seeing in the growing API design space.

An Editor For A Collective API Design Process
With this story, I intend to help keep the API design process a collaborative, and when relevant a public affair. I want to ensure we work from existing patterns that are defined in the space, and as we iterative and evolve APIs, we collectively share our best patterns. You should not just be proud of your API designs, and willing to share publicly, you should demonstrate the due diligence that went into your design, attribute the patterns you used to contribute to your designs, and share back your own interpretation—encouraging re-use and sharing further downstream.

What Features Would Be Part of Your Perfect API Design Editor
This is my vision around the future of API design, and what I’d like to have in my editor—what is yours? What do you need as part of your API design process? Are API definitions part of the “truth” in your API lifecycle? I’d love to hear what tools and services you think should be made available, to assist us in designing our APIs.

Disclosure: I'm still editing and linking up this post. Stay tuned for updates.

See The Full Blog Post


Adding Data Visualization Layer to Interactive API Documentation

I recently reviewed a new API initiative from the Food & Drug Administration, called OpenFDA. I gave a whole list of things that they did right when launching the API, but one item that I thought was particularly interesting, was the actual interactive documentation for the Drugs API endpoint.

I talk a lot about interactive documentation for APIs, something that has become commonplace, and a building block that developers are starting to expect. What is different about the OpenFDA Drug API, is that the interactive documentation provides a visual interface for building API calls, going beyond the interactive, and often very form based documentation that is commonly seen in other developer areas.

Via the OpenFDA Drug API documentation you can actually build an API query by selecting from radio button values, which then updates the resulting URL query, some summary text, and generates a graph visualization of the resulting query. After building your filter, you can run the API query, and see the request and response, which is a common feature other interactive API documentation implementations.

The addition of a visualization, that is driven by each endpoint is very interesting, and something I’d like to see baked into the DNA of interactive API documentation. Helping me build an API call, visualize and understand the value contained within an API has huge potential. Currently we have Swagger, API Blueprint, and RAML generated interactive documentation solution, which are pretty similar—I’d love to see more visualizations integrated into future interactive documentation implementations.

See The Full Blog Post


The Future Of Public Private Sector Partnerships Being Negotiated At The API oAuth Scope Level

A couple of weeks ago I attended a two day API specification session between major California utilities, Southern California Edison (SCE), San Diego Gas & Electric (SDG&E), and Pacific Gas and Electric (PG&E), that was organized by Hypertek Inc. for National Institute of Standards and Technology (NIST), that is looking to push forward the Green Button data and API agenda of the White House and Department of Energy.

The Green Button API and open data model already exists, but the current hurdle for the initiative is to get leading utilities to agree to specific implementation definitions that serve their customers, so it can be ratified as a standard. This entire two day session was dedicated to walking through line by line, and establish the oAuth scope that each of the three utility companies would implementing when providing Green Button data via the API to 3rd party developers, who are building solutions for utility customers.

An example of this in the wild, would be if a utility customer wanted to get a quote for a rooftop solar installation, the installer could use a software solution that was developed by a 3rd party vendor, that pulls that customers energy usage via the Green Button API, and generate a precise quote for the number of solar panels they’d need to cover their energy usage. Now this is just one example of how energy data could be used, but a very powerful and relevant one in 2014, that give customers access and control over their data.

Before we even get there, the Green Button API definition, data model, and oAuth scope has to be finalized with utility providers, before it can be submitted as a standard—with the final oAuth scope being what will be agreed to by each 3rd party developer that integrates with each utility's Green Button API. This oAuth scope sets the tone for the conversation that 3rd party software providers, and vendors can ultimately have with utility customers around their private utility data.

In my opinion this is one potential model for how industry operations will be negotiated in the future. While not all API definitions, data models and oAuth scopes will be defined by the government then negotiated with industries, but oAuth will be where this scope is negotiated between industry leaders and governments, no matter which side leads the conversation. Governments and industries working together to define API standards is nothing new, but what is new, is the presence of the oAuth layer which gives end-users, and citizens an active role. 3rd party developers and end-users do not get a place in the negotiations, but they do when it comes to putting valuable industry data to use in new ways--or not, which will flow back upstream and influence future iterations of APIs, data models and oAuth scope.

This introduction of the oAuth layer in how industries operate, potentially coupled with the access and innovation that can occur via API platforms when they are executed in alignment with modern API implementations, will change how industries grow and ultimately how power flows (pun intended). This evolution in how the public and private sector partner will not always positive by default, I’m not an API solutionist in that I believe APIs bless everything as good, but with the right players at the table, a little sunlight and transparency in the process, and a feedback loop that includes 3rd party developers and end-users, we might be able to implement meaningful change across many different industries around the globe.

See The Full Blog Post


Time Tracking Platform Harvest Moves API Docs and App Showcase to Github

Time Tracking API platform Harvest has embraced Github as part of their API ecosystem. I'm always on the hunt for examples of API providers using Github, so I figured I'd showcase Harvest's creative use of the social coding platform.

Starting with their documentation, the Harvest team has moved the API documentation to a Github repository, allowing developers to "watch" the API, get updates when changes are made, asks questions or even contribute to the API docs by submitting a pull request.

Harvest is also using the wiki portion of their Github repo for a developer application gallery they are calling Community Creations and Hacks, where they showcase innovative uses of the Harvest API--currently displaying 20 integrations by Harvest users.

I'm currently tracking on 11 separate uses of Github for API management, and always on the hunt for new ways to use Github to support API ecosystems. Nice move Harvest!

See The Full Blog Post


Can Swagger Deliver a RESTful API Discovery Service?

There is a lot of discussion around the growth of APIs, and what the future will look like. How will we discover and make sense of the number of available APIs, and quickly get to work integrating with the APIs that bring the most value to our apps and businesses.

One technology that comes up in every conversation I’ve had is Swagger. What is Swagger?

Swagger is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services.

The goal of Swagger is to enable client and documentation systems to update at the same pace as the server. The documentation of methods, parameters and models are tightly integrated into the server code, allowing APIs to always stay in sync.

Swagger was born out of initiatives from Wordnik, developed for Wordnik’s own use during the development of developer.wordnik.com. Swagger development began in early 2010 and the framework being released is used by Wordnik’s APIs, which power both internal and external API clients.

Swagger provides a declarative resource specification, allowing users to understand and consume services without knowledge of server implementation, enabling both developers and non-developers to interact with the API, providing clear insight into how the API responds to parameters and options.

I’m familiarizing myself with the specification more and playing with the various tools they provide:

  • Swagger UI - A dependency-free collection of HTML, Javascript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API
  • Swagger Core - Defines Java annotations and required logic to generate a Swagger server or client.
  • Swagger CodeGen - Contains a template-driven engine to generate client code in different languages by parsing your Swagger Resource Declaration.
  • Swagger node.js - A Sample App is a fully-functioning, stand-alone Swagger server written in javascript which uses node.js and the express framework.
  • Swagger Scala Sample App - A fully-functioning, stand-alone Swagger server written in Scala which demonstrates how to enable Swagger in your API.
  • Swagger Java Sample App - A fully-functioning, stand-alone Swagger server written in Java which demonstrates how to enable Swagger in your API.

I understand that Swagger is not the one specification to rule all APIs, and it won’t make all religious API fanatics happy. But I want to start somewhere. I see three main benefits for API owners coming from adopting Swagger:

  • Automated, consistent generation of clean, beautiful, interactive API documentation
  • Generation of client code and SDK in multiple languages
  • Feeding into an industry wide API discovery language that both developers and non-developers can use

I believe strongly that consistent documentation and code samples ensure an API will get used, but as the number of APIs grows, a system like Google API Discovery Service, will be essential for API adoption across industries and around the globe. I’m hoping to learn more about Swagger, and see if it can help deliver on this vision.

See The Full Blog Post


Google APIs Discovery Service

TheGoogle APIs Discovery Service provides a set of web APIs for discovering metadata across Google APIs.

The discovery service delivers a JSON-based API that provides a directory of supported Google APIs, and a machine-readable discovery document"for each of the supported APIs that includes:
  • List of API resource schemas based on JSON Schema
  • List of API methods and available parameters for each method
  • Available OAuth 2.0 scopes for each API
  • Inline documentation of methods, parameters and available parameter values
Developers can use the Google APIs Discovery Service to build client libraries, IDE plugins and other tools that interact with supported Google APIs.

The Google APIs Discovery Service delivers two things for each supported API:
  • APIs Directory Resource
    • Identification and description information, including name, version, title, and description.
    • Documentation information, including icons and a documentation link.
    • Status information, including status labels, and an indication as to whether or not this is the preferred version of the API.
    • Discovery document link, the URI of the discovery document for this API
  • Discovery Document Resource
    • Schemas, which is a list of API resource schemas that describe the data you have access to in each API
    • Methods, including a list of API methods and available parameters for each method.
    • OAuth scopes, which identifies the list of OAuth scopes available for this API.
    • Inline documentation, which provides brief descriptions of schemas, methods, parameters and available parameter values.
The Google APIs Discovery Service is part of a larger effort by Google to get a handle on their growing number of APIs. Developers find themselves potentially using multiple Google APIs across many application or client projects.

The Google APIs Discovery Service allows developers to find new APIs available in the directory and programmatically discover how the API authenticates, what methods, and parameters are available.

Not many companies have the number of APIs that Google has, and would need an API discovery service. But with the recent growth in web APIs there will be more of a need for API discovery services within specific areas or industries.

See The Full Blog Post