{"Hypermedia APIs"}

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.

See The Full Blog Post

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.

See The Full Blog Post

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.

See The Full Blog Post

Telling A More Complete Story With Hypermedia

I spend a lot of time connecting the dots with APIs, trying to understand what resources are available via an API, and then how I can actually put them to use. I can usually land the documentation page of an API, and be up to speed about what resources are available, and have a basic level of understanding of how I can put the APIs to work withing 15 minutes--if the API is reasonably designed, and somewhat documented. Where things get tougher for me and require much heavier of a cognitive load, is going from the basics to understanding what is possible when you can really connect the dots between all the APIs a provider makes available.

While I was profiling, and learning more about the AWS API Gateway, which is an API that let's you deploy and manage your APIs, I found that their usage of the hypermedia format HAL, significantly contributed to me going from basics to a better understanding the big picture, and what is possible at scale. Each API path I learned about gave me a wealth of links describing what was possible next, providing details on what I should be doing next, perpetually introducing and teaching me about what is possible with the AWS API Gateway.

I am hyper aware of the cost of getting up and running using an API. As a one person shop, reviewing thousands of APIs, my time is precious. I've looked at all of the AWS APIs, and it's easy to get a basic understanding of the resources available with their classic action= approach, but I rarely ever see the big picture of what is possible with the API. After spending the same amount of time in the AWS Gateway API as I would have spent learning any of the other AWS APIs, I found that I had a much greater understanding of what was possible, due to the presence of the hypermedia design pattern.

Hypermedia provides a much more complete story for me, as well as offering up a much more honest approach to supporting the API. It doesn't just provide me with documentation of available API resources, it connects the dots for me, showing me what is possible. In this scenario, it is an API deployment and management API, so while I'm learning about the API, I'm also being introduced to new API deployment and management concepts along the way. We shouldn't assume that all of our consumers will be able to connect the dots, we should be providing them with a more complete story of what is possible with the API design patterns we choose.

See The Full Blog Post

A More Honest And Flexible API Contract Using Hypermedia

One of the reasons I write so much on API Evangelist is to refine how I tell stories about APIs and hopefully make a bigger impact by being more precise in what I'm saying. I feel like one of the reasons why hypermedia API concepts have to take longer than we anticipated to spread is because many (not all) of the hypermedia elite suck at telling stories. I am sorry, but you have done a shit job selling the importance of hypermedia, and often times were just confrontational and turning many folks off to the subject.

I am working on playing around with telling different stories about hypermedia, hoping to soften some of the sharp edges of the hypermedia stories we tell. One of the core elements of hypermedia APIs is they provide us with links as part of each API response, emulating much of what works with the web, in the system to system, and application layers of the web. One of the benefits of these links is they help facilitate the evolution and change that is inevitable in our API infrastructure.

The default argument for hypermedia folk is often about versioning and change-resistant API clients. I'm looking to help make these concepts more human, and that employing hypermedia as part of our API contracts is more about providing an honest and flexible view of the business relationship we are entering into. As API provider and consumer, we are acknowledging that there will be change and evolution in the resources that are being delivered, and being more honest that this exists, as we craft this API contract.

As an API provider I am not just going to dump this JSON product response on you, and expect you to know what to do, refusing to have a discussion with my consumers that this product will change. it might be out of inventory, and might be replaced by another product, and any number of evolution changes that may occur in the normal course of business. Hypermedia gives me a framework to acknowledge that this will indeed evolve upon entering our agreed upon API contract, and provide a channel for all integrated API clients to receive future instructions about what is possible when things do change--our API contract is flexible.

As an API provider, when I share this machine-readable representation of my product I'm not just assuming you know you can add it to the cart, or to a wish list, I am providing you with the links to do this, and the link relations that define this relationship. As things change and evolve, I have a way to share other opportunities, and changes to this business contract. When a product is recalled, there is a link routing you to what you need. When a product is replaced, you are routed to what you need. As an API provider, I'm committed to providing you with what you need to be successful when putting API resources to work.

Hypermedia goes being just providing links, managing versioning, and ensuring more resilient API clients--a very technical story. Hypermedia gives us a more honest and flexible way to define the API business contracts we are entering into when we make API resources available internally, with partners, and even with the public at large. Change is inevitable, and I feel like we need to be more honest about this change and be less rigid in how we are doing things, and I keep coming back to hypermedia as a meaningful way we can make this happen.

See The Full Blog Post

Storytelling and the Future of Hypermedia APIs

Helping people understand the potential you see around a particular approach to API design, is hard stuff. Providing easy to follow stories, and implementations that the average person can follow is something I've dedicated myself to at API Evangelist, and something I'll keep working on when it comes to evolving API approaches like hypermedia. 

Hypermedia has long suffered from an image problem, something I feel can be remedied through a little hacker storytelling on the part of hypermedia API media type owners, API providers who bake hypermedia into their practices, and the developers who are crafting meaningful hypermedia driven experiences. In 2015 I feel like we are getting closer to fixing this, but as I said, this stuff is hard, and takes a lot of work.

Until there are easy to follow stories, and examples of hypermedia in practice, only us in the know are going to care. I see a lot of potential ideas for hypermedia hacker storytelling in my head, but getting these out into stories, and into practice takes a lot of work, and massaging of ideas. One idea that was just moved forward for me, was derived from a post Audrey sent to me today, a story from Eater, called One Night Kachka.

This approach to storytelling, provides me with a potential blueprint for evolving how I can tell stories using hypermedia APIs, and Single Page Apps (SPA). The Kachka story is full of rich structured data and content, providing a compelling timeline breakdown of a nights activity at a restaurant. There are so many interesting objects here that could be defined and woven together with a hypermedia core--then simply presented via a hypermedia client (aka Single Page App). 

Additionally you could generate an administrative SPA, allowing a user to be walked through the process of telling a story, adding the timeline elements, people, pictures, videos, and data around sales and activity--then point user towards the SPA client that allows them to explore the interactive story they just told. This represents an evolution in storytelling around hypermedia for me, where I move from talking about "clients" to talking about a more tangible storytelling SPA, that potentially a wider audience might be able to follow.

What is really beautiful about this model, is an API designer who was skilled in a hypermedia approach like HALCollections+JSONSiren, or JSON-LD could craft a core that could drive this restaurant experience, but also be flexible enough to tell other similar stories like one night at the club, concert, or maybe just Christmas eve at home with the family. With the SPA client approach, you could easily provide some amazing CSS implementations, using a CSS Zen Garden approach

Food for thought! I am just now playing with Siren, in redesigning how I tell the story around my API news curation, but once I get my chops up with Siren, HAL, and Collecton+JSON, I may take a crack at assembling a hypermedia core for an API that could drive stories like One Night Kachka.

See The Full Blog Post

A Good Example Of Hypermedia API Using The Siren Specification

I am spending a small amount of time each week, adding a new hypermedia layer to my link curation API. My goal is to better understand hypermedia, while also improving the designs of the APIs that I depend on for my own operations. During todays work, I was looking for a more extensive example of Siren being used by an actual API provider, taking me beyond what Kevin Swiber (@kevinswiber) provides in his examples. 

The example I found that has really helped me go from 0-60 when it comes to Siren (well maybe more like 0-15), was the TV and streaming video API platform Wurl. The API has a pretty robust example of Siren being used in the wild, allowing me to reverse engineer the design patterns and apply in my own way--this is one way I learn things, through breaking down other people's work. 

Wurl has 11 entities defined, demonstrating the really versatile power of Siren in defining the resources an API is serving up. They have some really nice workflows around each video episode, allowing them to be organized into series, bundles, and providing user management and search. For me it is a great introduction into what hypermedia is, and more specifically what Siren offers, in a working, real-world example.

I only have so much bandwidth to spend on this work, but after getting my feet wet adding a hypermedia layer link curation API using Siren, and playing with the Wurl API, I've got a lof of new thoughts floating around my head around how I can improve my own API designs, and better present the large amount of information, visualizations, and other information available within my API curation lifecycle.

See The Full Blog Post

Are You A Hypermedia Pragmatist?

I have been spending a lot more time in 2014 learning, discussing, and telling stories about hypermedia. Early this year I identified that hypermedia was moving beyond just academic discussion, and entering the mainstream consciousness of the API community. I do not consider myself a hypermedia expert, and had a lot more to learn, and by moving hypermedia further into my regular research, over time this education would come.

