Designing Hypermedia APIs

LA RubyConf 2012

by Steve Klabnik

In the presentation titled "Designing Hypermedia APIs," Steve Klabnik discusses the concept of designing APIs that genuinely utilize the web's capabilities, focusing on hypermedia. Klabnik expresses that while Rails popularized REST for developers, there is a significant disconnect between how REST is commonly understood and its true essence. He introduces the concept of hypermedia APIs as a step forward from traditional REST, which he sees as limited.

Key points of the presentation include:

- Principle of Lifelong Learning: Klabnik emphasizes his journey of exploring what REST truly represents and the importance of continuous learning in the field of software development.

- Definition of REST versus Hypermedia: He clarifies that when he references REST, he means the simplified version understood in the Rails community rather than true REST principles. He asserts that current practices have led to a misunderstanding of what REST entails, largely differentiating it from hypermedia, which incorporates links between resources to guide navigation.

- Architectural Styles: Klabnik outlines four major architectural styles for APIs: RPC (Remote Procedure Calls), XML, REST, and finally hypermedia APIs, explaining that while all serve a similar purpose, hypermedia offers a structured approach through connected resources.

- Key Components of Hypermedia APIs: He highlights that a hypermedia API uses HTTP, MIME types, and hypermedia formats, playing a significant role in creating interactions between various resources and guiding users through a business process.

- Designing a Hypermedia API: Klabnik discusses the five-step process for designing these APIs, emphasizing the need to evaluate business processes, create state machines, evaluate media type needs, build the API, and implement results effectively. He illustrates this with an example of a website that needed a hypermedia-driven API, showcasing how links can enhance user experience and navigation.

- Conclusion and Future Work: Klabnik expresses his enthusiasm for these principles and mentioned he is working on a book titled 'Get Some REST' to delve deeper into the ideas discussed. He invites the audience to stay updated on his work and acknowledges the resources available at Jumpstart Lab as valuable for learners.

Overall, Klabnik's talk encourages developers to move beyond traditional REST practices and adopt a hypermedia approach, enhancing API usability and coherence, while also advocating for better coding practices in the field of Ruby and Rails development.

00:00:00.840 Foreign

00:00:24.680 I'm Steve, and apparently my slides are a little long that way, but I don't have too much out there, so it should be okay. Today I want to talk to you about designing hypermedia APIs.

00:00:41.260 I hack on Hackity Hack, which is the best way for people who don't know programming to learn the basics of programming. It's a desktop app for Mac, Windows, and Linux that allows you to go from knowing nothing to knowing something. That's why I spend most of my time on that when I'm not working on other educational stuff.

00:00:52.980 I teach classes with Jeff at Jumpstart Lab. Thanks for attending. We teach the best Ruby and Rails classes in the world. One day I went searching for the meaning of how to make APIs fit on the screen, also known as REST. Ultimately, this presentation is a story, a story about this journey that I've been on.

00:01:11.700 You can think of me as someone from our community who wandered off into the desert and came back stumbling into town, hair all crazy and half chopped off, covered in dirt. You're like, 'What happened to you?' And I'm like, 'Dude, I saw the most insane thing out in the middle of the wilderness, and I have to tell you about it. It's going to change your life.'

00:01:36.479 I have a principle of lifelong learning, so I'm always trying to learn something new. I file away things I'd like to learn in the future, and then when I have time, I go investigate them. I often see people online say things like, 'Oh, that's not actually REST.' And after hearing this two or three times, I sort of file away or check on this idea and see if these people are right or not.

00:01:59.939 Eventually, I got bored one day, and I saw someone say, 'Let me find out what this actual REST thing is like.' So this is that story, and I want to share with you what I have discovered about the true nature of REST. The first thing I want to tell you is that REST is over. I don't know if you've seen Portlandia or not, but basically the first thing about real REST is that there's sort of this in-essence movement among the RESTarians, as we call ourselves, to basically give up the term REST.

