{"API Design"}

API Monitoring Blog Posts

These are posts from the API Evangelist blog that are focused on API monitoring, allowing for a filtered look at my analysis on the topic. I rely on these posts, along with the curated, organizations, APIs, and tools to help paint me a picture of what is going on.

Communication With Consumers Through The Design Of Our APIs

Many of the problems that APIs are often associated with API adoption can often be mitigated via more communication. I track on a number of ways the successful API providers are communicating around their API efforts, but I also like it when API designers and architects communicate through the actual technical design of their APIs. One example of this can be found in the IETF draft submission for The Sunset HTTP Header, by Erik Wilde.

"This specification defines the Sunset HTTP response header field, which indicates that a URI is likely to become unresponsive at a specified point in the future."

In his original post, nothing lasts Forever (and some things disappear according to a schedule), Erik shows us that a little bit of embedded communication like this in the design of our APIs can help make API consumers more in tune with what is going on. It is tough to get people's attention sometimes, and I think sometimes when us engineers are heads down in the code we tune out the regular channels, and baking things in the request and response structure of the API can help out a lot.

I like the concept of baking API communication and literacy into our operations through good API design. This is one aspect of hypermedia API design that I think often gets overlooked by the haterz. I'll keep adding these little building blocks to my API communications research, helping develop ways we can better communicate with our API consumers through our API design--in real time. 

Simple API Design Interface Features

I am on a quest to help improve and standardize the available API design tooling out there, and one aspect of doing this is spending time highlighting the API service providers who have interesting approaches to design embedded in their service.

Top of my list is Restlet with their studio. There are a couple of things going on in Restlet Studio that I think are significant to the API design conversation, and would like to see become commonplace across service providers, and possibly even part of some sort of open source offering.

Restlet Studio has a nice human interface for designing APIs. When you load up an API you are given a simple, clean, yet comprehensive user interface for adding and updating API paths, and other finer details of your design, no developer skills necessary--allowing anyone to step up and help define the API contract.

Next, when you look at the bottom of your API design in Restlet Studio you are given a design, OpenAPI 2.0, and RAML 1.0 view of your API, allowing you to switch from user interface to a machine-readable definition of the API contract in two leading formats. This API contract will continue to define your API at every stop along the life cycle, and it significantly helps that this contract is human readable in YAML and Markdown. All API design editors should abstract away as much as they possibly can regarding transformations between API definition formats (use the API Transformer API).

I like Restlet's simple approach to delivering design tooling at the center of their platform. I'm keeping an eye on a variety of service providers who are innovating in this way, providing usable tooling when it comes to API design. If you are looking for other examples of this in the wild, take a look at APIMATIC or Stoplight--they are both designing high-quality API design interfaces and tooling. When crafting your own API design user interfaces make sure you take the time to study what is already out there, so that you are building on the best practices are in use, and not just reinventing the wheel when it comes to API design.

Disclosure: I am an advisor to APIMATIC, and Restlet is my partner.

From CRUD To An API Design Conversation With Human Services

I am working to take an existing API, built on top of an evolving data schema, and move forward a common API definition that 211 providers in cities across the country can put to use in their operations. The goal with the Human Services Data Specification (HSDS) API specification is to encourage interoperability between 211 providers, allowing organizations to better deliver healthcare and other human services at the local and regional level.

So far, I have crafted a v1.0 OpenAPI derived from an existing Code for America project called Ohana, as well as a very CRUD (Create, Read, Update, and Delete) version 1.1 OpenAPI, with a working API prototype for use as a reference. I'm at a very important point in the design process with the HSDS API, and the design choices I make will stay with the project for a long, long time. I wanted to take pause and open up a conversation with the community about what is next with the APIs design.

I am opening  up the conversation around some of the usual API design suspects like how we name paths, use headers, and status codes, but I feel like I should be also asking the big questions around use of hypermedia API design patterns, or possibly even GraphQL--a significant portion of the HSDS APIs driving city human services will be data intensive, and maybe GraphQL is one possible path forward. I'm not looking to do hypermedia and GraphQL because they are cool, I want them to serve specific business and organizational objectives.

To stimulate this conversation I've created some Github issues to talk about the usual suspects like versioning, filteringpagination, sortingstatus & error codes, but also opening up threads specifically for hypermedia, and GraphQL, and a thread as a catch-all for other API design considerations. I'm looking to stimulate a conversation around the design of the HSDS API, but also develop some API design content that can help bring some folks up to speed on the decision-making process behind the crafting of an API at this scale.

HSDS isn't just the design for a single API, it is the design for potentially thousands of APIs, so I want to get this as right as I possibly can. Or at least make sure there has been sufficient discussion for this iteration of the API definition. I'll keep blogging about the process as we evolve, and settle in on decisions around each of these API design considerations. I'm hoping to make this a learning experience for myself, as well as all the stakeholders in the HSDS project, but also provide a blueprint for other API providers to consider as they are embarking on their API journey, or maybe just the next major version of its release.

Open Source Drag And Drop API Lifecycle Design Tooling

I'm always on the hunt for new ways to define, design, deploy, and manage API infrastructure, and thought the AWS Cloud Formation Designer provides a nice look at where things might be headed. AWS CloudFormation Designer (Designer) is a graphic tool for creating, viewing, and modifying AWS CloudFormation templates, which translates pretty nicely to managing your API infrastructure as well.

While the AWS Cloud Formation Designer spans all AWS services, all the elements are there for managing all the core stops along the API life cycle liked definition, design, DNS, deployment, management, monitoring, and others. Each of the Amazon services is available with a listing of each element available for the service, complete with all the inputs and outputs as connectors on the icons. Since all the AWS services are APIs, it's basically a drag and drop interface for mapping out how you use these APIs to define, design, deploy and manage your API infrastructure.

Using the design tool you can create templates for governing the deployment and management of API infrastructure by your team, partners, and other customers. This approach to defining the API life cycle is the closest I've seen to what stimulated my API subway map work, which became the subject of my keynotes at APIStrat in Austin, TX. It allows API architects and providers to templatize their approaches to delivering API infrastructure, in a way that is plug and play, and evolvable using the underlying JSON or YAML templates--right alongside the OpenAPI templates, we are crafting for each individual API.

The AWS Cloud Formation Designer is a drag and drop UI for the entire AWS API stack. It is something that could easily be applied to Google's API stack, Microsoft, or any other stack you define--something that could easily be done using APIs.json, developing another layer of templating for which resource types are available in the designer, as well as the formation templates generated by the design tool itself. There should be an open source "API formation designer" available, that could span cloud providers, allowing architects to define which resources are available in their toolbox--that anyone could fork and run in their environment.

I like where AWS is headed with their Cloud Formation Designer. It's another approach to providing full lifecycle tooling for use in the API space. It almost reminds me of Yahoo Pipes for the AWS Cloud, which triggers awkward feels for me. I'm hoping it is a glimpse of what's to come, and someone steps up with an even more attractive drag and drop version, that helps folks work with API-driven infrastructure no matter where it runs--maybe Google will get to work on something. They seem to be real big on supporting infrastructure that runs in any cloud environment. *wink wink*

Getting Feedback From Your API Community When Developing APIs

Establishing a feedback loop with your API community is one of the most valuable aspects of doing APIs, opening up your organization to ideas from outside your firewall. When you are designing new APIs or the next generation of your APIs, make sure you are tapping into the feedback loop you have already created within your community, by providing access to the alpha, beta, and prototype versions of your APIs.

The Oxford Dictionaries API is doing this with their latest additions to their stack of word related APIs, by providing early access for their community with two of their new API prototypes that are currently in development:

  • The Oxford English Dictionary (OED) is the definitive authority on the English language containing the meaning, history, and pronunciation of more than 280,000 entries – past and present – from across the English-speaking world. Its historical record of the English language is traced through more than 3.5 million quotations ranging from classic literature and specialist periodicals to film scripts and cookery books.
  • bab.la offers quick and easy translations and answers to everyday language questions. As part of the Oxford Dictionaries family, it provides practical support to people using a language that is not their mother tongue.

To get access to the new prototypes, all you have to do is fill out a short questionnaire, and they will consider giving you access to the prototype APIs. It is interesting to review the questions they ask developers, which help qualify users but also asks some questions that could potentially impact the design of the API. The Oxford Dictionaries API team is smart to solicit some external feedback from developers before getting too far down the road developing your API and making it available in any production environment.

I do not think all companies, organizations, and government agencies have it in their DNA to design APIs in this way. There are also some concerns when you are doing this in highly competitive environments, but there are also some competitive advantages in doing this regularly, and developing a strong R&D group within your API ecosystem--even if your competitors get a look at things. I'm going to be flagging API providers who approach API development in this way and start developing a list of best practices to consider when it comes to including your API community in the design and development process, and leveraging their feedback loop in this way.

Taking A Look At The Stoplight API Spec Editor

I'm keeping an eye on the different approaches by API service providers when it comes to providing API editors within their services and tooling. While I wish there was an open source GUI API editor out there, the closest thing we have is from these API service providers, and I am trying to track on what the best practices are so that when someone does step up and begin working on an open, embeddable solution, they can learn from my stories about what is working or not working across the space.

One example I think has characteristics that should be emulated is the API Spec Editor from Stoplight. The GUI editor lets you manage all the core elements of an OpenAPI like the general info, host, paths, and even the shared responses and parameters. They even provide what they call a CRUD builder where you paste the JSON schema, and they'll generate the common paths you will need to create, read, update, and delete your resources. Along the way you can also make calls to API endpoints using their interactive interface, helping ensure your API definition is actually in alignment with your API.

The Stoplight API Spec Editor bridges the process of defining your OpenAPI for your operations, with actually documenting and engaging with an API through an interactive client interface. I like this approach to coming at API design from multiple directions. Apiary first taught us that API definitions were about more than just documentation, and I think our API editors should keeping evolving on this concept, and allowing us to engage with any stops along the API life cycle like we are seeing from API service providers like Restlet.

I'm already keeping an eye on Restlet and APIMATIC's approach to providing a GUI API design editor within their solutions and will keep an eye out on other providers as I have time. Like other areas of the API sector, I'm hoping I can develop a list of best practices that any service provider can follow when developing their tools and services.

REST, Linked Data, Hypermedia, GraphQL, and gRPC

I'm endlessly fascinated by APIs and enjoy studying their evolution. One of the challenges in helping evangelize APIs that I come across regularly is the many different views of what is or isn't an API amongst people who are API literate, as well as helping bring APIs into focus for the API newcomers because there are so many possibilities. Out of the two, I'd say that dealing with API dogma is by far a bigger challenge, than explaining APIs to newbies--dogma can be very poisonous to productive conversations and end up working against everyone involved in my opinion. 

I'm enjoying reading about the evolution in the API space when it comes to GraphQL and gRPC. There are a number of very interesting implementations, services, tooling, and implementations emerging in both these areas. However, I do see similar mistakes being made regarding dogmatic behavior, aggressive marketing tactics, and shaming folks for doing things differently, as I've seen with REST, Hypermedia, and linked data efforts. I know folks are passionate about what they are doing, and truly believe their way is right, but I'm concerned you will all suffer from the same deficiencies in adoption I've seen with previous implementations.

I started API Evangelist with the mission of counteracting the aggressive approach of the RESTafarians. I've spent a great deal of time thinking about how I can turn average developers and even business folks on to the concept of APIs--no not just REST or just hypermedia, but web APIs in general. Something that I now feel includes GraphQL and gRPC. I've seen many hardworking folks invest a lot into their APIs, only to have them torn apart by API techbros (TM) who think they've done it wrong--not giving a rats ass regarding the need to actually help someone understand the pros and cons of each approach.

