Stoplight’s Taylor Barnett looks at how creating OpenAPI specs can give you more than just documentation, in her talk at DevXCon San Francisco 2018.

Transcript

“To infinity and beyond,” something Buzz Lightyear said in “Toy Story.” I think developers, even though it’s a little cheesy, also kind of embrace some of these things, creativity of different use case of different tools. And so that’s what I wanted to talk about today with OpenAPI and developer experience. So hi, I’m Taylor Barnett. I’m the lead community engineer at Stoplight. Stoplight is a platform to design, test, mock and test…I mean and document web APIs. And I help hundreds of our users use OpenAPI specifications. Before Stoplight, I worked at Keen IO, a data analytics API company, and I managed SDKs, developer community, and documentation there. And a lot of these things that I’m going to talk about are solutions to problems I faced and also things that our customers are using at Stoplight that I find really interesting.

OpenAPI as a bridge to understanding

So when I was first introduced to OpenAPI it was with this idea of a single source of truth. This idea that what Wikipedia says is: practice of structuring information, models, and associated data schema such that every data element is stored exactly once. I think that’s super wordy. An easier way to think about that, it’s a contract. It’s something that different parties agree on. And if someone breaks it, something bad happens. And so that’s kind of something I want you to think about throughout this talk. As much as we would like them to, self-documenting APIs do not exist. APIs are like this intersection of humans and machines. And so we need something to bridge those two things together, and that’s where I see API specifications sit.

And so, in this case, what is OpenAPI? Just to gauge everybody’s, like, level, I’m gonna ask a couple of questions. Who feels that you could answer this question, hypothetically, right now? Raise your hand. Okay. Who is currently using it in your role in some way? Raise your hand. Okay, cool. And then the last one, who knows that it’s being used at your organization for something other than API reference documentation? It’s a lot less. So that’s like the common thing that most people are using it for. I was first introduced to API specifications at a startup I worked at about four years ago, through API Blueprint. We were trying to document an API that was internal, but we were wanting to open up to other users. And it was extremely painful. I didn’t understand how the specification worked. I’m using a plain text editor. It was just a lot more painful. And I’m happy to say today, it’s gotten a lot better.

So how I describe OpenAPI, it’s a standard structured approach for describing APIs in a human and machine-readable way. It’s descriptions of specific properties that then machines can process. Initially, it was called Swagger. And now, it’s more a vendor-neutral specification. And now, Swagger is more the tooling. So sometimes people still use those interchangeably. And historically, it’s been a thing to generate API reference docs. I really love this quote: “OpenAPI is a bridge to understanding and being able to communicate around using HTTP as a transport, and our greatest hope for people to learn their HTTPs and 123s.” So again, this idea that it’s bridging together different teams and people.

And so like I said, it’s known as API reference generator. Everyone loves something that writes to your docs for you, you know? So that’s like typically everybody’s go-to because a lot of people don’t like writing docs. Here to say, it’s not just for API references. Say, you have a new API feature. All the things that you need to do, you gotta update the server implementation, you’ve got to update all your client libraries. Sometimes that’s many of them. You’ve got to update the documentation, and then you also got to make sure that all of these things are happening in a consistent way. Also, the frontend team is being blocked by the fact that the backend team has not finished the API endpoint and they need to implement it some on the frontend.

A tool for collaboration and common language

And so the OpenAPI fulfills a lot of these problems. It’s a development contract, a bridge between teams. It removes the silos that exist around the API development process when everyone’s working around a central contract. It allows technical writers, and frontend developers, and SDK maintainers, and developer advocates, and many others to go ahead and start their work earlier in the process. And it also gives you options for how to potentially create your SDKs and client libraries. And then the other thing is, it’s all different kinds of testing, which we’ll talk about later. And it’s even ways to generate server stubs so you can start your implementation faster based on the design you’ve all agreed on.

I’ve heard a lot of people ask me, a lot of times this is in technical writing communities, “Okay, my company is now using OpenAPI. What do I do?” And I tell them the good stuff – when you aren’t writing API references and you’re saving time during development, you have a bit more time to look at the bigger picture of the API. You have time to explore how maybe you can incorporate the references into guides and tutorials, which is something we’re exploring at Stoplight, and other tools like DapperDox are also working on. And so then you have more time to write guides, the things that users really want sometimes. And then also, it does take a little bit of time to explore, what is our maintenance flow of the specification? Like, “Cool, we created it once, but how do we update it? Who updates it? Who owns it?” It gives you a chance to kind of look at that design process internally and at least create some structure to it. And so it’s a tool for collaboration really.

Filling in a spec is kind of like filling in a form. It simplifies describing it. It’s a lot easier to fill in a form than starting a blank page that you have no idea where to start with, and so it kind of gives you that guidance and structure. It also standardizes terminology. So, kind of like a style guide. When you can speak the same common language, things happen faster. So I had seen in the Write the Doc Slack, some people were talking about BasePass. And another person was calling it a totally different name but they didn’t realize that they were talking about the exact same thing. And so, by having that common terminology, like these discussions can happen with less friction between teams.

