This website is currently dormant!

API Definitions News

These are the news items I've curated in my monitoring of the API space that have some relevance to the API definition conversation and I wanted to include in my research. I'm using all of these links to better understand how the space is defining not just their APIs, but their schema, and other moving parts of their API operations.

TVMaze Uses HAL For Their API Media Type

One of the layers of the API universe where I come across an increased number Hypermedia APIs is in the movie, television, and entertainment space. Where having a more flowing API experience makes a lot of sense, and the extra investment in link relations will pay off. One example of this I recently came across was over at TVMaze, who has a pretty robust hypermedia API, where they opted for using HAL as their media type.

Like any good hypermedia should, TVMaze begins with its root URL:, and provides a robust set of endpoints from there:






The TVMaze API isn’t an overly complex hypermedia API. I think it is simple, elegant, and shows how you can use link relations to establish a more meaningful experience for API consumers. Allowing you to navigate the large, ever-changing catalog of television shows, allowing the API client to do the heavy lifting of navigating the shows, schedules, and people involved with each production.

There hasn’t been enough showcasing of the hypermedia APIs available out there. Usually once a year I remember to give the subject some attention, or when I come across interesting ones like TVMaze. Hypermedia isn’t just an academic idea anymore, and is something that has gotten traction in a number of sectors, and I keep seeing signs of growth and adoption. I don’t think it will be the API solution most hypermedia believers envisioned it, but I do think it is a viable tool in our API toolbox, and for the right projects it makes a lot of sense.

Delivering Large Api Responses As Efficiently As Possible

404: Not Found

I Am Talking About Jekyll As A Hypermedia Client At APIStrat in Portland OR Next Week

Static website, and headless CMS approaches to providing API driven solutions have grown in popularity in recent years. Jekyll has been leading the charge when it comes to static website deployment, partly due to Github being behind the project, and their adoption for Github Pages. I’ve been pushing forward a new approach to using Jekyll as a hypermedia client to help deliver some of my API training and curriculum, and as part of this work I’m giving a talk at APISTrat next week on the concept. APIStrat is a great forum for this kind of project, helping me think through things in the form of a talk, the opportunity to share with an audience, and get immediate feedback on its viability, which I can then use to push forward my thinking on this aspect of my API work.

If you aren’t familiar with Jekyll, I recommend spending some time reading about it, and even implementing a simple site using Github Pages. I have multiple non-developers in my life who I’ve introduced to Jekyll, and it has made a significant impact on the way they do their work. Even if you do know about Jekyll, additionally I recommend spending time learning more about the underscore data folder, and the concept of Jekyll collections. Every Jekyll site has its default data collection, and the opportunity to create any additional collection, using any name you desire. Within these folders you can publish static CSV, JSON, and YAML data files, using any schema you desire. All of these data collections then become available for referencing through the static Jekyll website or application.

All of this functionality is native Jekyll. Nothing revelatory from me. What I’m looking to push things forward around is what happens when the data collections are using a hypermedia media type. I’m using Siren, which allows me to publish structured data collections, complete with links that define a specific experience across the data and content stored within collections. Next piece of the puzzle involves leveraging Jekyll and its use of Liquid as a hypermedia client, allowing me to build resilient websites and applications that are data driven, but can also evolve and change without breaking. All I do is update the static data behind, with minor revisions to the client–all using Github’s API or Git infrastructure.

I’ve found Jekyll’s data features to be infinitely beneficial, and is something I use to run my entire network of sites on. Adding the hypermedia layer is allowing me to push forward the storytelling experience around my API research and curriculum. The first dimension I find interesting, is that I can publish updates to the data for each project without breaking the client–classic hypermedia benefits. However, additionally, I can publish data and changes using Github workflows, and because every application runs as independent Github Pages driven website, it can stay in sync with updates via commits, or stay completely independent and never receiving any changes, which will also introduce another dimension of client stability, which is also so hypermedia.

