 That's in April, April the 8th, and then there's going to be one in the fall also. That's going to be an answer that I'm going to give you. All right, let's get started. Thank you very much. Yay! All right, so, good morning. Thanks for coming. In through the snow and the slush and the general, ffasdenweather. It's all part of the experience. Hi, my name's Lorna. I work at a company called Nexmo. We do telephony APIs, so if you need to make phone calls, send text messages, WhatsApp messages, Facebook messages, video calls, whatever. We do that, and that's the end of the plug, except you'll see some examples because they're examples from my day job. Today I am going to talk about API specification. Now, to bring open API spec into a documentation track is kind of false advertising because open API is a wonderful way to make excellent API documentation, but you can also do loads of other things with it. So I'm going to focus on the doc side today, try and give you some advice for working with open API in general, and we'll just touch on some of the other fun stuff I am and hope to be doing with open API spec. My background is, as a software engineer, I just have incurable writing tendencies, so I've ended up here at the join of writing and coding, focusing on documentation, and I'm excited to share it with you. So why are we describing APIs? By describing our APIs, we create something which is independent of the API itself. It is about the documentation, but it's not just about the documentation. If you were going to write API docs, instead, you can describe your API, generate the docs, and use that description for a bunch of other things. You're separating the content and the way that content is presented. So from the open API specification, you can generate long-form, very detailed docs, perhaps in a web-based format. You might want to generate them in a printable format. Maybe you just want to take the paths and the parameters and create a quick cheat sheet. You can do all of that from the description. Crucially, people can take that description and use it for whatever they need. I work as a developer advocate and focused on developer experience. It's about giving developers what they need. You can generate mock servers and tests, client SDKs, libraries, all from this description of your API. It's really not just, it never is just about the technology. It really isn't all about the technology. The thing I love the most about having the open API spec is how it enables people to collaborate on the API design before we build that API. It's not a case of let the developers loose and then bow to their superiority. By using the spec and collaborating on that spec, we can generate the documentation. The business users, the product users, can all be part of looking at the API and understanding it. The engineers can generate a mock server. I can import the spec into Postman and see what I'm going to get, how that's going to look, how the parameters are expected, how they should be formatted. I can instantly start to poke at this thing. Once upon a time, I took a request from a client, so we ran their admin backend, so it's got an admin backend, a database, a web-based thing, and they ran a front-end. The request came in saying, we need right access to the database as well as read access. No, I am responsible for the integrity of the database on your backend. There is no way that you get right access to it. Further inquiry was a holiday booking site and they needed to be able to, they wanted to be able to make some bookings from the front-end. Well, that's fine. We can make you an API for that. It was more about availability. However, they needed it like today. I wrote the fastest API documentation I have ever written for an API that didn't exist. We collaborated on it, agreed about how that should look, iterated on that API. This is before we had open API specification, so it was just a markdown document. Agreed how it should look, and then I don't think I've ever built an API faster than I did when I worked off the spec. By doing that collaboration and that evaluation early on in the process, it cuts out the cost of redoing something you've actually built. It's like finding a bug earlier in the process, except much bigger because it's a whole API, not just one bug. Open API spec itself, you may know it as swagger. Some of the tools still use that name, swagger. It's a smart bear trademark. What used to be swagger, which is, by the way, a perfectly good way to describe APIs, was given to the community. It's no longer owned by one company. It's owned by a group. I trust those people. There are some organisations and some individuals in that group. It's not all big business. They do know their API stuff. I believe that they have good motivations, and I trust them. They now own and iterate on the open API spec. You'll now hear it called open API spec. The v3 release introduced some really good stuff. I got some hints about the 3.1 release this week when I saw one of the maintainers. That's exciting. There's some really good stuff. Just look out for the versions, a mentioning version 3. Not all of the tools have caught up yet. We're very nearly there, and the ones that don't support version 3 yet have it on their road map, so just drag your feet a little bit before you start your project, and they'll probably get there. If you're starting a new project today, I definitely would recommend that you go for v3. I am often asked whether it's useful to add open API spec only on new projects, or if it can be added to existing projects. The answer is yes. At Nexmo, we retrofit the API description onto our existing APIs in most cases. We have some newer ones coming through now where the spec was built first. You absolutely can fit an open API description to an existing API. It's able to describe all sorts of weirdnesses. The places where it's a little bit sticky is where your API is a little bit not standard. That can give you a clue for areas that you might revisit when you are making changes to your API. I loved that we asked some questions at the start for who is in the room, and there was a good distribution of different types of people. I think open API specs do really cover lots of different disciplines. I'd love to have the product owners write the open API specs. They don't love Yamel, which is fair, but they do have a real insight into the detail of the product of the API, the real nuances of which lookup codes are allowed for this parameter and how the format should look, what sequence things should go in. Having the product owners involved in creating the API description is, in my opinion, invaluable. I see a lot of writers coming over from writing API documentation. They may not describe themselves as technical people. Clear to me, they're pretty technical. They could describe themselves as writers. Open API spec really benefits from the input of a writer because you need to describe each path, each action, each end point, each parameter, each error message. It's basically microcopy. This is a craft in and of itself, the way that you explain what something does in a concise way. Picking examples for the values that will display and illustrate exactly what this end point is for. That's the joy of having a writer writing your open API spec or involved in that process. I count myself here as an engineer. Of course, the engineers should be writing the API specs because they are probably writing the APIs. I'm being able to describe what your API does, even in the edge cases, exactly what it is and is not allowed. It's something that we need to get right in the spec and then bring into our implementation. I think if you identify as any one of these three people and especially if you identify as any one of the three plus some tendencies of one or two of the other, then open API is a really good place for you to be working and it will suit you really well. Let's talk a little bit about the anatomy of an open API spec. I have a tree here because it kind of starts with a certain level of top level elements and then each of those has many elements inside it. It kind of spreads out like a tree, except as I down details. At the top level, you will find these elements, open API. That's the version of the spec that we're following. There's an info block. This is super interesting. A lot of the documentation renderers don't show all of the fields in the info block. It's very tempting just to write a description and sort of skate over the rest. The future of open API is in discoverable APIs. We'll be uploading aspects to shared spaces and allowing people to discover the APIs that meet their needs. Don't skimp on what goes in the info section. It's going to tell the story of your API to the wider public in the future. The servers is the array of endpoints. We've got paths. Paths is what you think of as API documentation. It's a list of endpoints and describes what the method is going to be, what parameters are acceptable, how those should be formatted, are they query parameters, body parameters, is it JSON? The paths is where what I think of is the main stuff happens. The components section is a big bucket of all the things you might need. Open API supports references. If you need to use the same parameter, hopefully called the same thing, formatted in the same way, accepting the same values, in multiple places, you will put it in the component section and refer to it. That is true for responses as well. Error responses, standard responses. You can put everything in the component section and reuse it throughout the paths section. The security section describes which component scheme to use, which security scheme to use, that's in the component section. You can also use tags. Tags are free form labels that allow you to group similar endpoints together. Some of the documentation renderers will then show them in sections. If you have a large API that covers quite a lot of endpoints, tags can be really, really useful and I would recommend it. It's quite free form. You can attach multiple tags to an entry in the paths. It's a good way of saying, well, this is to do with users, this is to do with users and account, this one is to do with payments, so you can sort of group things together. I feel I've talked enough about this. Let's look at an example. You can write open API spec in either JSON or YAML. I could make the argument for or against either of those formats. At Nextmo, we're using YAML. I'm happy with that. It starts like this. We've got the open API element that I mentioned with an example. A list of servers that you can make API requests to. The beginning of the info block is here and I chopped a few hundred more lines off this example. I'm not going to lie to you. These things are the boasts. They are unwieldy. You are dealing with hundreds of lines of YAML. You probably need some tools and I'll talk about that in a minute. Here's a path example. I shrunk the font as much as I dared and I hope it isn't too much. This is our number insight API. You can use Nextmo services to take a number and look up. Is it a valid number? Which country is it in? The basic one doesn't give you a lot of detail, but if you want to know more about it, more about that number and when it was last used, etc, you can use the expensive versions. This is the basic version. We make a call to slash basic and then a format parameter. Because that format parameter is in every endpoint, it's going to be JSON or XML, I just refer to it. If for any reason I want to change those, we support an extra format or I want to change the wording of the description for this field. I change it in one place and it appears everywhere. For this path, we support a get parameter and I give it an operation ID and that's just going to be a unique way of referring to a specific endpoint. It's used usually in internal hyperlinks within a documentation, so it's good for it to be unique. Again, I'm linking through to parameters that will be reused for every one of the endpoints in this application. We see an example. We've got some responses. It's a 200 response and again we've got the basic JSON response. Let's have a look at a couple of these references, getting the idea that it's big and we sort of drill down a lot. Here's one of the parameters. This is the number parameter and we say this is in the query string. It's a query string parameter. We've got a description of it. We've got an example and the example shows you the format that the number needs to be provided in. It is a required field because I can't give you insight into a phone number if you don't give me a phone number. This would make no sense. Number is a required field and there's some rules about how it must be formatted. Here's that JSON response. I had to chop it but you get the idea that what do we get back? Well, we get an object and that object has some properties. They are status and we can look at what the status is might be. Typically at zero, everything works successfully. A status message if needs be. A request ID that you can use to look up later. We also offer an asynchronous version of this. Sometimes you need the request ID. You'll get the number as well, the country and so on. We describe all the fields that will be in the response, what their formats are, what their four descriptions. If there are default values, you'll see those listed here too. Oh my word. That's a lot of code. That looks complicated. If you don't look at Yamel all day, your eyes are probably a bit itchy right now. It's not complicated but it is verbose. It's unwieldy but it's not particularly difficult. Once you've got that API description, you can do a bunch of things with it. Here it is rendered with a standard tool called Redoc which is, I use it to check things to just see how my API looks so you can instantly generate this off it. Very nice. We also use a different renderer for our developer platform so the same API could be rendered like this on the developer portal for Nexmo. Maybe you want to get a bit more hands-on with it. Well that's fine. You take that open API spec in Yamel and you import it into Postman. They now support open API v3. You can instantly add your API key and secrets. Start adding a phone number. Start making those calls to the API. See how it looks. See what comes back. You don't have to write code in your application to be able to use this stuff. Let's talk about some tools to help you get things done. I think open API spec particularly the v3 is great. I think it opens so many doors. The community is fantastic, really supportive. I've seen so much help. People apologising for newbie questions but you don't need to because we're all learning and nobody minds questions and I think that's a great measure of a community. That said, you are going to need some tools so I'm going to recommend you my favourites. Perhaps I'm preaching to the choir but could we please begin with source control? You are working with hundreds of lines of Yamel. There will be moments where things go wrong and it won't compile. Wouldn't it be nice if you go back to a known working version? Source control is for people who sometimes make mistakes. You might want to work with other people someday, bearing in mind that if you've slept you are the other person. You might want to share this. You might want to make changes to the spec in the future. This is a whole of a talk which we will not give now but go to gitworkbook.com if you would like to learn. I wrote a book that was like all chapters with examples and you can download a sticker chart for each git thing that you've learned. Editing tools. You are going to need more than a text editor to work with Yamel. Can you edit Yamel with a text editor? Yes, you can. Would you want to do it without any helper stuff at all? If you're superhuman, sure, for the rest of us I'd recommend some helper tools. I usually use BIM but we'll skate over that because I'm not recommending it. Try ATOM. The plug-in is called Linter Swagger but it does support OpenAPIV3 and it will very clearly show you if you have either a Yamel indentation mistake or an unrecognised field and stuff. It's got some validation in it. I use that in ATOM. I have a screenshot of that. Look, here is that same thing in ATOM. Try Swagger UI, Swagger Hub. These are all smart bear tools that you might find useful. There's a bunch of different ones. Swagger Hub will help you write your Yamel and publish your documentation. API Curio Studio gets really good reviews. I haven't used it but it's earned a place here. Stoplight looks interesting. I'm just not convinced that they are live with their V3 support but it's in some of their tools and it's on their roadmap. If you find it's not there, it will be. If you have favourite OpenAPI tools, would you please tweet them at me and I'll try and tweet them back or update the slides or something. If I'm missing something, let's share that with everybody. OpenAPI, that's the same spec that I just showed you and you get the idea that if it goes wrong, the whole lot goes white or red or something and you're like, oh yeah, something's gone wrong. Do take the time to set up the validation tools. It's long and complicated and like I say, if you make a lot of edits in a long file, it can be hard to know what's not right. When you start a new OpenAPI spec project, take the time to do a minimum viable specification and set up the tooling. Save the file, run the validator and preview it in some sort of documentation renderer. Set that up before you go very far. Make sure it's there and then let the machine do the work. We're writing this machine-readable format and yeah, it's magic, yeah, it's going to change the world, but as far as I'm concerned, if I'm spelling it out for the machine, then the machine can do the heavy lifting of checking the spec and doing all the lint check and the validation. I often use spec-y. It's a command line tool from WeWork. It's opinionated. I mostly agree with its opinions, but crucially it is configurable so you can turn off the rules that don't apply to you. I also use OpenAPI spec-validator, which is another OpenSource command line tool. It often gives better error messages or more descriptive error messages on what I did wrong, so you might find that helpful. I just use a watch command so when I save the file, if the file's changed, speccy runs again and gives me the error output, not that I make mistakes. Yeah. Use a preview tool. You've seen the output of Redoc already. Even if it's not documentation that you're generating, I find the visual documentation human-readable, just a nice way to look at the YAML that I built. Speccy has a speccy serve option, which also has Redoc under the hood, and I've also had recommended to me OpenAPI GUI as a local tool, so you don't need to be working in the cloud with web-based interfaces if you don't want to. I tend to be more of a local machine independent, sometimes working on the train kind of person. So whichever you prefer, there's tools for you. It isn't rocket science, but it is quite an undertaking. We have a saying in English, how do you eat an elephant? One bite at a time, and that is how you're going to write your OpenAPI specs. Please do not open your editor and write 500 lines of YAML. Please open it, add the initial fields, add the first endpoint. Don't start putting things in the components section yet. Go longhand and check that everything looks right, and as you come to reuse a component, then you can refactor. It's just like coding for those of you who code. Build it up in steps and lean heavily on those automated tools for this machine readable format. That's what they are there for, and they will help you to get going much more quickly. I think OpenAPI spec is magic, and what's really magic is I could put a list on this slide of all the things that you can do with OpenAPI spec. We can create documentation, we can create tests, we can generate client libraries, we can import it into postman, we can run mock servers, and the magical part is I don't know what would be on this slide if I gave this talk in six months, 12 months. When you invest in OpenAPI, maybe just to make the best documentation ever, you're investing in a standard format that I don't know how we're going to use it yet. When we started writing the OpenAPI specs at Nexmo, you could generate docs that was it. There wasn't a lot of swagger integration. Now we're starting to look at, we write client libraries in seven languages, wouldn't it be nice to generate some of that boilerplate code? We're starting to look at that as we move forward. The magic is in the extensible format and being able to reuse things in the future. I am going to leave you with a whole list of resources. I'll tweet my slides later. They are also uploaded on to Pentebeth, so you're all good. Using the spec enables all of the stakeholders in an API, the product people, the business people, and everyone to participate. API evangelist has some great content on this. Speccy and Redock are great tools, but go to openAPI.tools for a community maintained up-to-date list of tools. They change all the time. Don't refer back to these slides of tool names in six months. Things are just moving so quickly. I'm using this code generator and I think it's awesome. I'm out of time. Tweet me if you have questions. Thanks a lot for your attention.