At the end of 2014, my deep technical knowledge of hypermedia, and the nuances between each of the formats isn’t there yet—I just do not have the production experience with any of them to know what I’m doing. I can provide an overview of the technology, the various formats, and the people behind each movement, as well as point to some real world hypermedia implementations, but when it comes to getting down to the details I’m just not there yet.

One of my readers, from a leading tech company recently emailed me asking for a “hypermedia pragmatist”—here is an excerpt:

We have a lot of opinions in our organization about how we should implement hypermedia APIs. I’d like someone to discuss pros/cons of different approaches in our monthly API discussion group but don’t want someone who only promotes one view (i.e., JSON-LD, HAL, etc.) or is extreme in their hypermedia views.

Do you know of anyone whom you would consider a hypermedia pragmatist? Someone who understands the competing specs but is pragmatic about how to implement.

This describes what I’ve set out to be for the API space in general, being a pragmatists in the tech, business, and politics of APIs, and I guess I can "almost" call myself a hypermedia pragmatists, except I just don’t have the implementation experience. I’m sharing this story, because I’m getting this question at multiple companies, educational institutions, non-profit organizations, and government agencies I'm in talks with.

Eventually I will get there, and obtain the experience in implementing each of the leading hypermedia formats, but until then I need some help. Do you consider yourself knowledgeable across the leading formats? Are you a pragmatists when it comes to understanding what is possible when it comes to API design, and the implementation? Are you nice, professional, and informative when it comes to API education, strategy, and execution?

If you are a hypermedia pragmatist and open to consulting, and telling stories from your engagement, please let me know.

See The Full Blog Post

Top 5 Most Popular Themes On API Evangelist In 2014

Throughout 2014, when I look at the top 10 posts in my Google Analytics dashboard each month, there has been a consistent theme of what stories are driving page views. The concept of a page is only one metric I look at when evaluating where the API space might be going, and while I don’t write stories specifically to page views, they do provide me with a general barometer of what my readers are interested in.

I’m seeing give areas consistently generating the most views across the API Evangelist Network:

  • Internal APIs - This slot is pretty much dominated by The Secret To Amazons Success Is Internal story getting thousands of page view each month, even with being written back in January of 2012.
  • Single Page App Tooling - Simple, easy to use formable single page apps like my CSV Converter, and my Data.Ongithub.com produce some really long lasting traffic, providing value to users.
  • API Design - This is definitely the topic of 2014, with all of my stories talking about API design tools like Swagger and API Blueprint dominating the top 10.
  • Hypermedia - Its time has come in 2014, and hypermedia stories like What Are Some Examples of Hypermedia APIs are popular with developers, and non-developers when it comes to understand what hypermedia is all about.
  • API Roundups - A pretty proven formula of rounding up listings of APIs for a specific purpose, the only difference is when I do it, I personally look at each API and make sure there is something there, defining what I consider to be API stacks or collections.

I’ll revisit this at the end of the year and see if it still stands up. For me it provides some sort of map of where my readers heads are at, and by no means is any measurement of where the API space is going, but is at least a place to start thinking about what is on people’s mind.

I usually don’t spend much time looking at metrics across my platform, but I see a lot of interesting trends, and I like being a transparent layer for the API space, so I think i will try to better track on some patterns I’m seeing in my own network, as well as across the space, and share as stories here on the blog.

See The Full Blog Post

Translating The World Of Hypermedia APIs For The Normals

I’m giving my hypermedia API research a little love today, and as part of this I was reviewing examples of hypermedia in the wild like with the Elastic Path Cortex API. Elastic Path was the first company to introduce me to the possibilities around hypermedia way back in 2011, so I enjoy checking in regularly to see what they are up to with their APIs.

As of January 2014 I’ve committed more time to doing research on hypermedia APIs, as well as work to tell stories about how hypermedia is being applied by companies, in a way that anyone can understand. This last summer at API-Craft in Detroit, the hypermedia community acknowledged that they have an image problem, and had some significant work ahead of them when it comes to storytelling, specifically around speaking to the “normals”.

Personally, I don’t 100% speak hypermedia-eze, but I know with some practice I can get better at translating. I also know that some of the hypermedia folks aren’t so good at speaking plain english to normal people, but with some practice I htink they will also get better. To help me in my jouney I figured I’d translate what Elastic Path has written on their Cortex API page, but first I want to acknowledge the image they have--which is the first sophisticated hypermedia visual I’ve seen, and I want to work on creating more like it.

Let’s get on with the translation from hypermedia-eze to plain english. Elastic Path starts with:

Cortex is a mediation layer that uses patent-pending dynamic linking technology to discover and assemble resources from multiple business platforms into one consistent interface. Data and services from enterprise applications like Commerce Engine, Adobe® Experience Manager, OpenText® CEM, and others are mapped to Cortex using a lightweight schema. Once abstracted, these resources — from any source — are linked together to generate Cortex Business APIs that securely project your unified services to the world.

Translation: Cortex brings together all your information, no matter where it resides, into a single, consistent API that you can then securely share with anyone you desire.

Cortex mediation completely decouples client applications from business platforms, yet enhances their ability to securely retrieve data and perform transactions. This breakthrough hyper media approach gives designers, developers, and API consumers the unprecedented freedom they need to create unique digital experiences — from mobile apps to Internet Retailer® Top 500 websites — that engage customers and create business value.

Translation: Cortex understands that you are delivering information to a wide assortment of web, mobile and tablet devices in 2014, and Cortex handles the heavy load, abstracting away the complexity for API developers, allowing them deliver more meaningful experiences for end-users, agnostic of any platform they use.

A hypermedia API means self-serve e-commerce.

Translation: A hypermedia API means self-serve e-commerce.

Unified services from your application portfolio are exposed via Cortex Business APIs, a set of highly scalable REST interfaces that conform rigorously to the HATEOAS constraint and Level 3 of the Richardson Maturity Model. This means that client applications can securely access enterprise data and perform authorized operations using only the hypermedia controls generated by the mediation layer. No deeper knowledge of your business platforms is required — so the tyranny of constant integration work ends with Cortex. It's simply the best API for ecommerce platforms.

Translation: Similar to understanding all of the devices you will be delivering information to, Cortex understand which users are accessing your information, and securely delivers only the information they have access to, and enables them to only take the actions they have afforded to them, again abstracting away the complexity of business operations for developers.

My translations may not be perfect, but in short, because the they employ hypermedia design patterns, the Cortex API can more intelligently consider which internal, or external systems your information is being pulled from, while also understanding the context of the end-user who will be accessing this information, both who they are, and what device(s) they are using, potentially handling all of this logic for developers, leaving them to do what they do best.

You see, APIs have been abstracting away the complexity of back-end system for a while now, but hypermedia has the potential to abstract away a couple more of the key layers for developers--who the user is, and what device (channel) they are engaging upon. When done right, this has the potential to make the delivery of digital resources via APIs, to any number of online channels much more streamlined and efficient for everyone involved.

Of course, even though all of this is a reality with Elastic Path right now, we have huge hurdles to jump in helping resource owners, and application developers understand the benefits hypermedia can bring to their operations, and this is why I'm honing my hypermedia translation and storytelling skills so I can help be a conduit in these ongoing discussions.

See The Full Blog Post

Extract Knowledge From Audio And Video Using The Clarify API

I’ve been tracking on a growing number of video, and voice enabled APIs lately, and one that is continually popping up to the top of my API monitoring list is Clarify.

The description Clarify provides on their docs page is pretty concise:

The Clarify API provides a RESTful API to extract knowledge from audio and video content

Why is Clarify popping up on my list lately? There are a number of things that will cause an API related company to show up on my radar, but Clarify has several things going for it lately:

  • Branding Shift - Recently they migrated from being Op3nVoice, which I didn’t think wasn't that hard to spell, but I know that many people would have trouble with, to being Clarify—which is a cleaner brand.
  • Hypermedia - Clarify is an extremely well designed API which employs HAL, and hypermedia JSON format for al API responses.
  • SDK Writing Guide - They provide an SDK writing guide for anyone looking to develop SDKs for Clarify, making sure they are consistent from language to language.
  • Story on Helper Libraries - Clarify produced a great blog post called "SPOIL your Users with Great Helper Libraries", which I added to my curation, and stories around API management.