I'm confident that GraphQL will find its place in the API toolbox, and enjoy significant adoption when it comes to data-intensive API implementations. However, I'd say 75% of the posts I read are pitting GraphQL against REST, stating it is a better solution. Period. No mention of its limitations or use cases where it might not be a good idea. Leaving us to only find out about these from the GraphQL haters--playing out the exact same production we've seen over the last five years with REST v Hypermedia. Hypermedia is finding its place in some very useful API implementations like FoxyCart, and AWS API Gateway (to name just a few), but its growth has definitely suffered from this type of storytelling, and I fear that GraphQL will face a similar fate. 

This problem is not a technical challenge. It is a storytelling and communication challenge, bundled with some very narrow incentive models fueled by a male-dominated startup culture, where folks really, really like being right and making others feel bad for not being right. Stop it. You aren't helping your cause. Even if you do get all your techbros thinking like you do, your tactics will fail in the mainstream business world, and you will only give more ammo to your haters, and further confuse your would be consumers, adopters, and practitioners. You will have a lot more success if you are empathetic towards your readers, and produce content that educates, and empowers, over shames and tearing down.

I'm writing this because I want my readers to understand the benefits of GraphQL, and I don't want gRPC evangelists to make the same mistake. It has taken waaaay too long for linked data efforts to recover, and before you say it isn't a thing, it has made a significant comeback in SEO circles, because of Google's adoption of JSON-LD, and a handful of SEO evangelists spreading the gospel in a friendly and accessible way--not because of linked data people (they tend to be dicks in my experience). As I've said before, we should be investing in a robust API toolbox, and we should be helping people understand that benefits of different approaches, and learn about the successful implementations. Please learn from others mistakes in the sector, and help see meaningful growth across all viable approaches to doing API--thanks.

A Looser More Evolvable API Contract With Hypermedia

I wrote about how gRPC API implements deliver a tighter API contract, but I wanted to also explore more thought from that same conversation, about how hypermedia APIs can help deliver a more evolvable API contract. The conversation where these thoughts were born was focused on the differences between REST and gRPC, in which hypermedia and GraphQL also came up. Leaving me thinking about how our API design and deployment decisions can impact the API contract we are putting forth to our consumers.

In contrast to gRPC, going with a hypermedia design for your API, your client relationship can change and evolve, providing an environment for things to flex and change. Some APIs, especially internal API, and trusted partners might be better suited for gRPC performance, but when you need to manage volatility and change across a distributed client base, hypermedia might be a better approach. I'm not advocating one over the other, I am just trying to understand the different types of API contracts brought to the table with each approach, so I can better articulate in my storytelling.

I'd say that hypermedia and gRPC approaches give API providers a different type of control over API clients that are consuming resources. gRPC enables dictating a high performance tighter coupling by generating clients, and hypermedia allows for shifts in what resources are available, what schema are being applied, and changes that might occur with each version, potentially without changes to the client. The API contract can evolve (within logical boundaries), without autogeneration of clients, and interference at this level.

As I learn about this stuff and consider the API contract implications, I feel like hypermedia helps API provides navigation change, evolve and shift to deliver resources to a more unknown, and distributed client base. gRPC seems like it provides a better contract for use in your known, trusted, and higher performance environments. Next, I will be diving into what API discovery looks like in a gRPC world, and coming back to this comparison with hypermedia, and delivering a contract. I am feeling like API discovery is another area that hypermedia will make sense, further helping API providers and API consumers conduct business in a fast changing environment.

A Tighter API Contract With gRPC

I was learning more about gRPC from the Google team last week, while at the Google Community Summit, as well as the API Craft SF Meetup. I'm still learning about gRPC, and how it contributes to the API conversation, so I am trying to share what I learn as I go, keeping a record for others to learn from along the way. One thing I wanted to better understand was something I kept hearing regarding gRPC delivering more of a tighter API contract between API provider and consumer.

In contrast to more RESTful APIs, a gRPC client has to be generated by the provider. First, you define a service in a .proto file (aka Protocol Buffer), then you generate client code using the protocol buffer compiler. Where client SDKs are up for debate in the world of RESTful APIs, and client generation might even be frowned upon in some circles, when it comes to gRPC APIs, client generation is a requirement--dictating a much tighter coupling and contract, between API provider and consumer. 

I do not have the first-hand experience with this process yet, I am just learning from my discussions last week, and trying to understand how gRPC is different from the way we've been doing APIs using a RESTful approach. So far it seems like you might want to consider gRPC if you are looking for significant levels of performance from your APIs, in situations where you have a tighter relationship with your consumers, such as internal, or partner scenarios. gRPC requires a tighter API contract between provider and consumer, something that might not always be possible, depending on the situation. 

While I'm still getting up to speed, it seems to me that the .proto file, or the protocol buffer definition acts as the language for this API contract. Similar to how OpenAPI is quickly becoming a contract for more RESTful APIs, although it is often times much looser contract. I'll keep investing time into learning about gRP, but. I wanted to make sure and process what I've learned leading up to, and while at Google this last week. I'm not convinced yet that gRPC is the future of APIs, but I am getting more convinced that it is another important tool in our API toolbox.

Focus On Having A Robust And Diverse API Toolbox

I'm learning a lot about HTTP/2 and gRPC this week, so I have been thinking about how we isolate ourselves by focusing in on individual toolsets, where we should really be expanding our horizons, helping ensure we have the most robust and diverse API toolbox we possibly can. Depending on what part of the tech universe an engineer comes from they'll have a different view on just exactly what I mean when I say API to them.

The most common perspective that people respond with is REST. Folks automatically think this is what I mean when I say API--it isn't. That is your dogma or your gullibility to other people's dogma--please expand your horizons. When I say APIs, I mean an application programming interface that leverages web technology (aka HTTP, HTTP/2). Sure REST is the dominating philosophy in this discussion, but I see no benefit in limiting ourselves in this fashion--I see API as a toolbox, with the following toolsets:

  • REST - Considering Roy Fielding's guidance when it comes to leveraging HTTP in my API design.
  • Hypermedia - Considering the web, and the role that links can play in your API design.
  • Webhooks - Helping keep APIs a two-way street, expanding your API to respond to events not just single requests.
  • GraphQL - Helping put powerful query tooling in the hands of API consumers when working with large and complex datasets.
  • gRPC - Acknowledging that the HTTP protocol is evolving, and our API contract can evolve along with the specification.

This represents the major toolsets that are currently in my API toolbox. Sure there are a number of other individual tools and specifications in there as well, but this represents the top tier toolsets I am looking at when it comes to getting things done. In my opinion, there is a time and place for each of these toolsets to be put to use. I can easily geek out on any of these areas, but because I'm not selling you a product or service, I'm more interested in finding the right tool for the situation.

I do not expect that all providers have this robust of API toolbox from day one--it is something that will come with time. My recommendation is everyone begins with REST, developing proficiency in this domain, while you are also learning about hypermedia webhooks. As your understanding evolves, then you should start looking at GraphQL, gRPC, and other more advanced approaches to round off your skills. Do not let your religious technological beliefs or any single vendor motivations limit the scope of your API toolbox, you should be working to make it as robust and diverse as you possibly can.

I Am Learning About gRPC APIs From Google

I have been processing Google's API design guide, and an unexpected part of the work has been learning more about gRPC, which Google is "converging designs of socket-based RPC APIs with HTTP-based REST APIs." -- something I have not seen in an API design guide until now. "gRPC uses protocol buffers as the Interface Definition Language (IDL) for describing both the service interface and the structure of the payload messages", and is something I'm hearing more chatter about from larger providers, which I think represents the evolving world of API design beyond the old REST days.

According to the site, "gRPC is used in last mile of computing in mobile and web client since it can generate libraries for iOS and Android and uses standards based HTTP/2 as transport allowing it to easily traverse proxies and firewalls. There is also work underway to develop a JS library for use in browsers. Beyond that, it is ideal as a microservices interconnect, not just because the core protocol is very efficient but also because the framework has pluggable authentication, load balancing etc. Google itself is also transitioning to use it to connect microservices."

To help me learn anything I need an example to reverse engineer, showing me how things work--so here are the examples they provide from the site:

I'm going to add a research area for gRPC, similar to hypermedia, as well as GraphQL. It helps me better keep track of the news about each approach to crafting APIs, and a single place I can go to reference service providers, and working examples. I've had gRPC / Protocol Buffers on my monitoring list for some time now, but seeing Google invest so heavily in this area gives me a signal that I should be paying attention to gRPC more, and gathering more examples that I can share with my readers.

I'm thinking that I will assemble some sort of toolbox area in my API design research, helping folks understand when a more RESTful approach makes sense, as well as when hypermedia, GraphQL, or maybe a gRPC approach might be more appropriate. Next, I'm going to dive into BigTable, PubSub, and Speech APIs to see gRPC in action--something I'm hoping that will help me better understand Google's approach to API design, which something I'm struggling with grasping completely.

Please Develop An Embeddable Open Source Visual API Editor

This is a repeat story of one I wrote two years ago, but things haven't changed so I'm going to rant about again, 2017 style. We need someone to develop an open source, visual API design editor. There is the Swagger Editor, but that is more a web IDE, and I'm looking for a well designed, intuitive, visual editor for managing your OpenAPI definitions, that is embeddable and easily integrated into any web or mobile system.

There are examples of nice visual API design editors with some of the leading API service providers, but I'm looking for something any API service provider could put to work. I included these examples in my last story, except I'm including Stoplight this round instead of Gelato, because they gave me an upgrade my account message, and wouldn't let me see the interface. These are currently my favorite three API design editors:

  • Restlet - A design, deployment, management service provider.
  • APIMATIC  - An SDK, API definition transformer, and continous integration provider.
  • Stoplight - An API design, definition, documentation, and orchestration provider.

I enjoy using all three of their API design interfaces. They are well thought out and provide what you need to design new APIs, as well manage the design of your existing APIs. While they are doing a good job at this, it is something I'd like to see standardized, and open sourced, so that other service providers do not have to reinvent the wheel here. We shouldn't have to use a different API design interface for each service we depend on, we need a common editor, making things more familiar. 

Ok, rant over. This is something I'll keep talking about until there is a solution. Oh, I have to say, I am impressed with what the Materia team has done for API design on the desktop. Between them and Stoplight, there has been positive motion forward. I'm just looking to give things another nudge and help folks understand the opportunity. I'll explore possible business models for such a solution in another post, and keep beating this drum until I get what I want.

Do You have An API Design Guide For Your Operations?

Everyone developing APIs struggles with API design. Ok, maybe a few of the gurus out there don't, but the rest of us need education, practice, and ideally someone or something to help guide us through the best practices when it comes to API design. I try to track what different companies are doing when it comes to API design, and maintain a list of any API design guides I come across in my work.

If you are looking to start getting a grasp on API design at your company, organization, institution or agency, I recommend starting on the journey to define your own API design guide--you will be surprised what you can learn along the way. You can kick things off by visiting my API design research, but I strongly recommend you head over to the API Stylebook, and build on this important work.

My friend Arnaud has aggregated 12 of the leading API design guides out there and is currently processing Google's API design guide, adding more knowledge to the repository. He takes each API design guide and breaks them down into common API design topics that you can consider as part of your own process, and resulting guide. His work is all machine readable and forkable so that you can easily assemble your own guide, and get to work learning, defining, and refining--then you can submit your guide to the API Stylebook when you are ready.