And then also there’s this idea of API fastness that was coined by an API handyman, which means accelerating the development of an API while still maintaining a certain amount of security and quality control. It’s removing the break things part of move fast and break things while still focusing on the overall developer experience. And so that’s a lot of what I wanna talk about. I’m gonna break this into three parts: design-first, mocking and feedback, and then testing.

Design-first

So design-first. So typically, people get their spec one of three different ways. You’re automating it from the code, or you’re creating through more design-first principles. A lot of times, they were product or engineering team, or you’re creating it from scratch after. Sometimes the developer relations team is doing that. Sometimes it’s the most painful way of all of them because you’re just being given the API and you have to start from scratch.

I really wanna focus on the second way. And because it’s really embracing what I think OpenAPI kind of has set out for. It’s heavily about making things are sure…they’re consistent. When you have a standard, your API just comes out a little bit more standardized in the end. And it’s easier then to maintain it and makes users a little happier that they’re not having to, like, get really confused because, you know, everyone has seen that API. That one similar endpoint was implemented one way, and another one was a totally different way. And support gets questions about it all the time, and the developer advocates are constantly having to correct users, and the docs are then more confusing to write, and it just spirals.

And then sometimes, also, code-first can be expensive. So fixing those problems is hard. Convincing the engineering team that we need to go correct that, especially if things are versioned in a certain way, and then maybe you have more versions you’re having to maintain. Again, it spirals. And then, so then, you can really fully gain the benefits of using OpenAPI.

Mocking: why you should care

At Stoplight, we say that mocking is routing incoming requests to example responses, or also dynamically generating examples on the fly. There’s a few mock server tools out there. Also, people like Stripe have built their own, some people are kind of building their own for Slack API even. My teammate maintains Prism, which is a popular one where you can just feed it an OpenAPI spec and it acts as a mock server, amongst other things. It does contract testing and some other stuff we’ll talk about.

So why should you care about mocking? A lot of people might care for different reasons, depending on your role, if you write docs, tutorials and content. In the past when I had to write docs for a new API feature, I’d be lucky if I’d get the communication started on that early while it was still in development. I was usually never able to start the docs then because I was given this, like, very vague Google Doc that wasn’t really enough to, like, actually write API reference material from. And so I’d have to wait, or the endpoints were still changing. And so it was just really hard to start documentation sooner. And then also, there’s this really awesome technical writing blog called, I’d Rather Be Writing, from Tom Johnson. And he says, a lot of times for writers, if you have access to the spec, you probably have a lot more opinions about whether you think it’s consistent or not, no matter the amount of your technical ability. You can just tell when you’re having to write, that it just doesn’t make as much sense. And you’re having to explain it to users anyway.

And then the last one is, mocking is what’s really empowering interactive docs. So when Swagger first came around, you know, part of the thing was that we can have these interactive docs that you can have, like, try it out functionality. It’s basically mocking, is what that is. If you maintain client libraries or SDKs, you just get more options. Whether you’re partially generating, not auto-generating at all, fully auto-generating, that’s like a whole other conversation, but at least you get the options because most of the tools out there now are using OpenAPI specification. Also, if you’re writing it from scratch, if you already can start mocking it, you can already start implementing those parts in the libraries. So then you can have it ready at time of release.

Time is of the essence

So one of the things I’ve seen a lot of times is new API feature comes out, and they’re like, well, the Python library is coming soon. Well, you just lost a bunch of Python developers because even though they could go use the API, they really want that SDK. And so, having things ready sooner can be really helpful.

And then also frontend engineers. So one of the really cool uses that I’m seeing with the mocking with users at Stoplight is that they want their frontend teams to go ahead and be able to start development while the API implementation is not done. They’ve agreed on the design, so that’s done. But then the frontend engineers can go ahead and start putting in those endpoints into their code and start writing so that they can work in parallel versus having to come in after the endpoints are done.

If you care about developer experience, API design, advocate for users, like, basically everyone here, being able to get early feedback and help influence where the product is going towards before its release can be so critical. I mean, sometimes, I’ve seen APIs get implemented, and it’s like, “Okay, how many users did y’all talk to? How many users did you put this API in front of?” And it’s not always a lot because it was hard to, you know, maybe have to explain it to them. Being able to put real endpoints in front of them and say, “You can hit this and get back a response,” is so much better. And you had to write almost no code to actually do that.

And so there’s this awesome blog post from Lorinda Brandon called API Design Using Feedback Loops, that really can show you, like, how do I run these feedback loops? So much of the docs that we create now are about interactivity. You know, users wanna be able to interact with the docs. And so this is doing that for them in the feedback process. And so, this is this idea that they’re called Experimental APIs, which Capital One describes as mock services that use simulated data to mimic API functions. And so, basically, you know, they’re able to start having conversations with users earlier. For Capital One, that’s about the future of banking products in APIs. And you can start then building better partnerships and in getting users to buy into the features so that when they’re released, there’s so much more engaged with them because it’s something they were a part of rather than created without them in mind.