I’m tracking on 15 separate APIs as part of my voice API research, and 18 as part of my video API research. These are fast growing spaces, and the problem of delivering indexable meta data alongside audio video is only going to increase, something startups like Clarify is looking to provide an API driven solution for.

Now that @APIStrat in Chicago is over, I'm going to take the video from the conference, and run through Clarify, to get a feel for how the API works, and see first-hand the value it adds to my existing audio and video content.

Clarify is a well designed API, and now that they've found their footing with their new brand, I predict Clarify will be one of those high value APIs like Twilio and SendGrid, that we are all talking about, and showcasing when it comes to how to do API right.

Look for more stories on Clarify as I get time to process the @APIStrat content.

See The Full Blog Post

Video From The Hypermedia Panel At API-Craft In Detroit Last Month

I never properly wrapped up my experience at API-Craft last month, where I moderated a pretty important panel discussion on hypermedia with Mike Amundsen (@mamund), Mike Kelly (@mikekelly85) Steve Klabnik (@steveklabnik), Kevin Swiber (@kevinswiber), Jørn Wildt (@JornWildt), and Markus Lanthaler (@MarkusLanthaler). 

The discussion was pretty amazing, I will let you watch for yourself. The action actually starts right at about 30:00 minute mark, so there is a lot of dead space until then. 

Broadcast live streaming video on Ustream


Careful it is 3 hours of some pretty geeky talk, you might experience some hypermedia side effects. Seriously though, this is a pretty important video discussion about a very relevant, and often misunderstood part of API evolution. I highly recommend watching.

I'm just getting back down to this time period in my Evernote stack, so look for some more stories out of API Craft and hypermedia after rewatching this talk. Also stay tuned for upcoming stories from I Love APIs in San Francisco, #API360 Summit in Washington DC, and of course @APIStrat in Chicago at the end of September.

See The Full Blog Post

The Hypermedia API Debate: Sorry Reasonable Just Does Not Sell

I moderated a panel of hypermedia experts at API Craft in Detroit last week. One theme that dominated not just the panel, but was also pervasive in the conversation over the next two days of the API event, was how can the hypermedia space, improve its overall image, message, and potentially reach a wider audience, and maybe even converting some of the hypermedia skeptics, to hypermedia evangelists.

After a session at #APICraft, dedicated to understanding all the hypermedia hate, Mike Amundsen (@mamund) and I continued the conversation, where he stated: When it comes to hypermedia, and technology online, reasonable just doesn't sell.

This statement sums up my views of the current state of the hypermedia conversation. I went into the event expecting a very heated debate, filled with very intelligent, passionate, yet opinionated and hard-headed individuals. If you even lightly pay attention to the world of APIs, you probably have stumbled across the conversation between passionate REST practitioners (aka Restafarians), and the more recently the select group of hypermedia specialists—producing an image that is perceived by some as passionate, opinionated, and pushy, or even portrayed as being down right mean, nasty, delusional and confrontational by some.

What I saw on the hypermedia panel last Monday, and over the next two days at #APICraft, was anything but the popular image of REST and the hypermedia community. I don’t dismiss that some REST, and hypermedia practitioners can be rude, mean, and less than tolerant of those of us who don’t quite understand every detail, but this group of hypermedia leaders were anything but. They were humble, articulate, and eager to better understand the hypermedia approaches of their colleagues, and try to understand how to better get the message out to the larger public.

So where does this image come from? I think there are two camps, who are equally to blame: 1) The hypermedia pioneers 2) The hypermedia skeptics — the rest of us are just along for a ride on this hypermedia roller coaster.

First let’s look at from the hypermedia skeptic side:

  • One Client To Rule Them All - You often hear claims, whether true or not, that hypermedia pioneers claim if all APIs were hypermedia, we could have a single, intelligent client to rule them all, and do away with all of the crap we have now—think web browser.
  • Adds Unnecessary Complexity - Adding extra links, and payload to each response just adds more complexity, without any benefits to warrant the added work.
  • Too Lofty, Dreamy, and Still Academic - Many say that Hypermedia is just to big of a vision, and the hypermedia pioneers are too dreamy, and stuck in just an academic discussion—it won’t work in the real world.
  • Solution For All APIs - There are many claims that hypermedia is something that all API designers should follow, applying to APIs in all industries as a silver bullet style solution.
  • Will Prevent APIs From Breaking - When you use hypermedia, your APIs are completely protected from breakage, and your developers will never feel any pain from API versioning, and the evolution of your API.
  • Solves Discoverability - With each payload, you get instructions for what is next, so if you know an API endpoint, you should be able to find everything else from there.

Next let’s look at from the hypermedia pioneers side:

  • Haters Gonna Hate - It has nothing to do with Hypermedia being good or bad, haters gonna hate. There is nothing you can do.
  • They Don’t Care - Nobody even cares about learning new things like hypermedia, so there is no reason to even explain it to them.
  • They Don’t Need To Understand - Not everyone even needs to understand what hypermedia APIs are, they will just benefit from the results.
  • They Just Don’t Understand - Skeptics just haven’t taken the time to understand what APIs are, and would rather just remain ignorant.
  • Its OK to Not Be Perfect - Hypermedia makes it ok to not build your API 100% correctly the first time, allowing you to change it along the way.
  • Use Media Types - People don't read docs, we need to rely on media types help provide the information developers will need.
  • Give Us A Break - This shit is hard, and the hypermedia community is working hard, and taking risks to push APIs forward.

Beyond both the hypermedia pioneers, and the hypermedia skeptic camps, I think the main problem with the hypermedia conversation is as Mike said, "reasonable just doesn't sell”. I think this is the number one illness in the whole debate, that some bloggers feel the need to polarize any debate, sensationalize and use hyperbole at every turn. You can see this playing out in coverage of hypermedia, but also around other areas of the API space like API deprecation, where the argument was either APIs can go away at any moment, to the other end where you have to support APIs forever—not discussing the middle reality which would show there are plenty of APIs who handle deprecation very well, but year, that is boring, and really doesn't sell.

Let’s talk about what the hypermedia pioneers can do to shift the conversation:

  • Strong Implementations - The space needs for examples of hypermedia APIs in the wild, providing as much detail about the implementation, and hopefully a public API that they can actually go play with.
  • Storytelling - There needs to be much more storytelling about hypermedia. Not the technical narrative of your implementation, but a story of hypermedia APIs, and the solutions it delivers. Keep stories, short, inviting, compelling, and published often—we are all busy and don't always have the time to commit to reading longer pieces.
  • Patience - Have patience with the community, this is complex stuff, and it will take time for hypermedia to roll out, get the implementations we need to showcase the potential, the tooling and resources needed to support developers.
  • Friendly - Make sure and keep things friendly—this will go a long way in defusing the skeptics, and you never know you might convert them, one by one along the way.
  • Speak To Management - When you are telling stories, building case studies, and presenting on your work, make sure you speak to management level as well as to developers. It can be the leadership that carves out time for developers to learn about hypermedia, or possibly mandate that it should be part of an API design.

Let’s talk about what the hypermedia skeptics can do to shift the conversation:

  • Make The Time To Read - There is some great material out there about hypermedia, to get you up to speed if you can carve out the time. Sure, we need more examples of hypermedia in the wild, case studies, and tooling, but in the mean time, make sure and read as much as you can before casting judgement.
  • Make Sure And Listen - I heard some really compelling stories around how hypermedia works, and I bet if you take the time to listen to more of the conversation you might at least evolve your opinion of hypermedia.
  • Think Long Term - Hypermedia provides some long term benefits that are often overlooked in the short term concerns about time and resources needed to get up to speed with hypermedia, and actually implement as part of your API design.
  • Don’t Worry About What You Don’t Know - I feel like some of the trolling of hypermedia might be based upon insecurity about what one doesn’t understand. I have to admit I don’t fully grasp everything about hypermedia, but I see enough to grasp the long term potential, and know I should worker harder to close the gaps in my understanding.
  • Don’t Be Mean - I’ve seen some pretty harsh responses to what hypermedia pioneers are working on, and I think it would be easier to just walk away, rather than shitting on someones hard work. Hypermedia pioneers are putting a lot of time and energy into moving the space forward in positive ways.

