Good morning everybody. Thank you for being so patient. I don't think I've ever had a
full room with 24 minutes to go before the start of my talk before. So that is a very
special experience. Thank you for sharing it with me. I unmuted, but thank you for checking.
So I am going to talk to you today about OpenAPI. I'm going to try to give you something
new that you could maybe take back and try, whether you haven't seen this before or whether
you're just looking to level up your game a little bit. My name is Lorna. I work for
Redockly. I'm VP Developer Experience there. I love APIs. My background is in software engineering.
I've been a developer for most of my career. I've built APIs, integrated with APIs, worked
for API producers, done API consultancy. Now I build the API tooling. It's, yeah, look,
it's a thing that I enjoy and I'm happy that you are all here to share it with me. So let's
start by talking about OpenAPI. OpenAPI, I know a lot of people raised their hands, but
maybe it's new to some people. OpenAPI is an open standard. It's a way of describing
your HTTP APIs in a format that aims to be both human and machine readable. What's nice
about that is when we use a standard format, everybody uses the same format. And when that's
an open format, it's developed in the open. You can be part of that development process
and I'll talk a little bit more about the OpenAPI community at the end. You can see
what's coming. You can join the meetings. You can follow the issues on GitHub. If you
are using OpenAPI as a producer, as a consumer, if you make tooling for OpenAPI, there are
no surprises. You know what's coming and you can be part of that. So it really improves
our confidence on working with it. I think the most difficult thing about working with
OpenAPI is it's just very verbose. It takes a lot of lines to describe what can be quite
a simple thing. So I'm going to start by talking a bit about the structure of OpenAPI because
I think when you can find your way around, you understand the map, it's much easier to
work with it. So this is a representation of the things that you will find at the top
level of an OpenAPI description. OpenAPI, which version of OpenAPI is this? Info, a
bit of metadata about the API that this description describes. So here you'll find the title,
probably some license information, some contact information, the version that we're on. All
of that is in the info block. External docs. It's very easy. You publish an IAS developer
website, you link to your API reference docs. If the user arrives on the reference docs,
maybe from a search engine, is there a link back to that nice developer website that you
made them? Check, because I feel like I've put this right on everything I've ever worked
on. There is a security section and that will describe the authorization and authentication
needs for the different that are used by the different endpoints in your API. We've got
a service section, where is this API published? Tags allow you to attach metadata to individual
endpoints. They're listed at the top level and then you can just use them where you need
them. The paths section is where the real API documentation actually happens. This is
what we think of as API docs. We have an entry for each endpoint describing what it does,
the parameters that it accepts or how to shape the request and the response or responses
that you can expect back. You'll also find web hooks here, so where you have an API that
as well as receiving requests and returning responses, something happens and it sends
you a response. You can describe those with web hooks. They're a little bit different to
the request response feature. Those were added in 3.1, which, although it is the newest version
of OpenAPI, is 3 years old, so wouldn't describe it as cutting edge. We also have here the
components section. The components section allows us to describe things that we're going
to use multiple times. If you use the same filtering, pagination, date format, if those
are common patterns across your API, I mean, if they're not, we need to talk. But if you
reuse those things, you can define them in the components section and reuse them.
So knowing kind of, they can go in any order, but knowing where you are and where the other
things are that you might need can make these very long documents navigable. OpenAPI descriptions
are often thousands or tens of thousands of lines of code. My favorite test API description
to use is the GitHub one. It's quarter of a million lines of YAML. Like, yeah, you need
to know where you're going. Your tools can help you. But it's like carrying something
that's not exactly heavy, but it's just a bit unwieldy.
So let's drill into some of the detail. Here is just basically the top part of your OpenAPI
description. We have a version. It's not very exciting. We have an info section. We've
got a title. Give your API a unique and meaningful title. We have summary and description. A
lot of OpenAPI elements have these two texty fields, the summary and the description. The
difference, the summary is just text. It's short format. It's usually shown in a listing.
The description supports markdown, specifically common mark. It's usually shown when we're
looking at the detail. So if your API is shown in a catalog or in a list, it'll use the
summary. And if you are viewing the API reference documentation, you'll probably see the whole
description. And don't be afraid to use the markdown features for links and to really
enrich what you do within your OpenAPI file.
There's an info version field. And I think this is one thing that I see people getting
confused with frequently. Info version is the version of the API description. So if you
change this definition document, you're going to change the description field. Does your
API info version need to match your API version? I don't really care. But if you change your
description a lot, can you please bump the info version so that I know I don't have the
latest version of this document? You lock it to your API version if that helps or don't.
Maybe you haven't made any API changes, but you did add great descriptions, better examples
or something else that changes the OpenAPI description of your API. Bump the version
so I know I need to get the new one. Please add a license. Yeah. So this is like some
nice fluffy rendering. I made this with Blockly. I hope that you like it. And I think it's
just easier to look at than the real thing. This is the YAML version. And I can do 10
screens of YAML and I will be having a nice time, but I don't know if you will be having
a nice time. So I brought you some pictures. But this is kind of the equivalent of seeing
it in YAML. Like now imagine another 20,000 lines and you're starting to visualize how
this thing looks. Okay, let's look a little bit at the paths. We have within the YAML
path section, we have one block for each combination of URL and verb or method. So like I have
one that is item endpoint, it's got a get operation. Got another one. I'm really good
at naming things. Called things another URL which has both get and post. Those are different
operations. They get their own description. If we drill into one, how's an operation ID?
Fun fact, operation ID is optional in open API. It's technically optional. Honestly,
you need it. It needs to be unique. Just get your linting to put that in. There's very
few APIs where this isn't a useful thing to have and it's not like it's painful to do.
We've got a description. You probably would have a summary as well. Won't all fit. I have
added some tags to my endpoint. This is related to user and accounts. We might have user and
orders or some other combination of tags here. You can have multiple tags. If there were
request body requirements or parameters, those will be described here as well. And then we've
got the responses. I've only got the 200 response here. It's very bad. You should always describe
your 400 response errors. I got 200 response here. It's application JSON and it's just
got a couple of fields in it. I'm going to drill into that in more detail. It's the same
endpoint. More detail. Shuffled down a little bit. In my response, you can see I have a
maybe you can't see actually because the font is quite small. This schema has a message
and an event ID. I've got data types. I've got descriptions. And I've crucially got
examples here. The examples are the magic because it lets the user know what kind of
data will this be. You can tell me it's a string. But if your example is, I don't know,
are you UID? I'm like, oh yeah, I know what that is. If you show me it's my username or
you show me it's an ID, okay, I am just instinctively going to put the right thing in when I'm using
those tools. If you use the same fields in other places and it's becoming increasingly
standard that even if you're not reusing them, you'll often use the open API reference syntax
to refer to them being stored somewhere else. So instead of defining each of the objects
or elements of the response payload, you just refer to use a reference, dollar ref, to refer
to that description and put the description in the components. So your path entry looks
like this and then we have that detail down in the components section under schemers.
So this gives you a very powerful reuse. The key to API experience is consistency. And
so the reuse helps us to just, without thinking, get it right, get it the same, get it consistent
and avoid having similar named fields that might take different timestamp formats or
look identical but validate differently because our back end application didn't understand
that they were the same thing. So that's the structure of open API but I really felt when
I created those slides that I was missing the magic. The thing that brings me to this
and makes me believe in open API as the powerhouse of our modern application development. And
when I think about open API, I think about the things that I do with it and the things
that it enables. You think about the way that you design your API, giving meaningful operation
IDs for each endpoint and these can be used by the tools that consume your API description.
Having great descriptions, naming things in such a way that developers don't need to come
and read your documentation because they will know from the operation ID what it's going
to do and it's very consistent. They feel at home. You describe your error responses
even if I never publish my open API description. The fact that I wrote down the error responses
makes my API better because I thought about what I wanted to do if something went wrong.
I can validate my API and make sure that my open API is valid, is at the standard that
I want and I can have my own linting rules as well. Operation ID is optional. Why? Not
in my APIs. So I write my own rules. I say we use kebab case here. We use plurals here.
We always define an error response. We make sure that our examples match our media types.
These are the things that you can add with the additional linting rules. We can create
documentation. That's great. You have an API. You should probably have some docs for it.
We can also allow other people to pull the open API description and generate their own
docs, keep it locally for reference. I have some accessibility needs. If you have an accessible
API web-based documentation, I can just generate with something that works for me with my
open API locally. It's ideal. Beyond this sort of entry level, there's
some more things that I think we are not doing enough of in open API. You have an API. You
describe it with open API. You lint it. You generate some docs. This is great. Please
do these things. You are all awesome. The next level is how you deal with very complex
API setups. If you work in a large organization with many microservices, how does that pipeline
look? How do you keep them all meeting the same standards? How do you bring them together
to publish as if you knew what you were doing to the user? Don't mind if you do or not,
but you need to look like you do. How do you bundle those things together? If you have
one enormous open API description, how do you collaborate on that when you are making
changes, whether you are an API experience specialist, product owner, engineer, tech
writer? How do we give you a clue that GitHub file is not maintained as a single quarter
of a million line YAML file? Looking at how do you manage your files? What do you do with
references? How do you split across manageable file chunks? Then how do you bring that together
to ship downstream? Finally, what do those downstream tools look like? A lot of organizations,
organizations come into open API because they want documentation. This is the beginning.
We don't want to write a whole load of words. We just want to describe once with open API
and then we can generate some documentation and we can generate it in different ways.
Then for free, you start being able to get all these other benefits. You can generate
some client SDKs. You can even generate your service stubs if you want. Lots of tools will
automatically integrate with your API if you have a good standard open API description.
So your API gateways and other integration platforms will just take it. But you can also
start to automatically look at how do you describe sequences of API calls? How do you
test your API? What does a mock server look like? Because you've described this API in
so much detail that a tool can pretend to be it very easily. So there's a lot of pieces
here that make up the ecosystem. Open API is kind of the seed from which the rest of
the tree grows. For me, this is the magic. It's the interoperability. It's the way that
we come back to maybe we generate some open API. It's terrible. So then we use overlays
or decorators to add all the descriptions and examples. And maybe not all of these end
points are public yet. So we just filter out the public ones to make the final open API
and generate some docs. Maybe only some of them are available in the SDK. So we filter
differently, make a new open API file, pass that down to the SDK's endpoint. Maybe the
next generation of your client SDK has some new functionality. Well, that you start with
the same source file or files and bring that together. So it's all about how do you not
code, generate docs, but how do you create your open API? Don't have time for my design
first rant. So I'm going to try and hold that in. However, your open API comes into
the picture. How do you maintain and manage it successfully? How do you ensure the quality
on it? How do you transform it and get it ready for all the outputs that you choose?
There's just so much in this picture. Let's talk about some tools. Now, I've just linked
open API.tools here. I'm not making any specific tools recommendations. That's for two reasons.
One, this is a really hot area. There's new tools every week. There are different tools
for different text acts. When you are ready for a new tool on that day and no sooner,
you should go and look at the list and pick something. The second reason is I work for
a tools vendor. I work there because I use their tools. I cannot possibly give you an
impartial recommendation. I went to ReadDocley because they know me and I know them. I really
don't know the other tools that well as a result. So don't listen to me for specific
tools. I work on the ReadDocley stuff and I love it. You need an editor. There's basically
two ways to go. You can use a programmer's editor, something like VS Code. Please add
some plugins to help yourself. ReadDocley makes an open API plugin. Even if you just
have some syntax highlight for YAML, the one that makes the indentations a different color
helps me a lot in YAML. Find something that works for you. There are some graphical editors
and if that's your thing, then go find one of those. You don't need to pick the same
as your team because it's an interrupt format. You use whatever you want to collaborate. Try
really hard not to lock your team into tools. Again, accessibility needs. I need to do it
in Vim and of course I can. That's part of the magic. Open API governance, which is clearly
not a tool, but let's skate over that. When you write, your API standards do not exist
until you write them down. They are not standards until they exist somewhere that somebody else
can look at them and they are consistently enforced. We have a lot of really good linting
that can really help you, but the humans are always going to be in this review process.
Find your most wise and thoughtful humans and invite them to be part of the review process.
Naming is the thing that the machines genuinely cannot do for us and just the joined up thinking
of being able to see things next to each other. As you introduce API standards, start small.
Do not be tempted by other people's recommended rule sets, not even ours. Pick what works
for you. Look at the recommended rule set, but then pick the things that you aspire to
and can adhere to today and commit to reviewing every six months and building up the quality
on your API. If you're retrofitting standards to an existing API, there will be things you
cannot change now and that's okay, but you can set those rules for the new versions.
If you don't know where to start on this, I am going to recommend Zalando. Have some
brilliant public API standards and you could do worse than, okay, they have a lot. Start
small, just pick your favourites out of theirs. It's a great place to start and your organisation
will evolve as it goes along. Please put some linting in. The machines are genuinely good
at this. They can help keep you straight. Is your open API valid? Does it have descriptions?
Does it have examples? I've got one team that I work with where we have a whole API where
the description for the access response is okay with a full stop and it turns out we
enforced sentences. So it has to be at least one word and at least one full stop. Yeah,
we did some work with them on that. Get some case conventions, some naming conventions
and be really picky about what you include. I do this with Redockly CLI, so if you are
using that, feel free to send me questions. If you use something else, I can't answer
your questions, but good luck. Open API documentation. Read the docs for your docs tools. I see a
lot of implementations where those functionalities exist in the tooling that you've used, but
you haven't really dug into what it can do or looked at how you can extend or configure
it. API reference documentation is evolving very quickly in a good way. There's a lot
of new entrants in this market. I'm not sure if I'm supposed to be saying that we have
a new product coming out later in the year that does this. It's beautiful, but you have
lots and lots of options. Whatever you've picked, make sure you're making the most
of it. And if you have something that's, oh, our, I don't want to malign any other tool
families, but something which isn't specialist docs and it can render documentation is a
great way to start. But because you have the open API format, you can use all of one tool
set for one thing, something else for docs, something else for your SDK gen, like lots
and lots of options. Open API, when you publish documentation, your documentation is part
of the product. You should be deploying it often. It should be easy to deploy and redeploy.
And make sure that you're treating it like a web product. Get some metrics, have a look
at what's happening, see what people run into. If you have interactive docs, what are people
calling the same endpoint all the time? Is it super popular or is it super confusing?
Why is everyone here testing this thing? Have a look at those metrics because they can really
help you understand your product. I want to talk a little bit about the open API community.
This is something that I don't always include in my technical open API talks, but as far
as them, it feels appropriate. It's an open standard. It's part of the Linux foundation.
You can get, you can learn more about it on openapis.org. The GitHub repository is public.
Everything happens there. We have a Slack group. It's very active. Also, public to sign
up. And there's a weekly technical meeting. I will confess, it's not super friendly for
Europe. I think it's 6 p.m. Central European time, 5 p.m. for me in the UK. Yeah. I'm trying
to get to a critical mass of EU-based maintainers, and then we need to start mixing that up.
But yeah. If it's unfriendly for Europe, it's sort of dinnertime. There's no hope at all
for anyone east of here. So yeah, we need to fix that. But the open API community is
currently growing its maintainer set. It's working on some new stuff. Like, this is a
good time to get involved. We've also spun up some special interest groups. So just to
kind of tease some of the headline activities within the open API project. The Workflows
special interest group describes a sequence of API calls. So if you have, this has come
from the travel industry. So where you need to find the flights, find the seats, ask the
user, book a seat. None of those make sense by themselves. Workflows aims to give an extra
level of description for that. Overlays is a special interest group that describes repeatable
modifications to an open API. So if you have a generated open API that is just thin, you
don't maintain good examples and good descriptions when you're generating from code, and lots
of organizations struggle to get away from that Java doc workflow. Overlays can help for
now, where you can get your open API and make the same changes every time to make the descriptions
better and add examples, hide things, whatever. Open API 4.0. Code name, Moonwalk, why? Don't
ask. Don't let engineers name things. Open API, Project Moonwalk, is committed to doing
some sort of release this calendar year. So that is just starting. The high level goals
are to give you a really simple upgrade from 3.1 upwards, so 3.0 you might want to go to
3.1, and to include a wider range of HTTP APIs. Open API is amazing for RESTful APIs. Okay
for some other HTTP-ish, RESTful-ish ones. Moonwalk will include the RPCs and a wider
family. So if you've struggled with open API, have another look in about a year. Yeah, open
API, an open standard for API descriptions. If you're not using it, I hope you will now
or feel like it's a thing that you can approach. If you are, maybe I've given you some ideas
to go back and look at what you might change in your current workflow. I'm going to leave you
with some resources and say thank you very much for your time. Okay, I'm allowed to take
two questions. Would anyone like to take a question? Yes. This is a really good question. How do I
feel about generating open API from code or code from open API both ways? Let's start at the
beginning. A lot of organizations generate open API from their back-end server-side code. I don't
like it. And the reason I don't like it is I think when you go code first, you're missing a design
step. When you design first, you're thinking about it in the context of the rest of the API. You're
more likely to get the naming right the first time because that implementation is not done by an
engineer by themselves. So you ideally design first APIs. You propose the change to your open
API with a pull request. You're wise people and you're amazing linting. Go a few iterations to get it
perfect. Then we build it. And that's my ideal and that's why I prefer it. The other question,
generating code from open API? Yes, go for it. I think we have this machine description and there's
a lot of boilerplate. So we can go quite a long way to things like client SDKs from open API. When I
talk about the transform step where you have an open API and you make it better, for docs, you're
going to add examples and descriptions. For API gateways, SDK code gen, that sort of thing, you're
going to add metadata here. You're going to give the type hints that the specific programming languages
and text stacks need. And you're going to give extra information. You might not have that at design
time, but if you think of it as a pipeline that splits off, you might want to add some extra magic from
your standard open API to enhance it before you generate code from it. But generating code is typically
fine. It will only be as good as your description is. And lots of those fields are optional. So cool. I am
out of time. Thank you so much, everyone. I hope to see you during the event.