API design and API definitions are the top two most trafficked areas of my website in 2017, and most of 2016. API design is top of mind for API providers who are further along in their journey, and the ones who are seriously rocking it usually have some sort of guide, helping keep things consistent. If you need any help, feel free to reach out. I am not an API design expert, but I know my way around the finer details, and concepts at play, and I'm happy to help where I can. I know Arnaud is happy to answer questions as well, and if nothing else, let me help tell the story of your API design journey so that others can learn from it.

The Web Evolved Under Different Environment Than Web APIs Are

I get the argument from hypermedia and linked data practitioners that we need to model our web API behavior on the web. It makes sense, and I agree that we need to be baking hypermedia into our API design practices. What I have trouble with is the fact that the web is a cornerstone that we should be modeling it after. I do not know what web y'all use every day, but the one I use, and harvest regularly is quite often is a pretty broken thing.

It just feels like we overlooking so much to support this one story. I'm not saying that hypermedia principles don't apply because the web is shit, I'm just saying maybe it isn't as convincing of an anchor to build a story that currently web APIs are shit. I understand that you want to sell your case, and trust me...I want you to sell your case, but using this argument just does not pencil out for me.

There is another aspect of this that I find difficult. That the web was developed and took root in a very different environment than web APIs are. We had more time and space to be more thoughtful about the web, and I do not think we have that luxury with web APIs. The stakes are higher, the competition is greater, and the incentives for doing it thoughtfully really do not exist in the startup environment that has taken hold. We can't be condemning API designers and architects for serving their current master (or can we?). 

While I will keep using core web concepts and specs to help guide my views on designing, defining, and deploying my web APIs, I'm going to explore other ways to articulate why we should be putting them to use. I'm going to also be considering the success or failure of these elements based on the shortcomings of the web, and web APIs, while I work to better polish the existing stories we tell, as well as hopefully evolve new ones that help folks understand what the best practices for web APIs are.

Considering A Web API Ecosystem Through Feature-Based Reuse

I recently carved out some time to read A Web API ecosystem through feature-based reuse by Ruben Verborgh (@RubenVerborgh) and Michel Dumontier. It is a lengthy, very academic proposal on how we can address the fact that "the current Web API landscape does not scale well: every API requires its own hardcoded clients in an unusually short-lived, tightly coupled relationship of highly subjective quality."

I highly recommend reading their proposal, as there are a lot of very useful patterns and suggestions in there that you can put to use in your operations. The paper centers around the notion that the web has succeeded because we were able to better consider interface reuse, and were able to identify the most effective patterns using analytics, and pointing out that there really is no equivalent to web analytics for measuring an APIs effectiveness. 

In order to evolve Web API design from an art into a discipline with measurable outcomes, we propose an ecosystem of reusable interaction patterns similar to those on the human Web, and a task-driven method of measuring those.

To help address these challenges in the world of web APIs, Verborgh and Dumontier propose that we work to build web interfaces, similar to what we do with the web, employing a bottom-up to composing reusable features such as full-text search, auto-complete, file uploads, etc.--in order to unlock the benefits of bottom-up interfaces, they propose 5 interface design principles:

  1. Web APIs consist of features that implement a common interface
  2. Web APIs partition their interface to maximize feature reuse.
  3. Web API responses advertise the presence of each relevant feature
  4. Each feature describes its own invocation and functionality.
  5. The impact a feature on a Web API should be measured across implementations.

They provide us with a pretty well thought out vision involving implementations and frameworks, and the sharing of documentation, while universally applying metrics for being able to identify the successful patterns. It provides us with a compelling, "feature-based method to construct the interface of Web APIs, favoring reuse overreinvention, analogous to component-driven interaction design on the human Web."

I support everything they propose. I cannot provide any critique on the technical merits of their vision. However, I find it lacks an awareness of the current business and political landscape that I find regularly present in the hypermedia, and linked data material I consume.

Here are a few of the business and political considerations that contribute to the situation we find ourselves in that Verborgh and Dumontier are focused on, which will also work to slow the adoption of their proposed vision:

  • Venture Capital - The current venture capital driven climate does not incentivize sharing and reuse, and their startups investing time and energy into web technologies.
  • Intellectual Property - Modern views of the intellectual property, partially fueled by VC investment, but further exacerbated by legal cases like Oracle v Google force developers and designers to hold patterns close to their chest, limiting sharing and reuse again.
  • Lazy Developers - Not all developers are knowledge seekers like the authors of this paper, and myself, many are just looking to get the job done and get home. There are few rewards for contributing back to the community, and once I have mine, I'm done.
  • The Web Is Shit - One area that linked data and hypermedia folks tend to lose me is their focus on modeling things after the web. I agree the web is "working", but I don't know which one you use, but the one I use is shit, and only getting worse--have you scraped web content lately?
  • Metrics & Analytics - Google Analytics started out providing us with a set of tools to measure what works and doesn't work when it comes to the parts and pieces of our websites, but now it just does that for advertising. Also we do have analytics in the API space, but due to the other areas cited above, there is no sharing of this wisdom across the space.

These are just a handful of areas I regularly see working against the API design, definition, and hypermedia areas of the space, and will flood in slow the progress of their web API ecosystem vision. It doesn't mean I'm not supportive. I see the essence of a number of positive things present in their proposal, like reuse, sharing, and measurement. I feel the essence of existing currents in the world of APIs like microservices, DevOps, and continuous integration (aka orchestration).

My mission, as it has been since 2010, is make sure really smart folks like Ruben and Michel at institutions, startups, and the enterprise better understand the business and political currents that are flowing around them. It can be very easy to miss significant signals around the currents influencing what is working, or not working with APIs when you are heads down working on a product, or razor focused on getting your degree within an institution. The human aspects of this conversation are always well cited, but I'm thinking we aren't always honest about the human elements present on the API side of the equation. Web != API & API !=Web.

Making Data Serve Humans Through API Design

APIs can help make technology better serve us humans when you execute them thoughtfully. This is one of the main reasons I kicked off API Evangelist in 2010. I know that many of my technologist friends like to dismiss me in this area, but this is more about their refusal to give up the power they possess than it is ever about APIs.

I have been working professionally with databases since the 1980s, and have seen the many ways in which data and power go together, and how technology is used as smoke and mirrors as opposed to serving human beings. One of the ways people keep data for themselves is to make it seem big, complicated, and only something a specific group of people (white men with beards (wizards)) can possibly make work.

There is a great excerpt from a story by Sara M. Watson (@smwat), called Data is the New “___” that sums up this for me:

The dominant industrial metaphors for data do not privilege the position of the individual. Instead, they take power away from the person to which the data refers and give it to those who have the tools to analyze and interpret data. Data then becomes obscured, specialized, and distanced.

We need a new framing of a personal, embodied relationship to data. Embodied metaphors have the potential to bring big data back down to a human scale and ground data in lived experience, which in turn, will help to advance the public’s investment, interpretation, and understanding of our relationship to our data.

DATA IS A MIRROR portrays data as something to reflect on and as a technology for seeing ourselves as others see us. But, like mirrors, data can be distorted, and can drive dysmorphic thought.

This is API for me. The desire to invest, interpret, and understand our relationship to our data is API design. This is why I believe in the potential of APIs, even if the reality of it all often leaves me underwhelmed. There is no reason that the databases have to be obscured, specialized, and distant. If we want to craft meaningful interfaces for our data we can. If we want to craft useful interfaces for our data, that anyone can understand and put to work without specialized skills--we can.

The problem in this process is often complicated through our legacy practices, the quest for profits, or there are vendor-driven objectives in the way of properly defining and opening up frictionless access to our data. Our relationships with our data are out of alignment because it is serving business and technological masters, and do not actually benefit the humans whom it should be serving.

APIs Can Give An Honest View Of What A Company Does

One of the reasons I enjoy profiling APIs is that they give an honest view of what a company does, absent of all the marketing fluff, and the promises that I see from each wave of startups. If designed right, APIs can provide a very functional, distilled down representation of data, content, and algorithmic resources of any company. Some APIs can be very fluffy and verbose, but the good ones are simple, concise, and straight to the point.

As I'm profiling the APIs for the companies included in my API monitoring research, what API Science, Apica, API Metrics, BMC Software, DataDog, New Relic, and Runscope offer quickly become pretty clear. A simple list of valuable resources you can put to use when monitoring your APIs. Crafting an OpenAPI Spec allows me to define each of these companies APIs, and easily articulate what it is that they do--minus all the bullshit that often comes with the businesses side of all of this. 

I feel like the detail I include for each company in an APIs.json file provides a nice view of the intent behind an API, while the details I put into the OpenAPI Spec provide insight into whether or not a company actually has any value behind this intent. It can be frustrating to wade through the amount of information some providers feel they need to publish as API documentation, but it all becomes worth it once I have the distilled down OpenAPI Spec, giving an honest view of what each company does.

The New API Design And Deployment Solution Materia Is Pretty Slick

I was playing with a new API design and deployment solution, from some of my favorite developers out there this weekend called Materia, which bills itself as "a modern development environment to build advanced mobile and web applications"--I would add, "with an API heart".

Materia is slick. it is modern. While very simple, it is also very complete--allowing you to define your underlying data model or entities, design and deploy APIs, and then publish a single page applications (SPA) for use on the web, or mobile devices. Even though I'm one of those back to land, hand-crafted API folks, I could see myself using Materia to quickly design and deploy APIs. 

I say this in the most positive light imaginable, but Materia reminds me of the Microsoft Access for APIs. Partly its the diagramming interface for the entities, but it is also the fact that it bridges the backend to the frontend, allowing you to not just design and deploy the database and APIs, but also the resulting user interface that will put them to work.

I know they are just getting going with developing Materia, but I can't help but share a couple things I'd like to see, that would make it continue to be the modern API driven application it is striving to be:

  • OpenAPI Specs or Blueprints - Allow users to import, export, and manage my APIs in the popular API definition format my choice.
  • Schema.org - Provide users with a wealth of existing entity models to choose from, so they do not reinvent the wheel.
  • Github - Allow for the publishing of projects, and importing of them to and from Github, allowing for the sharing of server design and deployment patterns.

There are a number of other things I'd like to see, but I'm sensitive to the fact that they are just getting started. These three areas would significantly widen the initial audience for Materia beyond the developer class, which is who the application solution should be targeting. Like I said, it has the potential to be the Microsoft Access of APIs for small businesses, which isn't quite the Microsoft Excel of APIs, but a close second. ;-)

Nice work guys! It is the another positive advancement in the world of API design alongside Restlet launched their API design studio, and Apiary setting this modern era of API design into motion with Apiary. I'll be tuning into Materia's evolution on Twitter, and play more with the server and designer editions available on Github.

API Stylebook: A Collections Of Resources For API Designers

My friend Arnaud Lauret (@arno_di_loreto), the API Handyman, has released a very cool new project called the API Stylebook--a collections of resources for API designers. It is a brilliant aggregation of twelve API design guides from Atlassian, Cisco, Cloud Foundry, Haufe, Heroku, Microsoft, PayPal, Red Hat, The White House, Zalando.

I think the API Stylebook purpose describes it well:

The API Stylebook aims to help API Designers to solve API design matters and build their API design guidelines by providing quick and easy access to selected and categorized resources.

In this first version, the API Stylebook provides direct links to specific topics within publicly available API Design Guidelines. Instead of reinventing the wheel or searching google for hours, API Designers quickly can find solutions and inspiration from these existing guidelines.