Ultimately the ball is in the court of the hypermedia pioneers.There really is no reason that skeptics, or anyone else should care, until there is more examples, tooling, and stories around why hypermedia is worth the extra work in getting up to speed, and implementing as part of our APIs designs.

I see hypermedia at the same place, as REST was in 2010 when I started API Evangelist. I had witnessed first hand the solutions a RESTful API provided, and saw what was playing out in the public API space with Amazon, Twitter, and Twilio. As I continue to study the space I saw the RESTafarians arguing, shaming and generally making people feel stupid for not understanding HTTP, and fighting over exactly what REST was. It appeared to me that REST would suffer from the same image problems as the semantic web, and linked data.

The API space needed a friendlier layer, one that would help soften up some of the technical debates, and tell stories that would make all of this valuable knowledge more accessible—with this in mind, API Evangelist was born. I’m not saying I’m responsible for web APIs moving into the mainstream consciousness, it has taken all the valuable implementations available out there to do that, but I do know I’ve started some important conversations by working so hard to help everyone better understand the space.

After what I saw in Detroit last week, during the hypermedia panel I moderated, and over the following two days, I’m confident that with a little more storytelling we can shift the tone of this conversation in just a year or two. It won’t happen overnight, but I saw some really smart, hardworking folks who were very humble about their hypermedia work, and willing to admit there is a lot of work to be done, and eager to help the public to better understand the benefits hypermedia will bring to not just individual API operations, but the overall API space.

If I didn’t believe that hypermedia offered significant benefits, I wouldn’t be talking about it. In 2014 I’m seeing the hypermedia conversation move beyond just the API-Craft forum, beyond just academic discussion, and we are seeing some meaningful implementations of hypermedia in the wild. I will keep working to evolve my understanding and storytelling around hypermedia, while also working with the experts to generate more stories, and examples of their own work.

Update: I changed the word hater to skeptic (except in the haters gonna hate bullet), John Sheehan said I should use, which seems sensible, and following my own advice. Thanks John.

See The Full Blog Post

Getting Labeled A Hater On The Hypermedia Panel At API Craft

I’m still gathering all of my thoughts on the hypermedia media panel this last week at API Craft. I have an Evernote full of ideas, thoughts, and potential stories from the amazing API event this week in Detroit. First up is responding to the Twitter backchannel around being a hypermedia hater, and the panel I moderated on Monday between Mike Amundsen (@mamund), Mike Kelly (@mikekelly85), Steve Klabnik (@steveklabnik), Kevin Swiber (@kevinswiber), Jørn Wildt (@JornWildt), and Markus Lanthaler (@MarkusLanthaler).

After bringing the panelists up, giving them each 10 minutes to introduce themselves, I kicked off the discussion by calling out a Tweet from @JeremiahLee:

First, I called out @JeremiahLee because he happened to tweet right at the moment I was moderating the panel, and second because I thought his comment reflected the polarization of the conversation around hypermedia. I personally know @JeremiahLee, and I know he’s not a hater, he a super smart, and critical leader in the API conversation, but he Tweeted a controversial tweet, at the perfect moment, and I seized the opportunity. ;-)

Hypermedia hating was a central theme to the event in Detroit, and I have several stories planned, hoping to further explore the phenomena, and make suggestions for moving the conversation forward, and @JeremiahLee provided a little more explanation of himself, so let’s explore his position, and I'll add some commentary along the way:

Thank you so much for Tweeting this @JeremiahLee, it really did provide a great focal point for kicking off the panel, and made this topic be a pervasive part of the conversation across the next two days! ;-)

Very true, but you can when you call someone’s conversation about a proposed solution, 99% bullshit. ;-) Something I think is a hallmark of many of the hypermedia haters, which immediately makes it easy to label as such, from a single Tweet.

Spot on, and something the hypermedia has failed to do. I do see signs where the benefits are being demonstrated, and potentially outweigh the work involved, but they are poorly communicated. There is so much work to be done on educating people around what hypermedia even is, let alone demonstrating the solutions it provides, which will allow each person to individually assess whether it alleviates more pain then it creates, and is something they should consider.

Great feedback. I think this was heard loud and clear by the audience. They realize there is a lot of work to be done to increase the number hypermedia API implementations in the wild, which will result in better client tooling, which will also provide material for the stories and evidence you will need to satisfy this concern.

Another area that was discussed at the event. I think HAL provides a minimalist approach that fits this description, and I leave to each of the other hypermedia format designers to chime in on why their approach is preferred, and isn’t extraneous baggage. I will also spend some time better acquainting myself with each of the formats, and try to lend my own view. I think linking data, and establishing a common data vocabulary are great starting points for demonstrating hypermedia value to API providers and consumers, and we will have to build a case for each addition layer added on from there--lots of work to be done!

I agree, and we need to see stories of specific implementations, that demonstrate that more value is generated then pain, as I said above. I’d also urge you to look beyond just pain, and looking at the potential for establish new ways to express ourselves using APIs. I think hypermedia can provide very subtle, simple ways of expression that don’t impose a lot of overhead, but can make integration, and even the end-user experience much smoother, chipping off the rough edges of what we currently have, reducing pain incrementally as we go.

The conversations I heard over the three days of API Craft do not reflect the “bold claims” I hear of online. I did not hear talk of a perfect API client, or APIs that never break, and the other “magic” that is pointed at in online discussions. The conversations were very humble, realistic, and talked of the challenges, pitfalls, and acknowledging hypermedia is not a fit for all scenarios. While I’m sure there are some snake oil hypermedia practitioners who preach magic, but I’m thinking “magic” and “bullshit” are the terms used by folks who aren’t immersing themselves in the conversations around hypermedia, and will only change when there is more material to help onboard them, and demonstrate real world implementations, and the solutions they provide.

I’d have to put the term bulldozers in the same toolbox as bullshit, and magic. By no means do I see adding simple linking at the bottom of an API response as a bulldozer. I saw many layers to what hypermedia is, and I think calling it a bulldozer is speaking to the entire stack, not acknowledging providers can implement any part, and developers can also choose to use or ignore any part, as well.

I will explore more of these thoughts in future posts on hypermedia, but I wanted to respond specifically to @JeremiahLee thoughts. You do have some excellent points @JeremiahLee, and I think they were heard loud and clear, and reflect the conversation that happened throughout API Craft. I think for anyone who wants to refrain from being labeled a hater, when it comes to REST, hypermedia, or any other topic, should be cautious when using polarizing terminology, and encourage the community to produce more of the evidence you are requiring to make the leap--while also acknowledging their desire to pioneer into new areas, which is good for entire community.

I will do my part to continue producing stories about what hypermedia is, and provide more examples of where hypermedia is being applied. I’m paying attention to hypermedia in 2014, not because it is the latest trend, I’m paying attention to it because in my monitoring of the API space I’m seeing a significant amount of discussion around it beyond just the academic discussions on API Craft. I’m seeing an increased amount of blog posts, and examples of hypermedia being used in the wild.

Thanks for playing so nicely into the discussion on hypermedia at API Craft, Jeremiah. I think you are asking the right questions, I just want to help both sides of the discussion better understand how we can better set the tone for the conversation, so that things are more productive, and the whole community can move forward in a healthy way.

See The Full Blog Post

My Discussion Today With 6 Hypermedia Leaders At API-Craft in Detroit

I'm preparing for my hypermedia panel at API Craft Detroit today. The API Craft organizers have brought together one of the most important line-ups, when it comes to the hypermedia API discussion, that I've ever seen. To prepare for the discussion,  I've spent time profiling each of the panelist, to help me, and hopefully you, better understand who they are:

These six hypermedia leaders, spend their time discussing hypermeida on the API-Craft forum, but it isn't just talk, each of the panelsts have each also contributed their formats and tooling to the discussion, resulting in 9 separate hypermedia formats to consider:

To help guide the conversation, I've asked each panelists to give me two things that they want the audience at API Craft to walk away with:

  • adding hypermedia to an API is a way to improve the API's usability (@mamund)
  • the more hypermedia information in a response, the more stateless that response can be (@mamund)
  • Hypermedia allows us to go beyond CRUD-influenced API design, enabling a task-based message design consisting of current resource state and available transitions. This provides a richer interaction model between client and server. (@kevinswiber)
  • The best way to improve the state of the art is to see hypermedia applied to more use cases and have feedback shared publicly with the community. (@kevinswiber)
  • What are the metrics of success for your API? How do hypermedia designs contribute to or detract from those metrics? (@mikekelly85)
  • Is adding links to a response enough? (@MarkusLanthaler)
  • What are the benefits of adding HTTP method and payload encoding information to links - aka forms/actions for APIs? What are the problems? Is it worth it? (@JornWildt)
  • Are more complicated media types, that require more than an HTTP library and a JSON parser to deal with, moving away from the "simplicity" that has been driving web API adoption over SOAP? (@mikekelly85)
  • Does adding hypermedia really help if the data itself can't be understood without out-of-band knowledge? (@MarkusLanthaler)
  • What are the pros and cons of moving hypermedia controls to a separate, machine-readable document (API descriptions) compared to embedding them directly in resource representations? (@MarkusLanthaler)
  • How would an ideal hypermedia client library look like? (@MarkusLanthaler)
  • People often have a knee jerk reaction to dismiss hypermedia APIs as a complex approach to API design. What is your three sentence pitch to convince these people that it is not overkill, and in fact can be a simpler approach over time? (@MattMcLartyBC)

If you have any questions you'd like to have asked, I have the list on a Github repository dedicated to the event. You are welcome to do a pull request on the list, or leave as an issue for the repository, and I will consider including in the conversation. 

The panel kicks off today around 1PM (we may start late, as some panelists hit flight troubles), and the conversation is being live streamed via UStream.

See The Full Blog Post

Getting To Know Jørn Wildt For The API Craft 2014 Detroit Hypermedia Panel

I'm preparing for my hypermedia panel with Mike Amundsen (@mamund), Mike Kelly (@mikekelly85), Steve Klabnik (@steveklabnik), Kevin Swiber (@kevinswiber), Jørn Wildt (@JornWildt), and Markus Lanthaler (@MarkusLanthaler), at API Craft Detroit next week. I wanted to go into the panel with a snapshot, and at least a minimal understanding of each of the panelists. This is kind of an all-star panel of hypermedia experts, so I need to at least bump up my understanding of what they are contributing to the API space, and who they are, beyond what I know from my own interactions with these API leaders.

As I do with all of my research, I wanted to share my work with you, my reader. Next up is Jørn Wildt. I'm a fan of Jørn's conversations via API-Craft, but beyond that I know very little. I look forward to talking more at API Craft, and learning about his work through my research.

Here is the outline of my research into Jørn's work:

Jørn Wildt