I am still in the beta phase of evolving some of my API projects to use this approach. I’m pioneering this work using my API design curriculum. I’ll be publishing an instance as part ofmy session at APIStrat in Portland, OR next week. I’ll make sure I cover some of the Jekyll and Github basics for people in the audience who aren’t familiar with these areas. Then I’ll walk through how I’m using the Jekyll collections, includes, and the Liquid syntax to behave as a hypermedia client for my Siren data collections. All my talks live on Github, so if you can’t make it you can still follow along with my work. However, if you are going to be in Portland next week, make sure you come by and give a listen to my talk–I’d love to get your feedback on the concept.

Using Jekyll As A Hypermedia Client

I am picking up some of my past work, so that I can move forward in a new way. A while ago, I began working on my subway map API to help me articulate aspects of the API lifecycle, and provide a “vehicle” for helping folks explore some often complex API concepts, in a way that would incrementally introduce them to new ideas. I used the subway map as an analogy because it has been historically used to help folks understand complex systems, and help them navigate it, even if they don’t fully understand everything about it. I gave a talk at @APIStrat in Austin, TX on this subject, but something I haven’t moved forward in over a year.

My new approach to using the subway map model is still using hypermedia (Siren), but I’m not wanting a single API to control the data for every client. I’m looking to develop a static, federated approach to delivering subway map experience. I want to be able to quickly publish a common map, but then be able evolve them independently, designed for specific implementations and use cases. Since I’m so Jekyll and Github centered in how I deliver projects, I’m looking for a way to do this in a static way, that can be forked. So, I got to work on publishing Siren YAML to Github, and seeing if it is possible to use Liquid and HTML as the client. Again, I want this to be static. All this could easily be building this in JavaScript, but I want things static and forkable.

For my proof of concept I published 15 “stops” along the request “line” for my API design “area”. I don’t have the visual elements present for this functionality, as I just wanted to prove that I could use Liquid and HTML for a hypermedia client, using Siren YAML published to Github. I was forced to add a layout: property to my Siren schema, which is probably heresy to couple to the client in this way, but it is something I’m willing to take a hit for. Everything else is pure Siren. While there is still a lot more work to be done, I was able to expand the boundaries of how I use hypermedia and Jekyll, in a single proof of concept–telling me the idea is worth moving forward with.

To make things work I published a set of Siren hypermedia YAML documents (I know Kevin, I’m making you cringe, but bear with me) to a Jekyll collection called _design. Then I have three Jekyll client templates in the _layouts folder, called area, lines, and stops. My client isn’t that sophisticated for this proof of concept, but I am able to easily work with the entities, properties, and links in Liquid effectively. I’m just wanting to show that I can take my YAML to the next level, and expand my link relations beyond just next and previous that is often associated with Jekyll _posts, opening up the entire IANA link relations catalog of options, plus anything custom I will need (ie. area, line, stop). It doesn’t look like much, but it provides a pretty compelling example of using Jekyll and Github to deliver complex content that will be changing regularly in a static way.

The viewable side of my hypermedia Jekyll subway map API client doesn’t look that attractive yet, but it provides the basic next/previous functionality, as well links back to the area, or line of coverage. This is just the first two types of experience I’m looking to provide as people explore. I will be introducing transfers, help, and other supporting link relations between the content being made available. Eventually the home page of these projects will be a subway map with accompanying key, and then you choose the area, explore lines, and get off on any stop you desire. It’s just a start, but I feel my Jekyll hypermedia client proof of concept is a success, and I’ll get to work on publishing more content, and adding the visual elements that make it truly a subway map experience.

Always Being Prepared For An Api Future That May Never Come

404: Not Found

Some Thoughts On OpenAPI Not Being The Solution