The API Stylebook isn't just a list of API design guidelines from these companies, it is a machine readable distillation of the twelve API design guides into a master list of API design topics you can consider when crafting your own API design guide. It is slick. I like Arnaud's approach to analyzing the existing API design patterns across API platforms who have shared their guides. I also really like the approach to breaking things down as YAML, and publish as a very good looking website using Github, and Github Pages.

I'm hoping it is something that will stimulate other API providers to craft and share their own API design guide. If you do, I'm sure Arnaud would add to his work, especially if you use his work as a blueprint for your design guide--keeping things as standardized as possible. Projects like this are critical to the growth of the space, and a lack of resources like API Stylebook, and Webconcepts.info have seriously slowed the consistency and interoperability across the world of APIs.

The API Evangelist API Design Guide

In the last couple of years, I've seen the concept of API design go from being something the API elite discuss, to something that involves business users, and something that has spawned a whole ecosystem of service and tooling providers. 

This API design research covers the concepts people often associate with API design, like REST, and Hypermedia, but also touches on other media types, API definitions, and many of the services, tooling and other solutions that have emerged to serve the space.

I fund my research through consulting, selling my guides, and the generous support of my sponsors. I appreciate your support in helping me continue with my work and hope you find it relevant in your API journey.  

Purchase My API Definitions Guide

Using My APIs.json Annotation Tool To Drive An API Design Conversation Via Github Issues

I am working on one possible API definition for the Human Services Definition Specification (HSDS), and the next phase of this work involves bringing in a small group of technical, and non-technical folks to have discussions around their API designs, in context of the master specification I am looking to pull together. 