Software developer with experience from web programming (C#, ASP.NET and PHP) - both web UI as well as RESTful web APIs, Windows desktop clients, SOA, asynchronous messaging, domain driven design, computer language design, compilers, formal verification. Some hobby experience with hardware, embedded systems and low level programming.

Title: Software developer at cBrain
Mission: Hard working father, coder by day, hacker by night, RC pilot when possible.



Mason is a JSON format for introducing hypermedia elements to classic JSON data representations. With Mason you get hypermedia elements for linking and modifying data, features for communicating to client developers and standardized error handling. Mason is built on JSON, reads JSON, writes JSON and generally fits well into a JSON based eco-system.




  • Google Group - https://groups.google.com/d/forum/mason-media-type

I'm not posting all of this information just so I can share my research, it is also because Jørn has contributed a lot of work to the space, and the wider world needs to understand his contributions.. While I learned a lot through this process, I will also use it as a reference for my panel at API Craft, and for other stories I write in the future.

I've already added Mason as a tools in my hypermedia API research. I could spend days going through this research, but I also have 2 ther hypermedia API experts to profile, so I'm going to move on to the others, and come back to my profile of Jørn in the future to continue my own hypermedia education.

See The Full Blog Post

Hypermedia Feels Like We Are Still Learning To Communicate With APIs

I’m looking through each of the worlds, of my hypermedia panelists, Mike Amundsen (@mamund), Mike Kelly (@mikekelly85), Steve Klabnik (@steveklabnik), Kevin Swiber (@kevinswiber), Jørn Wildt (@JornWildt), and Markus Lanthaler (@MarkusLanthaler), for API Craft tomorrow, reaquainting myself on what they bring to the hypermedia table, adding to my knowledge, and hopefully sharing some of the findings with you.

As I look through each of the hypermedia definitions, developed by my panelists, I keep feeling, that as API providers, there is still a lot of education that has to occur, to not just helping us better communicate with APIs, but also be more skilled at sharing and interacting around the resources we are making available via APIs.

I’ve been brushing up my knowledge on Collection+JSON, UBER, ALPS, HAL, Siren, Hydra, JSON-LD, json:api, Mason--9 spearate format that contribute to how we design our APIs.

When I think about the state of APIs, i see that we are barely using our words in our communication using APIs, what we say, and how we are saying it with our APIs, is still very crude, and unstructured. I feel like we are just toddlers, learning to use our words, sentences and playing nicely together. With the rich formats available to us, I feel that in 2014, I think we have to collectively get our butts to hypermeida school, and get educated—a lot of the work has been done for, we just need to get up to speed.

I see a handful of API providers employing hypermedia in their designs, but they are still few and far between.

See The Full Blog Post

Getting To Know Markus Lanthaler For The API Craft 2014 Detroit Hypermedia Panel

I'm preparing for my hypermedia panel with Mike Amundsen (@mamund), Mike Kelly (@mikekelly85), Steve Klabnik (@steveklabnik), Kevin Swiber (@kevinswiber), Jørn Wildt (@JornWildt), and Markus Lanthaler (@MarkusLanthaler), at API Craft Detroit next week. I wanted to go into the panel with a snapshot, and at least a minimal understanding of each of the panelists. This is kind of an all-star panel of hypermedia experts, so I need to at least bump up my understanding of what they are contributing to the API space, and who they are, beyond what I know from my own interactions with these API leaders.

As I do with all of my research, I wanted to share my work with you, my reader. Next up is Markus Lanthaler. I knew of JSON-LD from work I was doing in the federal government, around making government services available, before I knew Markus. I had the pleasure of meeting him when he spoke at API Strategy & Practice in Amsterdam, as well as share the stage with him in Germany at API Days

Here is the outline of my research into Markus's work:

Markus Lanthaler

Using JSON-LD, Hydra, and Schema.org to build awesome Web APIs

Title: Developer, Consultant, W3C Invited Expert
Mission: Working on JSON-LD and Hydra to make Web APIs more fun



JSON-LD is a lightweight Linked Data format. It is easy for humans to read and write.






Supporting JSON-LD:


  • JSON-LD NPM Package - A JSON-LD Processor and API implementation in JavaScript.


Hydra is an effort to simplify the development of interoperable, hypermedia-driven Web APIs. The two fundamental building blocks of Hydra are JSON‑LD and the Hydra Core Vocabulary.



  • HydraBundle - a bundle for Symfony2 to create Web APIs based on Hydra
  • HydraConsole - a generic API console for Hydra-powered Web APIs
  • HydraClient - a PHP client library to access Hydra-powered Web APIs
  • JsonLD - a JSON-LD processor implemented in PHP






I'm not posting all of this information just so I can share my research, it is also because Markus has an important vision of where we should take API design, and how we should be linking our most valuable data. While I learned a lot through this process, I will also use it as a reference for my panel at API Craft, and for other stories I write in the future.

I've already added Hydra and JSON-LD as a tools in my hypermedia API research. I could spend days going through this research, but I also have 2 ther hypermedia API experts to profile, so I'm going to move on to the others, and come back to my profile of Markus in the future to continue my own hypermedia education.


See The Full Blog Post

Getting To Know Kevin Swiber For The API Craft 2014 Detroit Hypermedia Panel

I'm preparing for my hypermedia panel with Mike Amundsen (@mamund), Mike Kelly (@mikekelly85), Steve Klabnik (@steveklabnik), Kevin Swiber (@kevinswiber), Jørn Wildt (@JornWildt), and Markus Lanthaler (@MarkusLanthaler), at API Craft Detroit next week. I wanted to go into the panel with a snapshot, and at least a minimal understanding of each of the panelists. This is kind of an all-star panel of hypermedia experts, so I need to at least bump up my understanding of what they are contributing to the API space, and who they are, beyond what I know from my own interactions with these API leaders.

As I do with all of my research, I wanted to share my work with you, my reader. Next up is Kevin Swiber. Kevin is one of the architects behind leading API provider Apigee, and has a great deal of experiencing in designing enterprise grade web APIs, contributing his own Siren format, as well as a wealth of white papers, books, and being a part of the API Craft movement.

Here is the outline of my research into Kevin's work:

Kevin Swiber

Open Source rebel. Enterprise survivor. Passionate technologist. Current projects: Siren Hypermedia Specification, Argo HTTP Server.

Title: Senior Product Architect & API Design Consultant
Mission: I like building things for APIs. Life is good. 

  • Twitter - https://twitter.com/kevinswiber
  • Github - https://github.com/kevinswiber
  • Stack Overflow - http://stackoverflow.com/users/119378/kevin-swiber


A hypermedia specification for representing entities.




Kevin produces some amazing content as part of is role at Apigee, and is responsible for many of the important conversations around APIs going on across the web, like API Craft forum, local meetups, and even this event in Detroit, by the same name.


  • Confreaks - http://www.confreaks.com/presenters/1347-kevin-swiber


  • Apigee - https://community.apigee.com/users/kevin-swiber


  • API Design: Third Edition - http://apigee.com/about/api-best-practices/api-design-third-edition


  • API-Craft - http://api-craft.org/

I'm not posting all of this information just so I can share my research, it is also because Kevin has a wealth of experience to contribute, and I want to better understand the role he plays, while also helping you understand along the way. While I learned a lot through this process, I will also use it as a reference for my panel at API Craft, and for other stories I write in the future.

I've already added Siren as a tools in my hypermedia API research. I could spend days going through this research, but I also have 2 ther hypermedia API experts to profile, so I'm going to move on to the others, and come back to my profile of Kevin in the future to continue my own hypermedia education.

See The Full Blog Post

Getting To Know Steve Klabnik For The API Craft 2014 Detroit Hypermedia Panel

I'm preparing for my hypermedia panel with Mike Amundsen (@mamund), Mike Kelly (@mikekelly85), Steve Klabnik (@steveklabnik), Kevin Swiber (@kevinswiber), Jørn Wildt (@JornWildt), and Markus Lanthaler (@MarkusLanthaler), at API Craft Detroit next week. I wanted to go into the panel with a snapshot, and at least a minimal understanding of each of the panelists. This is kind of an all-star panel of hypermedia experts, so I need to at least bump up my understanding of what they are contributing to the API space, and who they are, beyond what I know from my own interactions with these API leaders.

As I do with all of my research, I wanted to share my work with you, my reader. Next up is Steve Klabnik. I've known Steve for a while, and have had the pleasure of having him speak at API Strategy & Practice, as well as joined him speaking at API Days in Paris. I'm thankful for Steve's work on JSON-API, but I think that his other projects, and his consistent presence across the Twittersphere, and the intensity of his contributions to the Ruby on Rails community, is what stands out.

Here is the outline of my research into Steve’s work:

Steve Klabnik

I'm Steve Klabnik, and I've been a Rubyist for years now. I'm a Rails committer, instructor with Jumpstart Lab, and a prolific Open Source contributor. I think that the web is the best thing that mankind has ever built, and I care about it a lot. As the web becomes more and more programmable, we need to understand how our applications interact with the overall ecosystem, and build great services to power our shared future

Title: lim x → y f(x) = BwO
Mission: AXIOM 1: The war machine is exterior to the State apparatus. 

  • Website - https://www.steveklabnik.com/
  • Blog - http://words.steveklabnik.com/
  • Blog RSS - view-source:http://feeds.feedburner.com/steveklabnik/words
  • Twitter - https://twitter.com/steveklabnik
  • Github - https://github.com/steveklabnik
  • Instagram - http://instagram.com/steveklabnik
  • Stack Overflow - http://stackoverflow.com/users/24817/steve-klabnik

I consider Steve a part of the consciousness of the API space, and the larger "API Economy". I feel Steve's contributions go beyond JSON-API, and provide us a critical perspective, one that is not rooted in technology, but our collective self, working to understanding not just the how, but the why of all of this crazy shit.


A standard for building APIs in JSON, extracted from the JSON transport implicitly defined by Ember Data's REST adapter.



  • Rust for Rubyists - The classic first community tutorial to Rust - http://www.rustforrubyists.com/
  • Jumpstart Labes - Jumpstart Lab is a small team passionate about technical education. - http://jumpstartlab.com/team
  • Hackety Hack - Hackety Hack is an open source application that teaches individuals how to create software. - http://en.wikipedia.org/wiki/Hackety_Hack
  • Rails - http://contributors.rubyonrails.org/contributors/steve-klabnik/commits


  • Confreaks - http://www.confreaks.com/presenters/456-steve-klabnik-
  • Lanyrs - http://lanyrd.com/profile/steveklabnik/



  • Designing Hypermedia APIs - https://www.youtube.com/watch?v=g4sqydY3hHU


  • Designingg Hypermedia APIs - http://www.designinghypermediaapis.com/

I'm not posting all of this information just so I can share my research, it is also because Steve is a voice that the API space needs to hear, and I want to better understand the role he plays, while also helping you understand along the way. While I learned a lot through this process, I will also use it as a reference for my panel at API Craft, and for other stories I write in the future.

I've already added JSON:API as a tools in my hypermedia API research. I could spend days going through this research, but I also have 3 other hypermedia API experts to profile, so I'm going to move on to the others, and come back to my profile of Steve in the future to continue my own hypermedia education.


See The Full Blog Post

Getting To Know Mike Kelly For The API Craft 2014 Detroit Hypermedia Panel

I'm preparing for my hypermedia panel with Mike Amundsen (@mamund), Mike Kelly (@mikekelly85), Steve Klabnik (@steveklabnik), Kevin Swiber (@kevinswiber), Jørn Wildt (@JornWildt), and Markus Lanthaler (@MarkusLanthaler), at API Craft Detroit next week. I wanted to go into the panel with a snapshot, and at least a minimal understanding of each of the panelists. This is kind of an all-star panel of hypermedia experts, so I need to at least bump up my understanding of what they are contributing to the API space, and who they are, beyond what I know from my own interactions with these API leaders.

As I do with all of my research, I wanted to share my work with you, my reader. Next up is Mike Kelly. I'm been tracking on Mike's work around HAL for a while now, I wrote about Amazon using HAL for their AppStream API, a while back. I'm eager to learn more about HAL, and what it brings to the API design process, and how Mike, and HAL size up against the rest of the panelists, and their offerings.

Here is the outline of my research into Mike's work:

Mike Kelly

Mike Kelly is a software engineer from the UK. He runs an API consultancy helping companies design and build beautiful APIs that developers love.

Title: Web Engineer at Stateless Consulting
Mission: I like using technology to solve interesting problems.

Mike brings the Hypertext Application Language (HAL) format to the hypermedia discussion. He's been at it since summer of 2011, so he's been a pretty strong advocate in the space for some time, applying his mad skills that are polished at his consultancy Stateless.co. Let's take a quick look at HAL, and what resources I could find to support it.

HAL - Hypertext Application Language

HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API. Adopting HAL will make your API explorable, and its documentation easily discoverable from within the API itself. In short, it will make your API easier to work with and therefore more attractive to client developers. APIs that adopt HAL can be easily served and consumed using open source libraries available for most major programming languages. It's also simple enough that you can just deal with it as you would any other JSON.





I'm not posting all of this information just so I can share my research, it is also because Mike is a leader in the API space, and I want to better understand the role he plays, while also helping you understand along the way. While I learned a lot through this process, I will also use it as a reference for my panel at API Craft, and for other stories I write in the future.

I've already added HAL as a tools in my hypermedia API research. I could spend days going through this research, but I also have four other hypermedia API experts to profile, so I'm going to move on to the others, and come back to my profile of Mike Kelly in the future to continue my hypermedia education.

See The Full Blog Post

Getting To Know Mike Amundsen For The API Craft 2014 Detroit Hypermedia Panel

I'm preparing for my hypermedia panel with Mike Amundsen (@mamund), Mike Kelly (@mikekelly85), Steve Klabnik (@steveklabnik), Kevin Swiber (@kevinswiber), Jørn Wildt (@JornWildt), and Markus Lanthaler (@MarkusLanthaler), at API Craft Detroit next week. I wanted to go into the panel with a snapshot, and at least a minimal understanding of each of the panelists. This is kind of an all-star panel of hypermedia experts, so I need to at least bump up my understanding of what they are contributing to the API space, and who they are, beyond what I know from my own interactions with these API leaders.

As I do with all of my research, I wanted to share my work with you, my reader. So, first up is Mike Amundsen. I'm very aware of Mike's presence in the space, but after doing just a couple hours of refresh on what he's been up to, I'm blown away by the leadership he has brought to how we communicate with APIs. 

Let's dive in, here is the outline of my research into Mike's work:

Mike Amundsen

Title - Director of API Architecture, API Academy at CA Technologies
Mission - Improve the quality and usability of information on the Web.


  • we need to ely on hypermedia formats
  • focusing on high degree of shared understanding
  • significant contributions to API space with Collection+JSON, Uber, and ALPS
  • teaching us to communicate in a structured way

Mike brings a significant amount of work to the API sector. When you look at Mike's work, you realize how much time he has given to the sector. I picked three significant contribiutions to focus on for my panel, and ongoing research.


Collection+JSON is a JSON-based read/write hypermedia-type designed to support management and querying of simple collections.

Key Links:




The Uber message format is a minimal read/write hypermedia type designed to support simple state transfers and ad-hoc hypermedia-based transitions. This document describes both the XML and JSON variants of the format and provides guidelines for supporting Uber messages over the HTTP protocol.



  • Keep the message structure as lean as possible. 
  • Support all the H-Factors in hypermedia controls. 
  • Be compatible with multiple protocols (e.g. HTTP, CoAP, etc.) 
  • Maintain fidelity for more than one base message format (XML, JSON, etc.)



ALPS (Application-Level Profile Semantics)

The purpose of Application-Level Profile Semantics (ALPS) is to document the application-level semantics of a particular implementation. This is accomplished by describing elements of response representations for a target media type. For example identifying markup elements returned (i.e. semantic HTML ala Microformats) and state transitions (i.e. HTML.A and HTML.FORM elements) that advance the state of the current application.



  • Design a document format for describing hypermedia interfaces for use in public distributed network applications. 
  • Discover Web developers' common assumptions when building Web client and server applications. 
  • Explore the challenges of designing and implementing client and server applications for the Web that can independently evolve over time.





Beyond Collection+JSON, UBER, and ALPS, Mike is pretty accomplished when it comes to authoring books on the subject, speaking, and even producing his own event.




I'm not posting all of this information just so I can share my research, it is also because Mike is a leader in the API space, and I want to better understand the role he plays, while also helping you understand along the way. While I learned a lot through this process, I will also use it as a reference for my panel at API Craft, and for other stories I write in the future.

I will also be adding Collection+JSON, UBER, and ALPS as tools in my hypermedia API research. I could spend days going through this research, but I also have five other hypermedia API experts to profile, so I'm going to move on to the others, and come back to my profile of Mike Amundsen in the future to continue my hypermedia education.

See The Full Blog Post

State of Hypermedia Today @ API Craft In Detroit

I’m working with Brian Mulloy (@landlessness) of Apigee, to organize six of the leading hypermedia experts for a 2 hour panel discussion on the state of hypermedia, at API Craft, in Detroit, Michigan this month. I couldn't imagine a more distinguished panel of hypermedia experts, than this lineup:

The 2 hour panel is going to be broken into an hour of 10 minute presentations from each of the six panelists, followed by another hour of QA discussion between myself, the panelists, and the API Craft audience.

I’ve started a Github repository to gather thoughts for the discussion, from the panelists, and if you have anything you'd like me to discuss, feel free to submit an issue, and I'll consider including in the discussion.

See you in Detroit!

See The Full Blog Post



If you consider yourself an API designer in 2014, you should be familiar hypermedia, and how you can augment, and drive your API design for not just a better user experience (UX), but also a developer experience (DX).

As with REST, I won't be diving into the details of hypermedia design, there are plenty of resources available to teach about this, and proven examples of hypermedia used in the wild, that you can reverse engineer--my goal is to make sure you are aware of hypermedia, and its growing role in the API design process.

In 2014 I'm seeing a similiar uptick in hypermedia API deployments, to what I'm seeing with the overall API design space. I think hypermedia will emerge as a guiding principle in good API design, we just need the API design providers to work out the details of hypermedia integration, bake them into their API definition formats, and help API designers easily add hypermedia to their API desigin toolbox.

See The Full Blog Post

Help Developers Understand What To Do Next With Your API Response

There are numerous reasons for API designers to follow hypermedia patterns when crafting their internal, partner or publicly available APIs. One of the most fundamental reasons for offering hypermedia is to help developers understand what to do next, once receiving a response from your API.

Hypermedia APIs mimic the default characteristics of the web, and how you always know what do next with a web page, because there are many available links either in the form of navigation, in the body or footer. Reflecting this behavior, each hypermedia API resources comes with a set of related links giving developers clear actions to take once the response is received.

It can be easy to get lost in the numerous hypermedia debates online, not quite understanding all of the benefits of this fast growing API design pattern, but one clear reason is to help developers understand what to do next. Without clear instructions, developers can make obvious mistakes, misuse or misrepresent API resources, and be out of alignment with your own business goals in providing the API resource in the first place.

See The Full Blog Post

Hypermedia Adoption Will Not Be About The Perfect API Client

As I’m working to add yet another API example to my growing list of hypermedia APIs in the wild, I can't help but think about the long evolution of hypermedia, and how it will eventually become part of the mainstream API consciousness.

I first started following the often heated discussions around hypermedia a couple years ago as leading API technologists began discussing this significant evolution in API design. Hypermedia has numerous benefits and features, but one you often hear in discussions is that if we use hypermedia we can stop designing custom clients that consume APIs.

The logic is that if every API call comes bundled with URLs for discovering and navigating the resources that are made available via an API, clients can just use this as a blueprint for any app to API interactions. This became a fairly large argument between hypermedia architects and hypermedia haters, something that I think turned a lot of people off to the concept, forcing us to stick with many of the bad habits we already knew.

As I review these new hypermedia APIs, few of them are perfect by any hypermedia measurement, but they use the sensible portions of hypermedia discovery and navigation to deliver a better API experience for developers. I don't think API providers are doing it because of the perfect hypermedia vision we've heard articulated in the past, they are borrowing the pieces that make sense to them and that meet their goals.

Someday we may achieve a world where API clients aren't custom, with every application automatically knowing how to discover, interact, and navigate any API resource it will need. However I think in the currently reality, we will see hypermedia being adopted because it just makes sense as a next step for sensible API design, and this is how we should communicate it to curious API designers, looking to understand exactly what is this concept called hypermedia.

See The Full Blog Post

ReliefWeb Is Tackling The Worlds Biggest Problems Using APIs

I was introduced to the ReliefWeb API last week, which provides information including reports, jobs, training, countries, and source details on global crises and disasters going back to 1996.

The ReliefWeb API follows a trend of organizations realizing not just the potential of APIs for delivering content to mobile applications, but also the benefits of opening up publicly. As the site states:

The United Nations Office for the Coordination of Humanitarian Affairs (OCHA) originally built the ReliefWeb API to power a mobile version of the ReliefWeb website.

Since then they have normalized the interfaces for public consumption, hoping that “developers can build tools that increase exposure for valuable content and facilitate analysis for better decisions.”

The ReliefWeb API provides seven valuable API endpoints:

  • Discovery - Providing discovery, navigability and insight into other APIs.
  • Reports - Content API of updates, headlines and maps available on ReliefWeb.
  • Jobs - Job offers available on ReliefWeb.
  • Trainings - Training opportunities available via ReliefWeb.
  • Countries - Countries from Reliefweb.
  • Disasters - Disasters tracked on as part of ReliefWeb.
  • Sources - Sources of information available on ReliefWeb.

The design of the API is pretty well thought out, providing some common, as well as some forward thinking technical elements:

  • Documentation - Detailed information about all API endpoints, including content types, versions, data model, including full text and interactive version using Swagger.
  • Hypermedia - Control links facilitate paging, deep cross-linking of content allows navigating between related resources, and all resources can be reached by drilling down from the top level of the API at http://api.rwlabs.org.
  • Caching - Uses Cache-Control headers to point out how often ReliefWeb recommends checking for updates.

I started playing around making some calls and enjoyed the way the API flows, and excited about the potential. I do have some critique of the implementation, with the hope of influencing their roadmap.

Side Project
The API initiative has a very side project feel. Its under /help/ in the address, and I'd say 90% of the projects I’ve seen deployed in this way go away—this will affect developer perspective. While I understand most API projects are often underfunded side projects, you should work to hide this. Launch at developer.reliefweb.int and give the portal its own navigation, and make a link to developers area prominent in footer or header of main ReliefWeb site—instilling confidence in API consumers.

The API documentation is complete. It has all the relevant information, it just feels fragmented, and needs some UX love. The Swagger API docs could be made to be a little more beautiful, flowing and integrated with the rest of the docs. The age of link to interactive explorer is gone, your entire doc experience should be interactive.

Key Things Up
I love that I can just start playing with API, without registration, but I’d much rather have ReliefWeb in tune with how the API is being used, and including usage patterns into its roadmap and future API design. Requiring self-service registration and API key to use isn't going to lock up the data, it will allow you to better understand how endpoints are being consumed, bottlenecks, and common usage patterns. This will all go a long way to helping evolve the API roadmap and understand ReliefWeb API consumers.

Building Blocks
Much like I state above about it feeling like a side project, most of the essential API building blocks are there, but their are really fragmented. There are FAQs on multiple pages, docs spread across multiple pages, and support paths aren't super clear. Overall the portal and supporting building blocks just need some UX love to make sure it flows better for on boarding new developers, as well as supporting existing ones.

Looking Forward
It is always hard to critique new APIs from governmental or non-profit organizations, because I'm just happy to see any API come out the door. This means the iteration cycles start, and things will only get better (potentially).

I could recommend other building blocks like code samples, idea and application showcase and social elements like usage of Github and Twitter, but I know they are just getting going and these things will come.

Overall I’m excited about the potential around the ReliefWeb API, that the organization has seen the benefits of APIs in their own mobile strategy, but also understands the potential of opening up these resources to the public.

Seeing deployments like the ReliefWeb API remind me that we can truly tackle many of the big problems we face in the world, rather than many of the stupid, first world problem API solutions and applications we see out of Silicon Valley.

See The Full Blog Post

What Are Some Good Examples of Hypermedia APIs?

I'm increasing my coverage of hypermedia APIs in 2014, as we move from discussion to concrete hypermedia implementations in the wild. In support of this, there was a quick conversation on Twitter today regarding some good examples of hypermedia APIs, that I wanted to share with you.

Chris Metfcalf (@chrismetcalf) of Socrata asked:

Providing some much needed examples of hypermedia APIs in the wild. I haven't looked at the details of each implementation, but I trust Darrel's opinion, and will take a deeper look under the hood when I have more time.

It is nice to have three clear examples of hypermedia APIs to showcase:

A hypermedia example from the world of commerce, providing an example that fits nicely into the API economy.
An interesting approach to using hypermedia APIs for discovering and managing your family history.
An enteprise example of hypermdia APIs from the content collaboration platform huddle. 
Amazon AppStream REST API
The Amazon AppStream web service provides APIs you can call to manage applications hosted on Amazon AppStream and to manage client sessions connecting to those applications.
Our platform makes searching AV files simple for developers to integrate into their applications. This means the valuable mindspace and the time of developers can be employed building new and better services that use the information locked up in existing and growing AV libraries. In other words Clarify connects your AV files with their potential.
Microsoft Lync Web Developer
Microsoft’s Unified Communications Web API (UCWA) is the Next Generation Platform for Mobile and Web Development.
One of the key features of the PayPal REST API is HATEOAS (Hypertext As The Engine Of Application State).
VerticalResponse's API generally follows the REST model, based on the principles behind HTTP.

I'll keep tracking on other examples of hypermdia APIs in the wild, and see if we can't begin shedding light on some of the better implementations out there, and see about getting some of these providers to discuss their API developer strategies at @APIStrat or @APIdaysGlobal. If you know of any other examples, please let me know.

UPDATED: 04/17/2014 I added Amazon AppStream REST API, suggested in the Twitter stream by @zdne of @apiaryio.
UPDATED: 04/18/2014 I added OP3Nvoice and Lync Web Developer suggested in the Twitter stream by @darrel_miller.
UPDATED: 05/01/2014 I added Paypal Developer suggested by Pedros Santos on API Craft.
UPDATED: 05/01/2014 I added VerticalResponse suggested by Rob Zazueta (@rzazueta) on API Craft.
UPDATED: 09/29/2014 I updated Op3nVoice to be Clarify and reflect their new branding.

See The Full Blog Post

16 Areas Of My Core API Research

When I first started API Evangelist, I wanted to better understand the business of APIs, which really focused on API management. Over the course of four years, the list of companies delivering API management services has expanded with new entrants, an evolved with acquisitions of some of the major players. Visit my API management research site for more news, companies, tools and analysis from this part of API operations.

API Management

In 2011, people would always ask me, which API management company will help you with deployment? For a while, the answer was none of them, but this soon changed with new players emerging, and expanding of services from existing providers. To help me understand the expanding API lifecycle I started two new separate research areas:

API Design
API Deployment

Once you design, deploy your API, and you get a management plan in place, you have to start looking at how you are going to make money and get the word out. In an effort to better understand the business of APIs, I setup research sites for researching the monetizationand evangelizing of APIs:

API Evangelism
API Monetization

As the API space has matured, I started seeing that I would have to pay better attention to not just providing APIs, but also better track on the consumption of APIs. With this in mind I start looking into how APIs are discovered and what service and tools developers are using when integrating with APIs:

API Discovery
API Integration

While shifting my gaze to what developers are up to when building applications using APIs, I couldn’t help but notice the rapidly expanding world of backend as a service, often called BaaS:

Backend as a Service (BaaS)

As I watch the space, I carefully tag interesting news, companies, services and tools that have an API focus, or influence the API sector in any way. Four areas I think are the fastest growing, and hold the most potential are:


In 2013, I saw also saw a conversation grow around an approach to designing APIs, called hypermedia. Last year things moved beyond just academic discussion around designing hypermedia APIs, to actual rubber meeting the road with companies deploying well designed hypermedia APIs. In January I decided that it was time to regularly track on what is going on in the hypermedia conversation:.

Hypermedia APIs

After that there are three areas that come up regularly in monitoring of the space, and pieces of the API puzzle that I don’t just think are important to API providers and consumers, they are areas I actively engage in:

Single Page Apps (SPA)

There are other research projects I have going on, but these area reflect the core of my API monitoring and research. They each live as separate Github repositories, accessible through Github pages. I publish news, companies, tools, and my analysis on a regular basis. I use them for my own education, and I hope you can find useful as well.

See The Full Blog Post

The 15 Sessions At API Strategy And Practice in Amsterdam

I am getting psyched going through the schedule lineup of 15 sessions at API Strategy & Practice in Amsterdam. In planning the session outline, Steve, Vanessa and I listened to what the #APIStrat audience asked for after New York and San Francisco, which was more of the deep technical, as well as a balance of the business and politics of APIs.

I think our lineup delivers on this, which we've broken up into three tracks:

API Provider

  • Design and Development
  • Service Descriptions
  • Hypermedia APIs
  • API Marketing & Developer Communities
  • Hardware and Internet of Things (IOT)

API By Industry

  • Media, Music and Audio APIs
  • Civic APIs
  • Enterprise APis
  • APIs in Financial Services
  • Community APIs

API Consumer

  • Discovery and Trust
  • Security and Testing
  • High Scalability
  • API Based App Development
  • Business Models

This lineup of sessions represent what we are seeing across the API space, with API design coming front and center, to hypermedia moving beyond an academic discussion and actually getting traction. That is what API Strategy & Practice is about, providing a venue to have discussions about the areas that are impacting the industry.

The best thing is, this is just the session lineup, we still have workshops, keynotes, fireside chats and panels.

See The Full Blog Post