API World 2013 Conference & Festival

We'll share our experiences building a hypermedia API for Comcast's
multi-platform television experiences. During this process, we found that
both client and server developers passed through different stages in their
understanding and use of hypermedia (including a fair amount of actual
grief). We'll describe our real-life journey here, including all these
pain points. Initially, our API team, who had experience with hypermedia
APIs, approached our client developers with this concept, and ran into a
healthy dose of Resistance. "What do you mean, we can't have JSON?" With
deadlines looming, the teams eventually passed into Bargaining, trying as
hard as possible to simultaneously (depending on the point of view) avoid
or adhere to a lot of the hypermedia principles. Disillusionment followed,
as both clients and API developers were forced to endure naive self-link
following and bloated semantic payloads, wondering whether the hypermedia
fight was actually worth fighting. However, as our clients and API
developers continued to work closely together, API interactions began to
look more like state transitions, and protocol logic began to divorce
itself from domain knowledge. Things began to work a little more smoothly,
gaining speed, until a final stage began to emerge: Productivity. Through
the myriad lessons learned, compromises reached, tools developed, and a
deeper respect and understanding borne of a struggle mutually fought, we
have hypermedia success stories to share. These include fabled ten-line
java integrations, iOS developers wondering whether XHTML might be a
sensible approach for APIs, and diverse device platforms using a single
API in a way that makes sense to each of them.