To help drive the discussion I am wanted to use the OpenAPI Specification that I created for HSDS, and I also knew I wanted to use Github issue management to help keep track of the synchronous, and asynchronous conversation that would occur around it. However Github tends to have a perceived barrier to entry for many non-developers (which I don't fully get), so I wanted to leverage the platform, but also soften the way everyone discussed the overall specification, as well as each individual endpoint.

The HSDS specification is pretty verbose, and I needed a way to have conversations at the high level, but also down to the endpoint level. To help facilitate this, I got to work on a prototype micro tool which enables a conversation around any API(s) that are indexed within an APIs.json file, producing a human readable list of endpoints, parameters, etc., but then uses Github issue management as the core of the conversation. 

Resulting in my APIs.json Annotation tool. It is just a first draft, so there will be a lot of changes that need to occur. I'm going to test it against 20+ APIs.json collections I have defined as part of my API Stack work to try and harden it a little bit. My APIs.json Annotation tool runs in my single repo app style, leveraging Jekyll + Github Pages + Github API to operate--Github is the front and backend.

Anyone can view the conversation, but if you want to participate you have to be added to the Github repository, and pass in a Github personal token. This is something I often automate with a simple Github login, where I use OAuth.io to obtain token, but I kind of see the token as a minimum viable investment to understanding Github for using each tool.

It is really important to me that each app stands on its own feet. Not all of my micro tools that I develop in this way will enjoy zero outside dependencies, but most of them can be easily forked, and ran in any Github user account or org (with little or no setup). Conversations around API is just one area I am looking to simulate with this approach to delivering tooling, and specifically APIs.json tooling, that can be used throughout an API life cycle. 

You are welcome to play with the APIs.json Annotation, or any of the other tools I have listed on my home page. I will keep adding them here, so that they can be found, but like all my work they are all a work in progress. Each tool has its own dedicated repo and issue management, where you are welcome to join in the conversation around the road map for each one. I am just looking to develop a robust toolbox of small micro tools that will help be more successful across the life cycle of the APIs I am working on, but maybe you can benefit using them too.

Staying True To My API Core And Seeing Bots As Just One More Design Constraint

Over the last five years many of us have been pushing forward our API design skills to deliver valuable resources to mobile apps. The multi channel opportunity for delivering data, content, and other resources to not just websites, and web applications, but also to iPhone, Android, Windows, and other mobile platform is clear. Alongside delivering web apps to multiple browsers (IE, Chrome, and Firefox), we had to learn to deliver to an increasingly diverse mobile ecosystem (iOS, Android, Windows).

When you have an API core, crafting new endpoints that speak to new channels is not as daunting of a task. I'm thinking through how to deliver API Evangelist knowledge into a Slack channel, Facebook Messenger discussions, and via Alex Voice for use at our APIStrat Conference in Boston this fall. Whether I am creating bots, or delivering new skills to voice enablement, I'm just adding new design constraints to my already existing stack of things I consider when I'm crafting my API stack(s).

I can't help but be in tune with the frenzy around bots, and the interesting things AWS is doing within the Alexa ecosystem. I do not feel like it is a distraction from my core business, as I'm just applying some new design constraints to what I am already doing. I'm not chasing entirely new things, I'm just responding, and participating in what the latest shifts in what technology are.

I don't feel like any of the 50 areas of the API space that I'm keeping an eye on are distractions, as long as I stay true to my API core, and they help me critically think through, and apply new design constraints to the core business value I am already bringing to the table.

My API Life Cycle Research From Design To Deprecation

It always makes me smile, when I talk to someone about one or many areas of my API research, sharing how I conduct my work, and they are surprised to find how many areas I track on. My home page has always been a doorway to my research, and I try to keep this front door as open as possible, providing easy access to my more mature areas like API management, all the way to my newer areas like how bots are using APIs.

From time to time, I like to publish my API life cycle research to an individual blog post, which I guess puts my home page, the doorway to my research into my readers Twitter stream, and feed reader. Here is a list of my current research for April 2016, from design to deprecation.

Design {"View Research"}
Hypermedia {"View Research"}
Definitions {"View Research"}
Domain Name System (DNS) {"View Research"}
Deployment {"View Research"}
Virtualization {"View Research"}
Containers {"View Research"}
Serverless {"View Research"}
Management {"View Research"}
Getting started {"View Research"}
Documentation {"View Research"}
Frequently Asked Questions {"View Research"}
Support {"View Research"}
Roadmap {"View Research"}
Issues {"View Research"}
Change Log {"View Research"}
Monitoring {"View Research"}
Testing {"View Research"}
Performance {"View Research"}
Authentication {"View Research"}
Encryption {"View Research"}
Security {"View Research"}
Terms of Services (TOS) {"View Research"}
Privacy {"View Research"}
Licensing {"View Research"}
Branding {"View Research"}
Regulation {"View Research"}
Patents {"View Research"}
Discovery {"View Research"}
Client {"View Research"}
Command Line Interface (CLI) {"View Research"}
Bots {"View Research"}
Integrated Development Environment (IDE) {"View Research"}
Software Development Kit (SDK) {"View Research"}
Embeddable {"View Research"}
Visualization {"View Research"}
Webhooks {"View Research"}
Logging {"View Research"}
Aggregation {"View Research"}
Scraping {"View Research"}
Reciprocity {"View Research"}
Orchestration {"View Research"}
Real-Time {"View Research"}
Voice {"View Research"}
Spreadsheets {"View Research"}
Monetization {"View Research"}
Plans {"View Research"}
Partners {"View Research"}
Evangelism {"View Research"}
Deprecation {"View Research"}

I am constantly working to improve my research, organizing more of the organizations who are doing interesting things, the tooling that is being deployed, and relevant news from across the area. I use all this research, to fuel my analysis, and drive my lists of common building blocks, which I include in my guides, blueprints, and other white papers and tutorials that I produce.

I am currently reworking all the PDF guides for each research area, updating the content, as well as the layout to use my newer minimalist guide format. As each one comes off the assembly line, I will add to its respective research area, and publish an icon + link on the home page of API Evangelist--so check back regularly. If there is any specific area you'd like to see get more attention, always let me know, and I'll see what I can do.

Thinking Through The Design Of Your Pricing API Would Help You Think Through Your API Plan

As I made my way through nine of the leading SMS providers, profiling the details of their API plans, trying to bring it all together into a single, machine readable definition, Messente's pricing API stood out for me. Alongside their SMS API, and their number lookup API, they have a pricing API. As I take a moment to look at the simplicity of the endpoint, I am also thinking about the potential, and the details of their API docs really stand out for me.

In addition to a pricing API being a valuable utility for any API consumer, I can't help but think the process of constructing a pricing API would force API providers to think another layer deeper in their API plan(s). Similar to how you have to think through the details of any resource you make available via an API, considering how it will be put to use, crafting a pricing API would force you to do the same for one of the most valuable, and overlooked resources you offer, that is core to all of your API operations.

I've talked about the importance of API providers having management level APIs before, and I think they should also follow the lead of API providers like Messente who exist in a pretty mature sector, and have a handle on their API pricing. I've said it before, and will keeping harping on this issue...that all API providers and their service providers should have pricing APIs, as well as APIs for the other essential building blocks of their API operations.

Another thing to note here, that I will be writing about more in the future, is the presence of two-letter country code as a parameter for an API. While not all APIs will have country specific pricing like SMS providers do, the API providers who are looking to truly operate globally, you will need to continue the automation of your operations, making pricing available on demand, in any currency that consumers will need.

There Is A Big Opportunity Right Now When It Comes To API Design Tooling

API design and definitions are the number one area when it comes to talks submitted for APIStrat 2015 in Austin, and when it comes to traffic across the API Evangelist network in 2015. After diving into the Amazon API Gateway a little more over the weekend, I was reminded of the opportunity out there when it comes to API design tooling.

Amazon did a good job, providing a GUI interface for crafting the methods, resources, and underlying data models for APIs you are deploying using the gateway. However when you compare to some of the GUI API design editors I mentioned in my last post on this subject, from Restlet, APIMATIC, and Gelato, the Amazon interface clearly needs evolve a little more.

AWS is just getting started with their solution, so I'm not knocking what they have done. I just wanted to keep comparing of all of the solutions as they emerge, and highlight the opportunity for some standardization in this layer of API tooling. I see a pretty big opportunity for some player to step up and provide an open source API design editor that provides a seamless experience across API service providers. 

This post is nothing new. I am just trumpeting the call for open API design tooling each time I see another new interface introduced for crafting APIs, their paths, resources, parameters, headers, authentication, and underlying data models. At some point, a new player will emerge with the open source API design editor I am looking for, or one of the existing players open sources their current offering, and evolve it in context of the wider API design space, providing an abstracted layer that supports all API definition formats.

With the growth in the number of service providers I see stepping up to server the API space, the need for common, open tooling when it comes to API design is only going to grow. It took almost four years of waiting for the API management space to figure this out, I'm hoping I don't have to wait as long in the API design side of things.

Cultivating the Next Generation of API Design Skills

There was a pretty interesting conversation around API design going on in one of my API slack channels over the last couple days, about what is API design, and what is needed to get developers, and even non-developers more aware of the best practices that exist. It is a private group, so I won't broadcast it as part of this post, but I did want to extract a narrative from it, and help me set a bar for other API design discussions I am having. 

The Restafarian, hypermedia, and linked data folk have long been frustrated by the adoption of sensible API design practices across the sector, and the lack of basic HTTP literacy among developers, and non-developers is at dangerously high levels. The good news, is some of this is beginning to change, but we still have so much work to do, something that won't be easy, and unfortunately it won't always have the clean outcomes leaders in the space are looking for.

APIs returning JSON is just the next step in the evolution of the web, and when you consider how much work it took to get everyone on-board with HTML, and building web pages, then web apps, and recently mobile apps, you can begin to understand the work that still lies ahead. We have to help the next generation of developers be more HTTP literate (something the previous generations of developers aren't), and possess a baseline knowledge of common API design best practices. This needs to be done in a world where many of these developers really aren't going to care about the specifics of good API design, like us API architects and early pioneers have.

The average API designer in the future will not always be willing to argue about the nuance of how to craft URLs, whether to use a header or parameter, caching, and how to version. They just want to get the outcome they seek, accomplish their project, and get paid for their work. Consider the solar industry as a quick comparison. The first wave of installers were domain experts, while the following waves of installers who will be focused on scaling and maintaining the industry, will only need to be trained on only what is required to get the job done in a stable, profitable way.

Ok. So how do we do this right? I feel like we are already on the good path. We just need you to publish your own API design guide somewhere that we can all learn from, like other leading API providers already present in my API design research. As we build a critical mass of these, we need to also work to aggregate the best practices across them, so that instructors and textbook publishers can incorporate into their curriculum. If you have an API platform, and have ever wished that there were more highly skilled API designers out there, make sure you have your API design practices documented, and shared with the world.

This will get healthy API design practices out of the trenches of startups, SMBs, enterprise, and government agencies, and get it into the educational institutions around the world. Then we can start equipping the next generation of programmers with the knowledge they will need to be successful in delivering the resources need for the next generation of Internet powered apps, networks, and devices. 

I want to add on emore thing. API service companies who are looking to provide tooling that API providers can use to do deploy APIs, will have share in the load here. This is core to my criticism of the AWS API Gateway, in that I applaud their use HAL, but please make sure you also provide a healthy dose of hypermedia literacy along the way, don't just hide it behind the curtain. I really do not want to see the another FrontPage for APIs, so if you are building an API editor, let me know so I can provide you with some ideas. (1) (2).

We all have a lot of work to do, in preparing the next generation of developers, and business users when it comes to a baseline of HTTP literacy, as well as a healthy dose of API awareness. We are going to need an army of API designers to help us deliver on the API economy we are all seeing in our heads--so let's get to work. If you do not have a formal API design strategy get to work on one (let me know if you need help). If you have one, please share it, so I can add it to my API design research, for others reference.

We Need an Open Abstraction Layer to Help Us Better Define and Design Our APIs

I walked around San Francisco with Jakub Nesetril (@jakubnesetril), the CEO of Apiary, Wednesday evening, talking about the API space. Eventually we sat down in Union Square, continuing our conversation, which is something I wanted to further process, and blend with some existing thoughts I'm working through. Much of our conversation centered around the need for an open abstraction layer for API design, which would reduce the focus on Swagger vs. API Blueprint vs. WADL vs. RAML vs. any other API definition, and make it just about defining and designing our APIs.

Jakub is right, I'm sure he'd love everyone to use API Blueprint (which thousands are), but it is more important to him that people just use API definitions, and commit to a healthy API design strategy. This line of thinking is in alignment with other thoughts I'm having around there being a common open source API design editor, which I'd like to use as vehicle to get us closer to my vision of a perfect API design editor.

I see an abstraction layer consisting of the following elements:

  • Import - We need to be able to import ANY API definition format we desire.
  • Export - We need to be able to export ANY API definition format we desire.
  • Viewer - We a code view for ANY API definition format we want to look at while working.
  • Editor - We a visual, GUI editor that is all about visual API design, WYSIWG editor for APIs

The import, export, and viewer should work as an API, and the API editor should be a simple, well design JavaScript tool that can be embedded anywhere. The back-end API stack should be available in PHP,Python,Ruby, Node.js, Go, C#, and Java flavors, with a docker image anyone can deploy within their own infrastructure. This should be all about abstracting away the complexities of each individual format, and focus on delivering a simple, yet robust API design editing experience.

API definition format owners should be able to maintain importing, exporting, and viewing layers via some sort of plug-in architecture--meaning the platform is about API definition, the WSDL, WADL, Swagger, API Blueprint, RADL, RAML, Postman Collection, and other formats should be owned by each respective owner. The Open API Abstraction project could provide a single architecture for everyone to plug into, with an emphasis on building the best possible API design editing experience possible.

The Open API Abstraction tooling could be baked into any API service or tooling in the space, allowing the next generation API service providers to focus on what they do best, and not having to build out their own API design editor, while  also baking in compatibility for all API definition formats by default. Such a layer would allow API architects and designers to craft APIs in a consistent way, no matter what API definition format designers and developers might be speaking, opening up a wider world for communicating and collaborating through the API design process.

The API Design Guide Is Just The Beginning Of The Journey - Better Get Started!

I'm processing all of my thoughts from some travel to the big city of San Francisco. I was providing feedback on Microsoft's API design guide, as part of the OneAPI Technical Advisory Group. As I was thinking about the journey Microsoft is on, the role of the API design guide, and how many other companies like Paypal, and Cisco, are on the same journey

In parallel to this, I am on my own journey with my own API stack, I've been looking at everything from a slightly different perspective than many other analysts and providers in the space. When I started in 2010, it was all about API management, then after folks kept asking me about options for deploying APIs I expanded my monitoring to API deployment. Then Jakub the CEO of Apiary, moved the dial back ruth on the life-cycle, and got me paying attention to the concept of API design.

Fast-forward to 2015, I am paying attention to almost 20 separate areas, as part of my core API research. I tune into a number of other areas, but these research projects make up the heart of my API storytelling. On the trip back from San Francisco today I had a few thoughts, and needed to organize them in context of my core research. 

Define (A)

  • A1 - Tech
    • Do you use Swagger to define APIs?
    • Do you use API Blueprint to define APIs?
    • Are there other API definition formats you use?
    • Do you employ NO API definitions?
  • A2 - Business
    • Do you support multiple API definition formats?
    • Do you use API definition formats to engage with other services or tools?
    • Are your service tiers represented in your aPI definitions?
  • A3 - Politics
    • Do you share your API definitions publicly?
    • How do you license your API definitions? Are they open?

Design (B)

  • B1 - Tech
    • Do you use Restlet Studio's API design tools?
    • Do you use APIMATIC  API design tools?
    • Do you use Apigee API Studio API design tools?
    • Do you use Gelato API design tools?
  • B2 - Business
    • Do you use a service provider for API design?
    • Do you use a consultant(s) for API design?
    • Do partners and other stakeholders participate in the API design process?
  • B3 - Politics
    • Do you JSON:API?
    • Do you hypermedia?
    • Do you JSON-LD?

Deploy (C)

  • C1 - Tech
    • What gateway tech do you use?
    • What API frameworks do you use? 
    • What cloud solutions do you use?
  • C2 - Business
    • Are you monetizing APIs?
    • Are you covering costs of deployment?
    • Do you hand API deployment internally?.
    • Do you depend on outside resource to deploy APIs?
  • C3 - Politics
    • Are your API deployment solutions open source?
    • Do Your API Deployment resources scale?

Manage (D)

  • D1 - Tech
    • Are you rolling your own API management solution?
    • Which API management solution are you using?
  • D2 - Business
    • Do you require registration to use an API?
    • Do you have service tiers?
    • Do you have partner levels of access?
    • Do all areas of your companies operation apply same approach?
  • D3 - Politics
    • Is your API management solution open source? 
    • Do you provide support for your API developers?

Secure (E)

  • E1 - Tech
    • Do you require SSL?
    • Do you require API keys? 
    • Are you employing OAuth?
  • E2 - Business
    • Are you investing in security?
    • What would a security breach cost you?
    • Do all areas of your companies operation apply consistent template?
  • E3 - Politics
    • Are you more secure than your competition?
    • Do you share your security practices publicly?


  • F1 - Tech
    • Which management solution do you use to handle monetization?
    • Is there an API for your API monetization layer?
    • Is there a developer dashboard for pricing, billing, and revenue sharing?
  • F2 - Business
    • Do you apply consistent monetization strategy across all APIs?
    • Is your billing real-time?
    • Is API revenue, your only revenue stream?
    • Do you have a credit based system, beyond just API call based?
  • F3 - Politics
    • Do you share your pricing publicly? 
    • Is your partner program transparent?
    • Do developers have dashboard for managing billing?


  • G1 - Tech
    • What services to you use for monitoring APIs? 
    • What open source tooling do you use for your monitoring?
    • Does your monitoring include testing, performance, and security?
  • G2 - Business
    • What do you spend on API monitoring each month?
    • Is there a dedicated person(s) to monitoring APIs?
    • What has outages cost you in the past?
  • G3 - Politics
    • Do you publish your monitoring reports publicly?
    • Do you keep your ecosystem in tune with monitoring via messaging system(s)?


  • H1 - Tech
    • What services to you use for testing your APIs? 
    • What open source tooling do you use for your testing?
    • What are your benchmarks?
  • H2 - Business
    • Do you provide testing tools to your developers?
    • Can developers request specific types of testing for APIs?
  • H3 - Politics
    • Do you publish your monitoring reports publicly?


  • I1 - Tech
    • What services to you use for testing your APIs? 
    • What open source tooling do you use for your testing?
    • What are your benchmarks?
  • I2 - Business
    • Do you have SLAs for any tiers of operation?
    • Do you generate any revenue from SLAs in place?
  • I3 - Politics
    • Do you publish your monitoring reports publicly?
    • Do you consistently meet your SLAs?


  • J1 - Tech
    • What services to you use for virtualizing your APIs? 
    • What open source tooling do you use for your API virtualization?
  • J2 - Business
    • Is virtualization part of your QA process?
    • Do you virtualized instances of your API as an added service?
    • Do you provide a sandbox or simulators for developers by default?
  • J3 - Politics
    • Do you provide virtualization for developers?
    • Are your virtualization images openly sourced?


  • K1 - Tech
    • What services to you use for virtualizing your APIs? 
    • What open source tooling do you use for your API virtualization?
  • K2 - Business
    • Do you have dedicated people to managing your API architecture?
    • Do you have dedicated services for managing your API architecture?
  • K3 - Politics
    • Can you migrate between infrastructure providers? (ie. AWS to Google)
    • Is your server side API code open source?
    • Are you virtualization images openly licensed and available? (ie. Docker Images)


  • L1 - Tech
    • Do you use oEmbed?
    • Do you have bookmarklets?
    • Do you have a JavaScript API?
  • L2 - Business
    • Do you have a standardize strategy for allowing users to embed API driven resources?
    • Is your embeddable strategy integrated with your overall marketing and branding efforts?
    • Do you offer embeddable tool builder?
  • L3 - Politics
    • Are your embeddable tools non-invasive? Protect privacy?


  • M1 - Tech
    • Do you have robot evangelists? Just sounded cool, and couldn't think of anything to put here.
  • M2 - Business
    • Do you have dedicated evangelist resources?
    • Do you contract with 3rd parties for any evangelist resources?
    • Is your evangelism coupled with your marketing?
  • M3 - Politics
    • Are there opportunities for developers to get involved with evangelism?
    • Do you have healthy feedback loop present with your API operations?


  • N1 - Tech
    • Do you have an APIs.json for your API operations?
    • Do you employ API definitions?
    • Are you using hypermedia?
  • N2 - Business
    • Are your APIs plug and play with other platforms?
    • Are your APIs public or private?
  • N3 - Politics
    • Does discovery feed every other layer of API life-cycle?
    • Does discover play into your security strategy?

Sorry, I don't mean to be a downer. But...we are just getting started with stabilizing how we do APIs. I feel like we are beginning to formalize how we manage or APIs (thanks Mashery, 3Scale, and APIgee), and we are getting a handle on API deploy (thanks Restlet, Amazon), and we are deep into understanding how we define (thanks Swagger and API Blueprint), and ultimately design (thanks Apiary, Restlet, and Apigee).

We are moving fast into testing, monitoring, performance, and virtualization (thanks Runscope, APITools, API Science, and SmartBear), but our security sucks, embeddability has stagnated, and evangelism and discovery really isn't improving. I'm working on APIs.json, and bringing together the Swagger and API Blueprint communities, but there is so much work left when it comes to discovery, and automating each of the areas listed above.

There really is no point to this post. It is my mental vomit, after a trip to San Francisco, and working on Microsoft's API design guide. Stay tuned for how any of this applies to anything.

Crafting and Publishing API Design Guide Shows That You Are Further Along In Your API Journey

I spent all day Wednesday, at Microsoft offices in San Francisco, providing feedback on the Microsoft API design guide, as part of the OneAPI Technical Advisory Group. The OneAPI team had already done most of the hard work in hammering out the API design guide, by working with the API leadership from groups across Microsoft--we were just brought in to provide outside perspectives.

A group of about 20 of us, spent the entire day walk through the high levels of the Microsoft API Design philosophy. The Microsoft OneAPI design guide is a draft, so they aren't ready for us to share it publicly, something we'll see in the near future. However, document being ready or not, the process showed me that Microsoft is really working hard to get their API design strategy house in order. They had worked hard to iterate through all the common areas of API design, with their various teams--even some of the more controversial areas like versioning.

I did not feel like I had a lot to contribute to the process. They have some really good API designers, and there was plenty of high quality API design talent in the room, to provide the feedback they wanted. When Microsoft is ready for more of the management, evangelism, and other areas more in the business and politics of APIs, I will have much more to bring to the table. I did however, provide some insight that I think could help the overall process, and will continue to provide feedback--which is why I'm gathering my thoughts in this series of posts.

Prior to me participating in the OneAPI Technical Advisory Group, I had just published the API design guides for Cisco and Paypal, as part of my API design research. Bringing the number of API design guides to 9, which is a good sign the space is getting more serious about standardizing how we do API design. For me, there are two important things going on here:

  • Company Journey - The companies own API journey, allowing them to collaborate and craft a single API design philosophy, with the intent of making it a company-wide initiative.
  • Publicly Sharing - Declaring to the public, this is how we design APIs. Something that allows others to learn from, and merge with their own API design philosophy--benefiting the entire space, while also establishing leaders and followers.

Crafting a document that defines how a company builds software is nothing new. However, APIs aren't just about building software, they are about defining your companies resources, and when you work to standardize how you define your resources as APIs, you are focusing on the core of your business. Next comes the value when building websites, web and mobile applications, and potentially devices as well. Getting your API design house in order, is all about standardizing how you speak API across your company, something that touches every product and service, and is the foundation for your corporate digital strategy.

My participation in the OneAPI Technical Advisory Group gave me a unique glimpse at the API strategy unfolding at Microsoft. While there is still a lot of work to be done, the fact that they are working on a central API design strategy demonstrates to me they are further along in their API journey than I thought they were. Where are you in your own API journey? Does your organization have an API design guide? How do you share this knowledge across your organization, and with the public?

As I monitor the API space, I am always looking for the signals of a healthy API strategy, and I think, when I see a formal API design guide present for any company that I track on, I am going to tack on a couple extra points. A polished, publicly shared API design guide shows organizations are a further along in their overall API journey, than other companies in the space, who are still trying to figure things out.

A Common, Open Source API Design Editor Is Needed For API Service Providers

I love the API design editors that have emerged from Restlet as part of their design studio, and from APIMATIC as part of their SDK management service, and if you haven't checked out Gelato.io, I highly recommend it. All of these solutions provide me with a well designed user interface for working with common API definitions, but even with these offerings, I feel like the overall API universe is very deficient in this area.

It is good that these providers are using common API definitions like Swagger and API Blueprint, but the UI itself is a one-off, and for API definitions to take their place, front-and-center throughout the API lifecycle, we are going to need some common API design tooling. Any successful solution needs to go well beyond just the JSON, YAML, and Markdown, and give us a powerful user interface to craft exactly the APIs we need.

There are several other API definition editors that let you directly edit JSON, YAML, and Markdown, but to move things forward, we need an easy to use, standardized, open source, API interface interface that will work across common API definition formats. Think of what the WYSIWYG editors did for web design--we need a similar, elegant and modern solution for API design.

I have had this conversation with several API service providers, but I wanted to expand the conversation, and see if I can stimulate the development (or release) of an open source API design editor. I am looking for a solution that any API service provider can deploy within their management solutions, encouraging them to not just speak in common API definition formats, but do it in a way that developers, and non-developers alike, can participate at every stage of the API design life-cycle.

API Rate Limits Are Making Me Think More About How I Design My APIs, and How I Consume Them

As I migrate the version 1.0 of my internal systems to an API-first version 2.0, one of the challenges I face is the optimization of some of the features in my own system. I have numerous systems I crafted to solve a specific need, at a specific point in time, with very little consideration about the most efficient design. 

About 50% of my version 1.0 systems employed APIs, many systems relied on directly connecting to my MySQL databases. One example of this is my main news curation screen on my dashboard. This was the replacement for Google Reader about 6 months before they killed it off. My reader system is very chatty, every action I take against a single post (archive, curate, tag, etc.) initiates a round-trip to the database--something when you translate to API calls, becomes a very huge blip on my API analytics. 

I treat all my internal apps, just like I would one of my API consumers, and make them sign up for key, and exist within my API service tiers. There are numerous reasons for this, but in the end, it helps me see things through an external lens. When I got my report on my usage, I noticed my curated API usage was through the roof. This is good right? No! It means I have super chatty features in my application, something I need to refactor. 

My curation may involve 1000 to 3000 news articles which needs to be curated or archived, resulting in potentially 3000 API calls, and when you add on applying tags, and managing other details, I can be in the 5,000 to 10,000 range pretty quick. Its obvious I need a better approach, so I'm developing a new queue based system that lets me work with 25 news stories at once, and submit the changes as a single bulk API call--significantly reducing the number of calls I make.

In the end, my API rate limits are forcing me to think through my app design, and how I make API calls. It also is helping me rethink how I design my APIs. I want each API call to be as efficient as it can from app to server. To quote my friend Tyler Singletary (@harmophone), "rate limits on APIs pushes developers to be more creative". Something I agree with 100%, if it truly is a transparent conversation between API provider and consumer--which in my private, schizophrenic ecosystem is pretty easy to achieve.

Thoughts On API Gateway Deployment Over Artisan Farm To Table API Design And Deployment

I was wallowing in the exhaust of my previous story on Amazon API Gateway, and talking with an API development team about their preferred way to launch an API today. Leaving me thinking...what is the better way to design, and deploy an API? Gateway or hand-crafted?  Ok, cut to the chase, its a bullshit question, but for the sake of working through my own anxiety, I'm going to explore.

For my audience, I'm going to oversimplify what an API gateway is by stating it is a hardware and / or software appliance you can you use to connect to any existing, internal system like a database, CRM, or other, and then quickly and efficiently design, deploy and manage APIs driven by these resources.

Personally I am from the artisan, farm to table guild of API architects--I prefer to hand craft my APIs. Well OK, that is bullshit--I use an API framework, but I wire it up by hand to whatever is the original resource is (database, file-store, other API). This is just my style, and probably most aligned with the fact that I cannot afford any API gateway--something the release of Amazon API gateway has me thinking more about. 

My overall opinion of the gateways I've used is that they lack the amount of granular level control I desire--maybe this is just me. However this is something that is being re-examined for me because of the emergence latest cloud-based API service providers like Restlet APISpark, Wavemaker, DreamFactory, Apitite--and AWS. Honestly I think Amazon will skew the concept of what is an API gateway with their new offering, they just took the name to sell it to the enterprise.

I guess I didn't even have a real point to this story. I just wanted to talk to my API therapist about my own enterprise API gateway baggage and PTSD, and justify my hippie dippe, artisan approach to APIs. Sucka...I got you to listen!! In the end I think I support your API offering, by any name, as long as you help move the conversation forward, which I have to admit I think AWS is doing with their new AWS API Gateway offering--even though they used that name!!!

An Example Of Resource Based API Design Over At The Envirofacts Data Service API

I told a contact of mine at the Environmental Protection Agency I would provide some feedback for the next iteration of the Envirofacts Data Service API, and as I prepare my formal response, there is a huge opportunity for me to carve off some other smaller stories. These stories are what make API Evangelist go around--pulling off these nuggets of learningz, as I'm working with API various providers. 

A concept I work hard to help API designers and architect adopt is around experience-based API design over resource based API design. Something I learned from my friend Daniel Jacobson (@daniel_jacobson) at Netflix, but have been taking it in different directions to help designers and architects from smaller API groups, adopt this way of life--I feel like my work today on the Envirofacts Data Service API provide a great opportunity to move this conversation forward.

When you land on the Envirofacts Data Service API page, you are given a single base URL to employ when "constructing a search" for the API:

Ok, not the best API design, a little confusing, but where do I find the list of possible values for every potential path variable? I scroll down and see some examples, but I have to read the opening paragraph again, before I find a link to the data model. Once I click on the text link, I'm faced with 20 separate "tables"--which in reality are 20 separate APIs, all housed under the Envirofacts Data Service API. (who named this??)

This is resource based API design. You craft an API, that either resembles, or in this case is exactly named just like your database, and its fields. This type of API design, while very appealing to database administrators (DBA), but will leave any new API developer and potential "customer", pretty lost, left with having to work overtime just to understand what is possible. (you can do more work on my behalf)

I had no idea the Envirofacts Data Service API had such a wealth of resources. The overall API landing page, and API design does not tell the story of the value that lies within. Anyways, I'm just embarking on the profiling of this API, and providing a formal review that the team can put to use in their efforts. I'm not trying to bash their work, just help demonstrate to other folks, what I mean when I say "resource based API design", furthering my work to help folks design APIs more focused how they'll be used, not just where they come from, only ticking the box on the task you were given--launch API.

As The API Design Space Grows, More Companies Are Publishing Their API Design Guides to Github

I recently went through my API design research, updating and evolving it, to help me better understand changes in the API design space, while also sharing as much of the information as I can with my readers. One of the resources I include under my tools section are the increasing number of API design guides being published

Currently I'm showcasing the API design guides for 18F in the federal government, Heroku, and PayPal, then the other day my friend Holger Reinhardt (@hlgr360), formerly of CA Technologies, now the CTO at the Haufe Group in Germany, shared his teams API design guidie with me. The executive summary for the guide says it well:

Purpose of this style guide is to gather a list of rules, best practices, resources and our way of creating REST APIs in Haufe Group. The style guide addresses API Designers, mostly developers and architects, who want to design an API. Intention is to ease the design process by providing helpful rules to create a successful API that your customers will love.

One thing I really like, is they also added "please follow the guidelines but don't follow blindly! you can break the rules with justification". Overall the API design guide is full of very pragmatic API design theory, much of what I've heard before, but also emphasizes some very import, forward thinking aspects of modern web API as well. 

The design guide leads with some very sound API wisdom:

  • You should think of an API like a product. Indeed a Business API is a product.
  • Design your API with a customer, or at least with a customer in mind and Get Feedback.
  • Do not implement API Management (use existing services)
  • Every API MUST be described using a formal API description language
  • API clients MUST use a self-service API portal to get access to the API via an API Key

After that, they do not miss a beat going into REST principles stating: "All our REST APIs MUST support hypermedia." The way they lay out their API design best practices makes everything very accessible, leaving hypermedia seeming a very sensible practice, not a bleeding edge design theory. I'm going to try and go through each section and apply to my own internal API design practices, there are several things here I could do so much better, by following.

I may even begin work on my own API design guide, based upon what I've learned from the Haufe Group, 18F, Heroku, Paypal, and others. Not that my version would be any better than the sources, but I'm feeling the process of parsing the work of others, and assembling into my own document will be a healthy journey all by itself. An API design guide is quickly becoming an essential building block for API providers of all shapes and sizes, and publishing it publicly via Github is becoming a badge of leadership and transparency for the rest of the API community.

My API Design Research Distilled Down As Single PDF Guide

When API Evangelist began five years ago it was a single research into the business of APIs, which ultimately became a research project which I called API management. Over the last four years, I have spliced off other areas of research including the elements of my core research into API design, deployment, management, integration, evangelism, and monetization

My goal with each research project, is to evolve my understanding of each area of the API space by identifying the key companies and organizations involved, the open tooling being developed and put to work, and some of the common building blocks that make up each area. For each of my research projects, you can visit its Github repository to get regular updates, but I find many people seem to prefer browsing a single, portable paper of my research.

Each year I usually published a PDF version of each research project, something I have always intended to update regularly. However it seems, this is usually is an annual thing that I find time for in the summer. To helpl change this, I've evolved my own tooling for publishing for what I considers guides to my research areas, allowing me to more easily publish the information and content I regularly curate about the space. 

I just finished v1 of my paper API, which allows me to aggregate pages, organizations, building blocks, tools, and news that I curate, into field guides for my research. Using this new API, i intend to update each of my core research areas each month, getting more disciplined about distilling my research down to a single, coherent story. 

Here is a copy of my API design research as a single PDF guide, you can also find it on the main navigation for my API design research. Now that I have my paper API stabilized, I will going through API deployment, and management, publishing a research guide for each. This process couldn't have come at a better time, as I'm carving out a couple of new research areas for API performance, testing, and monitoring, and I would like to be able to quickly publish guides for each of those areas as well.

Tightening Up The Organizations That Are Included In My API Design Research

I try to go through each of my areas of research as often as I can and update the content, as well as my understanding. Ideally I update the news each week, take a look at the organizations involved once a month, and evaluate the building blocks and tools each quarter. Unfortunately it doesn't always happen as planned, but as a one man operation, I think I do pretty well. 

I just went through my API design research, and adjusted my definition of what I felt needed be listed there. As I move API definitions to their own research area(s), I'm reconsidering what I want to keep an eye on when it comes to API design, and my current definition involves organizations who offer API design editors, either in the cloud or as download. They should allow you to add, edit, and manage the API details, then also provide the ability to import and export using common API definition format(s).

Currently I have nine organizations represented, as part of my API design research:

Apiary Apiary jump-started the modern API design movement, by making API definitions more than just about API documentation, allowing API designers to define APIs in the machine readable API definition format API blueprint, then mock, share, and publish documentation via a cloud platform.    
Apigee API Studio Apigee launched their API Studio out of their earlier Apigee-127 product, their work on the Swagger platform and editor, and their BaaS offering. Opening up the ability for developers to design, mock, test and share via their online platform.            
APIMATIC When you use APIMATIC to manage SDKs, they provide you with an editor for adding, editing, and deleting the details of each API. When you bundles this with their multi API definition format import and export, the platform quickly becomes an API design tool as well as a platform for generating your SDKs.          
APIMATIC API            
deployd Deployd is an open source API design, and deployment platform that allows developers to quickly design, customize, and deploy an API, with supporting application interface via a downloadable app, and command line utilities.        
Mashape Mashape provides an API editor, as part of their API management and discovery platform, allowing API providers to add, edit, and manage the details of an API design, while also managing the rest of API operations--from design to discovery and integraiton.      
MuleSoft Mulesoft provides a cloud, and open source version of their API design editor, enabling API designers to craft APIs using the RAML API definition format, then publish to notebook, as well as manage through other aspects of the API lifecycle with other Mulesoft systems.    
Restlet The Restlet Studio allows you to design APIs, and add, edit, and manage the details via cloud based API editor, import and export in Swagger and RAML, then also generate server, and client side code, as well as interactive documentation.    
Sandbox Sandbox provides an environment for users to quickly mock APIs that are generated from common API definition formats like API Blueprint, and Swagger, then deploy, collaboratively build, and debug APIs using an online platform.        
Swagger Swagger is a machine readable API definition format that has built a number of tools around the specification, including an open source API design editor that allows you to design, import, and export APIs in JSON and YAML, then also generate server, and client side code, as well as interactive documentation.      

As I work to refine each of my research areas, it can be hard to draw the line where each projects starts, and ends. I had Readme.io, and Wavemaker on this list, but I really felt they were more in the API management, and API deployment realms, resulting in me drawing the line where I did.

Next I am looking to tackle the API design tooling, which I am looking to organize into groups, as there is kind of a mash-up of different things there now. Hopefully I can break it all into a more coherent breakdown of not just the open tooling, but also open content, and other resources that might help all of us all in our API design journey. 

One thing I have to say after updating the list of organizations on my API design research, is I am impressed how far the services, tooling, and overall API design mindset has come in just two short years. We have more than one editor, with a couple of the implementations being open source--I'd say this is pretty healthy progress. ;-)

The API Design Tooling I Have Included In My Research

I am going through each of my research projects, and tightening things down, now that I have them all driven through my new, master stack of APIs. First up was API design, and the other day I spent time going through the organization I track on as part of my API design research, and today mission was to refine the tooling section.

Previously my tooling page was just an alphabetical list of tools, and I wanted to at least group things in a more meaningful way, reflecting how I break them down in my own monitoring system. So I reworked the publishing to allow me to group the tools by tags, resulting in the following list:

API Blueprint

API Blueprint


API Blueprint is a documentation-oriented API description language. A couple of semantic assumptions over the plain Markdown. API Blueprint is perfect for designing your Web API and its comprehensive documentation but also for quick prototyping and collaboration. It is easy to learn and even easier to read – after all it is just a form of plain text. API Blueprint, its parser, and most of its tools are completely open sourced so you don't have to worry about vendor lock-in. This also means you can freely integrate API Blueprint into any type of product, commercial or not.


Atom Editor API Blueprint Preview


The Atom Editor API Blueprint preview is a plugin for the Atom editor that allows you to render HTML representation of API Blueprint in the right of the current open Atom editor using CTRL-SHIFT-A. This plugin requires Agilo to be installed and available in your path.


API Definitions

API Blueprint


API Blueprint is a documentation-oriented API description language. A couple of semantic assumptions over the plain Markdown. API Blueprint is perfect for designing your Web API and its comprehensive documentation but also for quick prototyping and collaboration. It is easy to learn and even easier to read – after all it is just a form of plain text. API Blueprint, its parser, and most of its tools are completely open sourced so you don't have to worry about vendor lock-in. This also means you can freely integrate API Blueprint into any type of product, commercial or not.


RAML Specification


RESTful API Modeling Language (RAML) is a simple and succinct way of describing practically-RESTful APIs. It encourages reuse, enables discovery and pattern-sharing, and aims for merit-based emergence of best practices. The goal is to help our current API ecosystem by solving immediate problems and then encourage ever-better API patterns. RAML is built on broadly-used standards such as YAML and JSON and is a non-proprietary, vendor-neutral open spec.


Swagger Specification


Swagger is a simple yet robust representation of a RESTful API, with a large ecosystem of API tooling that includes code generation, interactive documentation, and much more. Currently  there are housands of developers supporting Swagger in almost every modern programming language and deployment environment, using the 100% open source software and specification.


API Design Editor

Atom Editor API Blueprint Preview


The Atom Editor API Blueprint preview is a plugin for the Atom editor that allows you to render HTML representation of API Blueprint in the right of the current open Atom editor using CTRL-SHIFT-A. This plugin requires Agilo to be installed and available in your path.




Deployd is the simplest way to build real-time APIs for web and mobile apps. Ready-made, configurable Resources add common functionality to a Deployd back-end, which can be further customized with JavaScript Events.


RAML API Designer


API Designer is a standalone/embeddable editor for RAML (RESTful API Modeling Language) written in JavaScript using Angular.JS, which by default, uses an in-browser filesystem stored in HTML5 Localstorage. Mulesoft provides a cloud version of the editor as part of their larger API suite.


Swagger Editor


Swagger Editor lets you edit API specifications in YAML inside your browser and to preview documentations in real time. Valid Swagger JSON descriptions can then be generated and used with the full Swagger tooling (code generation, documentation, etc).


API Design Guide

18F API Standards


18F is a technology team inside the US federal government. 18F is very API-focused: our first project was an API for business opportunities. This document captures 18F's view of API best practices and standards. We aim to incorporate as many of them as possible into our work. APIs, like other web applications, vary greatly in implementation and design, depending on the situation and the problem the application is solving.


Heroku - API Design Guide


Heroku has provide their own set of what they call HTTP+JSON API design practices, which I think describes what we do much better than just web API. The guide is designed for internal and external usage, and looking to provide some consistency in API design, that anyone can follow.


Paypal API Design Standards


Paypal has developed their own API design standards, providing a common blueprint for their teams to follow, while also transparently sharing with their API community, and the wider API industry to follow.


Realtime API Design Guide from Fanout


An API Design Guide dedicated to helping you understand the common design approaches, as well as the pros and cons of realtime API design, showcasing the implementations of 16 public real-time APIs--developed by Fanout.io




NARWHL is a framework intended to provide a roadmap for those needing to implement an API using current best practices but flexible enough to grow into the future. This guide contains a set of API design recommendations you can implement today with the confidence that your API will be RESTful (level 3 according to the Richardson Maturity Model) and able to adapt to future iterations while still making it easier for developers to use.


UK Government Service Design Manual for APIs


Martha Lane Fox report called for government to act as a wholesaler, as well as the retail shop front, for services and content by mandating the development and opening up of Application Programme Interfaces (APIs) to third parties -- this section is a set of guiding principles for exposing a digital service as an API.


White House Web API Standards


This document provides guidelines and examples for White House Web APIs, encouraging consistency, maintainability, and best practices across applications. White House APIs aim to balance a truly RESTful API interface with a positive developer experience (DX).



RAML Specification


RESTful API Modeling Language (RAML) is a simple and succinct way of describing practically-RESTful APIs. It encourages reuse, enables discovery and pattern-sharing, and aims for merit-based emergence of best practices. The goal is to help our current API ecosystem by solving immediate problems and then encourage ever-better API patterns. RAML is built on broadly-used standards such as YAML and JSON and is a non-proprietary, vendor-neutral open spec.



Swagger Specification


Swagger is a simple yet robust representation of a RESTful API, with a large ecosystem of API tooling that includes code generation, interactive documentation, and much more. Currently  there are thousands of developers supporting Swagger in almost every modern programming language and deployment environment, using the 100% open source software and specification.


I have other resources I need to add to this list, but each one requires a certain amount of love before its ready to be included. Everything here should be openly licensed, providing essential tools API providers, designers, and architects will need. If there is something that you think should be here, let me know, and I will consider adding it. 

One area I am still working on, is cross linking areas of tooling, potentially with other research areas. For example API definitions has its own evolving area, and Swagger does as well. This is why I wanted to retool and break things down by tags, because some of these tags eventually become other projects, and when I break off a new area, I  want to keep things connected.

Next I'll give the API design building blocks page a little attention, but it was recently overhauled, so I think I am pretty good there. After that, I need to give my paper API a little love, which allows me to aggregate my design research into a white paper. Once I'm done with that I'll quickly go through some of my other core research like API deployment, management, discovery, and beyond.

Using API Definitions To Help API Providers With Their API Design Roadmap

As I work to create Swagger API definitions for the almost 1000 companies in my API stack, I'm chasing an elusive definition of a complete Swagger definition for any API. Only a small portion of APIs I am defining using Swagger will reach an 80-90% completions status, in reality most will never be complete for reasons that are totally out of my control.

When it comes to crafting API definitions for public APIs, I may be able to get the API definition complete in the sense that it has all the paths, parameters, responses, definitions, and security configurations, but if the API itself is missing pieces--the API definition will always be incomplete (in perpetuity).

As I work to automate the questions I ask of Swagger definitions, helping me get to a more coherent definition of what is a complete Swagger definition, I can't help feel the need to offer API design tips to the API providers I am profiling. Honestly I have never considered myself a high quality API designer, I've been more business than tech, but I can't help pointing out the obvious stuff. 

I am still using my API definition tooling for my own goals around defining the API Stack, but because I'm building it all as APIs, I intend to open it up to others for analyzing their own API definitions, determining how complete they are, and potentially offering up tips on what could be done to improve them. A kind of self-service, API design tip API, that helps with some of the most common elements that are missing from API designs.

In 2015, API definitions are opening up a buffet of services that are courting API providers ranging from mocking and deployment, to monitoring and security. I don't see why API definitions couldn't also allow for professional API designers to help API providers evolve their APIs in a more constructive ways, from the outside-in. Using Swagger or API Blueprint, professional designers could easily provide suggestions for existing API providers and their designs, then give them potential suggestions that they could use in their API design road-map.

Anyhoo, food for thought!

Visions Of My Perfect API Design Editor Using Electron

Darrel Miller(@darrel_miller) reminded me of the desktop development platform Electron the other day, with his story on Moving Beyond the Browser with JavaScript and Hypermedia. I had been eyeballing Electron as a potential candidate for my perfect API design editor, something I honestly don't have the bandwidth to build, but is something I enjoy pushing forward in thought.

If you aren't familiar with Electron, it is what powers popular desktop version of the apps that I use most--Github, and Slack. The open source desktop framework, developed and maintained Github, allows you to deliver simple, easy to maintain desktop experiences, using HTML, CSS, and JavaScript--powered by Chromium and Node.js. Electron is appealing to me because it allows me to use the tech that I am most fluent in, to deliver high quality desktop apps, but also as Darrel mentions in his story, it has the potential to improve on the quality of JavaScript apps we build--giving us C grade JavaScript people a framework to live within. ;-)

I have a pretty clear vision in my head of the API design editor that I would like to see developed. I doubt this will be something I will have the time to develop personally, but I would like to encourage others to develop API design editors using Electron, and encourage a focus on it being extensible, allowing 3rd party, API driven API design features to be added--keeping the editor simple, with almost every feature living as an extension.

I think the API workflow and life-cycle will be different for each API provider, and we need to be able to have the features that we need most, right at our fingertips. Through my profiling of 917 companies, in 223 business sectors, with 882 APIs cataloged, and 407 Swagger definitions so far, I intend to provide API design tips and dictionary functionality based upon popular / successful API designs

Anyways, back the actual work at hand. I just wanted to revive these visions of my perfect API design editor, so I can add to, and make sure it is connected with the potential for developing the next killer API design editor, using Electron.

Applying A Little Hypermedia Is Helping Me Tighten Down My API Design And Tell A Better API Story

I get hypermedia at a high level, but have no real experience designing or deploying a hypermedia API or client. For the longest time I just watched the hypermedia conversation from afar, but in the last year I have spent time learning about the different approaches, but I still have not gone as deep as I'd like. I'm looking to change this over the summer, and begin to add some hypermedia thinking to my own API design.

To get started I've targeted my curation API for the addition of a hypermedia layer, and I'm choosing Siren as my hypermedia format. Siren spoke to me over some of the other approaches, but once I get my bearings I will look at tackling one or two more implementations. As I do with my other work, I'm just looking to share my thoughts in real-time, as I go along.

First, the process is really helping me tight down my API design. This is something I feel going with an API first design approach using Swagger has helped me, but adding the Siren format to the design of my API is taking this to a whole new level. I still have a longs ways to go in crafting the Siren responses for my curation API, but so far the process of defining the entities, actions, and links is really helping me think through the overall API design--leaving very few loose ends.

Second, the actions and links are also helping me really craft a more meaningful workflow around an API resource that I depend each day. This link curation API that I use in my daily, weekly, and monthly monitoring of the API space has an ever evolving workflow associated with it, but ultimately its been something I've kept in my head, or visualizing in the minmium viable (half-assed) clients I have built to help manage my world. This hypermedia learning process is forcing me to think it through, as if I'm telling the workflow to the world. 

This feels very much like storytelling on API Evangelist to me. You see I tell stories to work through my ideas, and craft a nevernding stream of evolving ideas, that help me better understand the world of APis, but also share it in a way that my readers can understand along the way. While applying hypermedia principles to my API design, I feel like I'm working through my API resources in much meaningful ways, and I'm not even approaching what some of the popular benefits of hypermedia are, yet.

I still don't what I am doing entirely, but sure enjoying the process.

Targeting Some APIs In My Stack For House Cleaning And Maybe Some Design Iterations

As I look through more APIs, and I don’t just play around in their developer portal, and look at documentation, I am actually get my hands dirty generating Swagger definitions, and authenticating and making calls to an API. There is no better way to get to know an API, that generating a Swagger definition, and integrating with it—something when done, you always walk away with a new perspective.

Once I get more of the APIs profiled in my API Stack, I’m going to see if I can configure my API editor to let me iterate on other people’s API designs a little bit. As an API consumer, you don’t always get a voice in the design of the next version of an API, but with API definitions like Swagger and API Blueprint, you can actually make edits, and then share them back with a provider. Of course it is still up to a provider to decide on what they accept, but there is not better way to make suggestions than a machine readable API definition, that is ready to go.

When I get around to doing some housecleaning on these API designs I generated, and possibly make some design iterations, I’ll focus on some of the smaller operations, leaving the bigger teams to do their own heavy lifting. Also, my goal isn’t just to iterate on API designs to help the original provider improve on their design, my goal is to iterative and improve on the API designs in my stack. The more designs I play with, more designs I have in my library, and the more I get a feel for what I think API designs could, or should look like.

I can’t fix all the APIs in the world, but I can improve on the hard work that has already occurred, and who knows, maybe some providers will see it for the compliment that it is, and listen to some of my API designing that is occurring out loud.

My API Design Research

I am giving each of my primary API research sites a refresh, and first up is the home page of my API design research. As I update each home page, I'm going to publish here on API Evangelist to help bring more awareness to each of the main areas I'm studying.

This is one of my API research sites, focused specifically on API design. My name is Kin Lane, and I am the API Evangelist, working as hard as I can to understand the world of the Application Programming Interface, widely called an API. This network of API research projects all run on Github, and is my real-time workbench, which means there is a lot of finished work present, but occasionally you will also come across areas projects that are unfinished--you have stumbled in my API design research, you will find the main API Evangelist site over here, with other links to my work.

This site is where I publish news that I have read, stories I’ve published, company I’ve profiled, and valuable tools I’m stumbled on across while researching API design space. I’m in the middle of carving off a couple individual projects from this API design research including hypermedia, and a soon API definition specific projects. As with my other research projects, there can be a great deal of overlap with other projects, when it comes to defining exactly what is API design. This research isn’t about being complete, or finished, it is about maintaining a liquid understanding of what API design is, and be as comprehensive as a one man operation can be.

I execute on my API research by focusing in on specific areas like API design, getting to work understanding who the key actors are, which may include individual personalities, or corporate, government, or institutional entities. I profile each actor, and establish monitoring streams using Github, Twitter, RSS, Stack Exchange, and any other relevant channels. Throughout my monitoring I keep an eye out for interesting articles, white papers, announcements, and tooling that contribute to, and expands upon my definition of what is API design.

The more I research an area like API design, the more I’m able to identify common building blocks, that make up the space. For API design, this can be as fundamental as API definitions, or as specific as publishing and sharing interactive documentation. My interpretation of these building blocks change over time, and sometimes I will link up these building blocks with other research projects, or spin off as independent projects, allowing me to dive even deeper—for example, Swagger began as a building block on API management, and is now its own research area entirely.

All my research is openly licensed CC-BY, and is meant to help grow the awareness around healthy API design practices. I try to be as fair as I can when covering companies, individuals, and the tools they provide, but ultimately you will notice I have my favorites, and there are some areas I only touch on lightly, for a variety of personal reasons. I try to stay as neutral as I can when it comes to technological dogma, and company allegiance, but after almost five years, I have some pretty strong opinions, and can’t help but try and steer, and influence things in my own unique way. ;-)

Thanks for reading!

There Are Four API Design Editors To Choose From Now

In the early days, there was just one API design tool to use, Apiary.io. Now at the end of 2014, we have four separate API design tools to choose from. I credit Apiary.io for opening up this new era of API design, expanding the API life cycle, and emphasizing healthy API design practices over just API deployment and management.

In my opinion the expansion of APIs design formats, and API design tooling is extremely important to the space, allowing API providers to have conversation around API design with developers, and key business stakeholders, before development actually begins. However, the benefits of healthy API design, using leading API definition formats, goes well beyond just design, and the rewards can be seen throughout the entire API lifecycle.

There are three API design tools, from each of the providers of the modern API design formats:

Apiary.io - Collaborative design, instant API mock, generated documentation, integrated code samples, debugging and automated testing using the API Blueprint API definition format.
API Designer | Anypoint API Portal - Enables the ability to design APIs in the RAML API definition format, and mock, preview and save API designs into a notebook, and integrate with other Mulesoft API tooling.
Swagger Editor - Allows the designing APIs in the Swagger format in both YAML and JSON, allowing you to import, edit, preview, and export API design docs.

All three of these API design tools are developed by the creator of the leading API definition formats, API Blueprint, Swagger, and RAML. (aka. Apiary, Wordnik, and Mulesoft). Now, a significant evolution in the API design tooling space has occurred and a cross format API design tool has emerged from the popular Java API framework Restlet.

Restlet Studio - Allows you to create, and load API designs in Swagger and RAML formats, save, and generate server side scaffolding, and client side SDKs in multiple languages.

The emergence of the Restlet Studio is significant because it represents the expansion API design tooling beyond the three leading API definition format providers, as well as being the first cross-format API design editor. There are other API service providers who deliver vital API services along the API lifecycle like Ready! API, for mocking and testing your APIs, or APIMATIC which generates SDKs, both of which support multiple API definition formats, but Restlet Studio is the first cross-format purely API design editor (correct me if I’m wrong).

I’ll be spending more time mapping out all of the tools that are emerging to deliver vital services throughout the API design life cycle, something that gives me hope for things standardizing when it comes to designing, deploying, managing, and integrating with APIs. It is an exciting time to be in the API space, as the universe rapidly expands, and more companies emerge to help us make sense of this rapid expansion.

The Heroku HTTP API Design Guide

I stumbled across a cool resource out of Heroku today, their HTTP API design guide, which intends to direct practices for API design on the Heroku API platform.

Heroku’s goals around APIs design are, "consistency and focusing on business logic while avoiding design bikeshedding”. They put out the guide to drive consistent aPI design practices at Heroku, but are also interested in sharing with the wider API community.

I think API design best practices are something every API provider should have, and publish publicly (on Github). I think it is ok to even fork, and modify existing guides like Heroku’s or maybe from 18F out of federal government. This most important thing is that you have a guide that can guide your team, or other teams within your organization.

Now that I’m seeing more of these, I will start flagging, and aggregating them so we can browse and continue learn the API design practices from the leading API providers out there.