I get regular waves of folks who chime in anytime I push on one of the hot-button topics on my site like hypermedia and OpenAPI. I have a couple of messages in my inbox regarding some recent stories I’ve done about OpenAPI recently, and how it isn’t sustainable, and we should be putting hypermedia practices to work. I’m still working on my responses, but I wanted to think through some of my thoughts here on the blog before I respond–I like to simmer on these things, releasing the emotional exhaust before I respond.

When it comes to the arguments from the hypermedia folks, the short answer is that I agree. I think many of the APIs I’m seeing designed using OpenAPI would benefit from some hypermedia patterns. However, there is such a big gap between where people are, and where we need to be for hypermedia to become the default, and getting people there is easier said than done. I view OpenAPI as a scaffolding or bridge to transport API designers, developers, and architects at scale from where we are, to where we need to be–at scale.

I wish I could snap my fingers and everyone understood how the web works and understood the pros and cons of each of the leading hypermedia types. Many developers do not even understand how the web works. Hell, I’m still learning new things every day, and I’ve been doing this full time for seven years. Most developers still do not even properly include and use HTTP status codes in their simple API designs, let alone understand the intricate relationship possibilities between their resources, and the clients that will be consuming them. Think about it, as developer, I don’t even have time, budget or care to articulate the details of why a response failed, and you expect that I have the time, budget, are care about link relations, and the evolution of the clients build on top of my APIs? Really?

I get it. You want everyone to see the world like you do. You are seeing us headed down a bad road, and want to do something about it. So do I. I’m doing something about it full time, telling stories about hypermedia APIs that exist out there, and even crafting my own hypermedia implementations, and telling the story around them. What are you doing to help equip folks, and educate them about best practices? I think once you hit the road doing this type of storytelling in a sustained way, you will see things differently, and begin to see how much investment we need in basic web literacy–something the OpenAPI spec is helping break down for folks, and providing them with a bridge to incrementally get from where they are at, to where they need to be.

Folks need to learn about consistent design patterns for their requests and responses. Think about getting their schema house in order. Think through content negotiation in a consistent way. Be able to see plainly that they only use three HTTP status codes 200, 404, and 500. OpenAPI provides a scaffolding for API developers to begin thinking about design, learn how the web works, and begin to share and communicate around what they’ve learned using a common language. It also allows them to learn from other API designers who are further along in their journey or just have had success with a single API pattern.

For you (the hypermedia guru), OpenAPI is redundant, meaningless, and unnecessary. For many others, it provides them with a healthy blueprint to follow and allows you to be spoon fed web literacy, and good API design practices in the increments your daily job, and current budget allows. Few API practitioners have the luxury of immersing them in deep thought about the architectural styles and the design of network-based software architectures or wading through W3C standards. They just need to get their job done, and the API deployed, with very little time for much else.

It is up to us leaders in the space to help provide them with the knowledge they’ll need. Not just in book format. Not everyone learns this way. We need to also point out the existing healthy patterns in use already. We need to invest in more blueprints, prototypes, and working examples of good API design. I think my default response for folks who tell me that OpenAPI isn’t a solution will be to ask them to send me a link to all the working examples and stories of the future they envision. I think until you’ve paid your dues in this area, you won’t see how hard it is to educate the masses and actually get folks headed in the right direction at scale.

I often get frustrated with the speed at which things move when I’m purely looking at things from what I want and what I know and understand. However, when I step back and think about what it will truly take to get the masses of developers and business users on-boarded with the API economy–the OpenAPI specification makes a lot more sense as a scaffolding for helping us get where we need. Oh, and also I watch Darrel Miller (@darrel_miller) push on the specification on a daily basis, and I know things are going to be ok.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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 -

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.

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.

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


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 -
  • Github -
  • Stack Overflow -


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 -


  • Apigee -


  • API Design: Third Edition -


  • API-Craft -

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.

If you think there is a link I should have listed here feel free to tweet it at me, or submit as a Github issue. Even though I do this full time, I'm still a one person show, and I miss quite a bit, and depend on my network to help me know what is going on.