00:02:36.780 So in the rest of this presentation, when I say REST, I mean what Rails thinks REST is and what you all think REST is right now, not what REST actually is in a real sense. Because when you're involved in social justice movements, there's this idea that you shouldn't call people good or bad protesters. Instead, you should be talking about your actual mission and why waste time discussing what's happening on the street.

00:03:06.120 With REST, we have this message of how to build APIs in a scalable, long-lasting, and flexible way, so we shouldn't be squabbling over terminology. That's counterproductive and detracts from how to actually build APIs in a long-lasting way. So we're dropping REST; it's done. Whatever Twitter and those people have in their fake REST APIs is fine, and we're going to move on to something else. Remember that throughout this talk, I might say REST a couple of times unless I add a disclaimer, but I'll primarily discuss the Rails REST model that isn't actually REST.

00:03:49.980 Instead, we're calling them hypermedia APIs. There's a very specific reason for this that I will get into later. The first book by O'Reilly that was published recently is called 'Building Hypermedia APIs with HTML5 and Node.' Node is irrelevant to the content of the book, but if you're interested in real REST, you should buy it by a friend of mine. It's awesome. Hypermedia APIs are what I'm here to explain to you how to build and why they're awesome.

00:04:20.760 At the end of this slide is 'Designing Hypermedia APIs.' This is three words, and you need to know all three of them to understand my talk. I will explain it to you backwards. We're going to start with APIs, then move into what hypermedia is, and finally, discuss how to design a hypermedia API.

00:04:43.419 You might be thinking, 'Oh man, I already know what APIs are,' but I doubt it. There are four major architectural styles for APIs. An architectural style is similar to styles used in buildings or paintings, which categorize various designs. For example, there's no RFC 2100 that tells you what impressionist paintings are. You know an impressionist painting when you see it because it has certain characteristics.

00:05:09.540 For APIs, the first style is RPC or Remote Procedure Calls. Here's an example of making an API call to JSON RPC. There's also XML RPC. The idea is that you post a method name and parameters to an endpoint, and you get some result back. It's basically a method call over the Internet, very much like C programming: call this function and get data back. It's simple and very understandable, making it easy to work with.

00:05:43.740 The next style, XML, stands for Simple Object Access Protocol. The basic idea is that you serialize objects, send them over the wire, and unserialize them on the other side. It represents transferring objects from procedural programming, like RPC, to object-oriented programming. From an architectural perspective, you're essentially doing the same thing.

00:06:15.720 REST works by taking HTTP verbs, like GET, PUT, POST, DELETE, and using those to manipulate resources. It is structurally identical to RPC but uses multiple endpoints. So, for example, if I call POST to /posts or POST to /articles, it's the same as sending a create post or create article method call. It's essentially the same process, just implemented differently.

00:07:02.520 While there are multiple endpoints with REST, this gives you flexibility, such as using readable URLs. I would much rather work with the REST style than the others. However, this does not mean I am denigrating it entirely; the current API infrastructure is functional and mostly effective.

00:07:31.260 Lastly, there's hypermedia, meaning you encode hyperlinks into responses in a specific hypermedia format. When you request it, the API returns links to other resources; this helps guide you through a business process without needing to know all the resources' locations. Hypertext is a key element in application states. All of your resources must be connected, and the links are crucial.

00:08:25.620 That's what separates a hypermedia API from the Rails style of doing things: the web of resources connected through links. The main reason why Rails is not real REST is that you can't provide links to other stuff in your representation unless you follow a specific approach. Hypermedia APIs link resources, assisting users in navigating while storing essential contextual information.

00:08:55.920 To recap, three styles are as follows: RPC, Remote Procedure Calls, involve calling methods over the internet. REST is RPC with multiple endpoints for every resource. Lastly, hypermedia focuses on using hypermedia formats and links to create a connected web of state machines that you're working with. To understand hypermedia fully, you need to grasp what hypertext is.

