b {font-size:115%;} Note: If you're in the Bay area, come listen to Michael Stowe speak tonight (Monday, Oct 12) at the STC Silicon Valley chapter in Santa Clara. See the meeting details here. In this episode, I interview Michael Stowe, author of Undisturbed REST: The guide to designing the perfect API, about spec-driven design for REST APIs. The podcast has an emphasis on RAML as the specification format, but the discussion goes beyond a particulate specification to discuss development approaches that focus on creating a specification file (which acts like a contract) before coding the API. You can listen to the audio here: You can download the MP3 file here. (The audio is a little choppy in the beginning due to some bit rate issues — sorry about that.) Topics covered in the podcast Some of the topics covered in the podcast include the following: The purpose of RAML, Swagger, and API Blueprint REST specifications The philosophy of spec-driven development Benefits of interaction API documentation Agile development and versioning with APIs Treating the spec as a contract for what developers are building Prototyping and mocking services from the spec Client SDK generation from spec files Determining which spec to use Using the spec as a point of collaboration for all groups Treating the spec as a single source of truth Workflows and processes about when to create the spec and when to annotate the code How to get support and buy-in for using a spec-driven development approach Resources mikestowe.com RAML Undisturbed REST: The guide to designing the perfect API (on Amazon) Undisturbed REST: The guide to designing the perfect API* (Free PDF download) Podcast transcript I also created a transcript of the podcast below. (My questions are in bold; his responses are in normal font.) Tom: You're listening to another podcast from Idratherbewriting.com. My name is Tom Johnson. Today I'm talking with Michael Stowe, who is the author of Undisturbed REST: The guide to designing the perfect API. Michael, can you tell me a little bit about yourself and your book? First of all thank you for having me on your podcast here. I was engineer for about 10 years, and actually the reason I wrote the book was a little bit selfish. I kept using APIs that were a bit difficult to use. I felt that there were a lot of different conventions out there. Undisturbed REST is really a book about going back to the basics. What is REST? What is this design theory, this architecture? How do we make it work, and what are the best practices with it? If I have to use APIs, they should work and there should be standards, so I'm not pulling out my hair (because I can't afford to lose anymore). Tom: You work for Mulesoft, right, and a lot of the book focuses on RAML. Most of my listeners won't be too familiar with RAML and Swagger specifications. Can you give a brief into to what these REST API specifications are, and how they came about? Yes, absolutely. The first specification that came out was Swagger. This was created by Tony Tam about 5 years ago, and it was for his company Wordnik. At the time we had these APIs coming out, there was really no support for documentation, client generation, server generation, code generation. You would create the API, write the code, and then you'd have to do all of these additional services on top of it. Wordnik wanted to create a quick way to easily document your API and create some SDKs, so they created Swagger. A couple of years ago, a new spec came out called RAML. RAML stands for REST API Modeling Language. It took the idea that Swagger had, which was once you have the API you can document it, a step further. What if you can actually design your API before you build it? What if you could see what your API looked like before you build it? What if you could prototype it and collaborate with your users to make sure your API meets your needs before you spend time on the code? And then get all the goodnes