Interacting with humans

And so the last thing with mocking, it’s all about all the things we’re doing. We’re talking to actual people. We’re actually interacting with humans because that’s what APIs are, a mixture of humans and machines. And so, very basic questions you could ask, you know? What are the tasks that they’re wanting to accomplish, you know? Are they able to do that when they go through these experimental APIs? Will the API help them achieve that? And then, are they confused in any part of going through those? You can catch a lot of little things that could be fixed so that they’re never released early on with that.

Some companies that are also putting their OpenAPI specifications on GitHub, SendGrid, Azure, even though that’s probably a lot of Microsoft employees, to me, like 440 people, and this was a couple weeks ago, interacting with a specification and a repo is just like incredible to me. Slack, Stripe, New York Times, Flickr, many others. There’s this idea that they could then make this specification the centerpiece to the whole feedback loop with the community. It’s a lot easier for users, especially more technical users, to be like, “Okay, on this line, this response doesn’t match this other response. Like, why did you all do that?” And open an issue, and have a discussion, and makes it easier than just be like, “I’m confused by this part of the API.”

Testing makes users happier

And then the last one is testing. So, testing can mean a lot of different things, but I want to focus on how it’s important to the overall developer experience. So it’s machine readable so you can write a lot of different tests based on the specification. What we mostly focus on a lot of times is helping people verify that their requests and data types match or are similar, things like that, in the specification to the actual implementation, to the SDKs, to how it’s in docs, and especially if you have like a custom docs setup. You can track API style guides. There’s this awesome tool called SPECI that you can then make sure that your specifications are meeting your internal design style guide, tools like Dredd allowing you to validate your API implementation against the backend implementation.

One great example of that is also Sun Grid, is in their continuous integration process, in their SDKs are comparing to make sure that the SDKs are actually implemented against the way they’re described in the spec so that they’re consistent. And it also helps if you have outside contributors, so then they can then flag like, “Hey, this doesn’t match what the API actually does.” One of the experiences I had at Keen IO was we had an error in our PHP SDK. And I’m not necessarily the best PHP developer. And I had to get the code from the user, what they were doing, because it wasn’t responding the way they thought it should. I had to look at the docs, make sure they were correct. I had to go to the API team, see if anything changed recently, then I had to go to the SDK and see what its history was. Like, did we introduce some kind of change?

And then, you know, that’s like two days of going between all these different people. And it turns out six months earlier, somebody merged a pull request and it changed the behaviour, which could have been completely prevented if we had done what we’re calling contract testing, basically. It’s testing against the contract. Your API specification is that contract. This could be done in multiple ways, but here’s like a very basic example. So you have the response body, and then you have your specification, and it’s comparing that on, like, a validation server. In our case, we use Prism. And then it just basically tells you yes or no, like, it matches or it doesn’t, and it can really save some headache later on.

And this is back to what I was talking about. Like, it’s less support overhead, then, you know, less confusion. And not only the users are happier, but you’re just having to run around and deal with these, like, annoying bugs that could have been prevented, and you get to spend more time on more developer experience-related stuff.

To infinity and beyond

Now, the last part, the reality of all this is that it seems like very wishful thinking. I’m seeing companies do little parts of all of it. The question of who makes a spec is still a really big one. Maybe you’re in an organization where the developers are fully onboard in maintaining a spec. That’s awesome. You’re lucky. Maybe you’re the one having to maintain the spec.

One of the things that I’ve seen is, project managers can be really great allies because they have a bigger scope of everything, from QA, to documentation, to product, and they can help introduce some of these best practices. Also, sometimes, just describing the spec yourself and then taking that back to engineering and being like, “Look, we just got these awesome tools because we had this. Help me maintain it,” like, work together. And it’s all about, like, inserting yourself into the process. How do you become part of the design process, because you’re the one talking to the users the most?

And that’s the infinity part of this. Like, all the ways that we could be using OpenAPI specifications is still being figured out. You know, there’s linting, different ways of style guides, continuous integration and deployment, testing of docs, just integrating it deeper into the development environment. That’s still things that we’re all figuring out. So some of us say that we should be building better APIs, but I think we should be building better API experiences because that pulls in more of the silos that have typically existed, pulling in the writers, and developer relations, and advocates, and engineers.

And so I have a challenge. What will allow you to focus more on the things that you could use something like OpenAPI specifications so that you could then focus more on the API experience? I work with a lot of smart people. I’ve seen a lot of different creative solutions. I’d love to talk about them. If you have anything you wanna brainstorm, I’m happy to talk. And just thank y’all. Yeah.