00:09:31.140 Hypertext refers to text displayed on a computer with references or hyperlinks to other text objects. It was coined by Ted Nelson long ago. Hypermedia extends hypertext to all media types. Both terms can be used interchangeably today, but it's important to understand that we care about more than just plain text. Media types, also known as MIME types, define the specifications of the content being transmitted.

00:10:05.280 When we use a media type, we identify how to interpret and process documents. For example, when transferring JSON, you use the application/json MIME type. If we mislabel the type, the receiver might not be able to parse it correctly. Let's move on to hypermedia APIs and discuss what they entail.

00:11:05.520 A hypermedia API consists of three elements: HTTP, MIME, and specifically hypermedia MIME types. HTTP addresses the transmission of data, while MIME describes the structure of the data being sent. Hypermedia is the third element, emphasizing the need for links to other resources in your MIME types.

00:11:25.940 Using HTTP is vital because it supports many needs without additional work. While we may invent other protocols in the future, currently, HTTP is our best option. REST, being a stateless protocol, must maintain the application's state via hyperlinks. This point is what makes REST a limited name for our work in hypermedia APIs.

00:12:08.820 When we use HTTP properly, we get all the necessary supporting elements for building our APIs, which is a great advantage. Now, let's shift to actually designing hypermedia APIs. The process comprises five steps, along with an example.

00:12:50.820 First, evaluate your business processes to determine how your API should function. Next, create a state machine representing these processes and how they interconnect. Then, assess the media type needs for your application and build those media types accordingly.

00:13:39.300 Finally, implement the API based on the gathered information. For example, a friend of mine, Jamie Ernesta, developed a website called w3c.love.com, which checks websites for valid HTML. He wanted to create an API, and I assisted him by reviewing the proposed structure.

00:14:36.120 Initially, the API was standard with a GET request to /api/v1/sitemaps/check that accepted a URI. It returned typical JSON responses containing validation data. The existing process followed REST patterns but lacked hypermedia elements, so I suggested incorporating those aspects to enhance it.

00:15:05.760 To convert it into a hypermedia-driven API, we needed to define how we would interact with the API using forms, starting with how to follow links to process the sitemap API. This step required considering how many parameters we would pass and what formats we would use.

00:16:08.520 The next step requires us to use hypermedia to guide users through the process. We create an API that not only serves data but also includes links for further actions. The structure of our API would reflect the logical flow while maintaining a focus on user experience.

00:17:24.540 As we develop our API, we explore how to implement the media types and hypermedia links to facilitate state transitions. Each response should include these links, emphasizing the connections between resources. Diving into implementing the API, we research the specific media types we need.

00:18:25.740 During this design process, we use custom media types to specify how clients should interact with our APIs. These media types reflect the attributes and operations relevant to the application, promoting a better understanding for developers and clients alike.

00:19:03.900 As we finalize the implementation, we ensure all responses include meaningful links to facilitate navigation and to enrich the user experience. This approach encourages exploration, enabling users to understand the rationale behind the API's functionalities.

00:20:03.180 By adhering to these principles and integrating hypermedia with robust design, we can effectively build APIs that improve usability and coherence. Moving forward, we focus on these patterns to enhance our coding practices and foster better interactions within our projects.

00:20:58.980 I'm excited to share that I am working on a book that dives deeper into these topics. Although I intended to release a beta version today, unforeseen circumstances delayed my progress. Within a week, I plan to release the beta version of 'Get Some REST,' where I explore these ideas in much greater depth.

00:22:06.120 If you're interested in learning more, you can visit the website getsome.rest. Just enter your email, and I'll keep you updated on the book's progress. Again, I'm Steve Klabnik; thank you for listening, and I look forward to answering any questions you may have.

00:22:48.180 At Jumpstart Lab, all of our tutorials are online, and we offer open source content that can help you improve your Ruby and Rails techniques. This makes it a terrific resource for anyone eager to expand their knowledge. Thank you all for attending, and I'll see you around.

LA RubyConf 2012