[MUSIC PLAYING] MARSH GARDINER: Hi, my
name is Marsh Gardiner. I'm a product
manager for Google. I tend to work on
Apigee's developer portals and Google Cloud
Endpoints' portals as well. I also work on our
open API-based tooling, and represent Google on the
governing board for the Open API Initiative, and chair
the marketing group, and serve on the Technical
Steering Committee that guides the evolution of the spec. Just a reminder, this is
better API design with OpenAPI. This is an intro
level discussion. We're not going to get
deep into the weeds on how the specification works. But we will talk specs a lot. In general, we're going
to cover four areas. One, I'll give you a bit of
a background on OpenAPI Two, we'll review specifications
and how they work throughout the API lifecycle. Three, we'll cover some
basic API design principles. And that will set us up
to combine all of these so that we can talk about
how OpenAPI's opinions guide, somewhat, API design and
the choices you have to make. There's a spoiler. OpenAPI is not going
to magically make your API awesome. But it can help. And hopefully, by
the end of this, you have a bit of an
understanding about how that helps and why it matters. Who here uses OpenAPI in
their organizations today? Great. Who's thinking
about using OpenAPI? Good. Who here still calls it Swagger? Be honest. Let's see the hands. Well, it's my marketing
hat on for OpenAPI. One of our challenges
is to get people to use the name
OpenAPI when referring to the specifications. Swagger still means the tools. And that is still a
perfectly appropriate way to talk about the tooling
that SmartBear oversees. But the specification,
it's important that we use the right name
because this is an industry format, an industry standard. But behavior change is hard. The good news is those were
fewer hands than last year by percentages. So I think we're
making progress. So briefly, to set the stage,
before we had this thing called Swagger. The state-of-the-art back
in 2010 was still WADL, the Web Application
Description Language, and WSDL for SOAP APIs. They'd been around awhile, and
they were pretty successful. But there were also
XML-based formats. Because of JSON
and JavaScript, we began to see the rise of
JSON-based APIs over HTTP. And it kind of sucks to describe
JSON-based APIs using XML. And in 2010, a couple
of us at Apigee took note of a new API
documentation approach that a company
called Wordnik was pioneering for their own APIs. And we thought it
was pretty cool. So we reached out to them,
which began a conversation in an Apigee office
about whether they would be interested in Creative
Commons licensing, the look and feel of their
API documentation. And to our surprise,
they said, actually, we're thinking of open
sourcing all our tools. We thought that
sounded pretty great. And we talked and
laughed about how much it sucks to describe
JSON-based APIs with XML. And I think was
Zeke who said, why waddle when you can swagger? And we all laughed and
thought that was funny. And then someone said, actually,
that'd make a great name. And so it began. Wordnik had created all of these
tools to serve their own needs. And so in the beginning, for
instance, the description format that they'd
created, you couldn't specify how you would do
authentic authorization. Obviously, other
people needed that. And so as the community
began to participate, the format began to
become more descriptive. It was also very much bottom-up. It was one company trying
to solve their own problems with software. And it wasn't a
vendor saying, I think everyone should do it this
way or a consortium saying, hey, everybody, like so. So it had real
authenticity about it. It was solving real
problems for real people. And it grew organically
over the next few years. And then in 2014, that
was about the time where we were at Apigee,
getting kind of tired of using WADL as our preferred format. And we took a survey to
see how the API description landscape looked. We still really liked
what Swagger was doing. And so we approached Tony
and suggested perhaps it was time to consider a
major revision to the spec. And that kicked off
a working group. It introduced things
like the YAML format, at the time, Swagger
specifications. It did things, like
it added a single file expression of a spec. Before that, there were others,
a bastardized version you could do that was embarrassing. It was really multi-file format. And it turned out to be a pain
when you wanted to do things like create an editor to
make it easy to create a spec in a browser. It also added things. We called them, at the
time, vendor extensions. Those would be renamed
specification extensions later. But really, it's because
we were realizing that, as providers,
we needed a way to mix in a bunch of
implementation details. So that's an
important piece here is that the Swagger
specification grew really as a way to document the
contract for clients. But there was this interesting
tension between the fact that while it's
client first, it's also really useful
to the server side and how providers are
describing their own services for their own needs in the back. I'm going to talk about
that a bit more later. And we began to see
with the 2.0 spec, it was like the world
was waiting for it. And I'll show you that
in a slide in a second. It began to take off. It also became more
important to get it into a neutrally-governed
foundation. And along the way, Wordnik
sold some of its interests in Swagger to SmartBear and some
its other technologies to NDN. And it became even
more important that if this was going to
be an industry standard, it had to have
neutral governance. And so the Open API
Initiative was founded. The spec was contributed
by SmartBear. And all of that
led to figuring out the right structure and
organization for how we would evolve the spec. And that all led to
the Open API version 3 specification, which took
a lot longer than anybody had planned. It took us a lot of time. And that was released
about a year ago. And since then, we've
seen tooling adopting it. And it's starting to get some
pretty good momentum around it. This is why. You can see, in
2014, when we started the working group,
that's when interest began to really take off. It continued to accelerate as
we added the neutral governance model around all of this. It's like the world
was waiting for this. And I stopped tracking
these numbers. This is the Stack Overflow tag
trends for the various formats as of 2017. OpenAPI just continued
to accelerate. And part of that is because
of this governance model. So for those of you who
are really interested, you can go read all about how
the inner workings of this happen. But it's pretty interesting. I had never gone through
this process before. How do you take this
open source project and make it a safe
space for lots of people to participate in? And that means doing things like
incorporating, and making sure that everyone's assets
are properly protected, and there's a level
playing field for folks. It's pretty interesting stuff. So we became a project
of the Linux Foundation and continue to this day
under their auspices. And we have all of these
guidelines and charters. If you're really
excited about this, you can read this
on OpenAPIs.org. We grew from an original
founding members of 9. We're now, I think, at 32, with
a pretty impressive collection of logos. These are all the members
in the OpenAPI Initiative-- everything from Big,
Salesforce, Google, IBM, Microsoft down to
small players, who are focused more on narrow
sections of tooling. But it's pretty robust,
and it continues to grow. The reason why all these people
came together to work on this is because having a common
industry format to describe APIs, it's really important
to a lot of people and the industry as a whole. And this is why I said earlier,
using the specification name OpenAPI really does matter. It's important that this thing
be able to live on its own. And I think it's
been doing great. We have more work to do. The specification itself evolves
and is maintained on GitHub. So if you want to read
through the specification, or participate, or ask
questions, or file issues, this is a great place to go. And all of this is guided by the
Technical Steering Committee. We started as six,
shrank down to four, and we're back up to six again. We meet once a week, in general,
for about an hour and a half. That's an open
meeting, except when we have to deal with
internal governance issues. These happen on Thursdays. And they're open to anyone. You can actually
find the calendar through the GitHub repo. We have all this
documented in how you can participate in the
development guidelines, et cetera. That's me. I thought it was
really cool in 2007 to be trapped inside an iPhone. And I just haven't
updated my avatar. So the purpose of this body
is really to govern the spec. It's important to consider
the burden on tooling authors when you're making
changes to the spec. Because any time
you add something, it's more work for people to
do, or if you make a change and now, things
are incompatible. Really, the way the spec evolves
is by the community needs. But someone has to
make sure that it's evolving at the right pace. And that's what we do. But also, it's work-like,
writing requests to make changes to
the specification, clarifying things along the way. If you get excited about
API description formats, you should come
talk to us and join. Right now, we're meeting on
Thursdays in the morning. So we've had the 3.0
spec out for a year. And we spent some of
that time thinking about how to better
involve the community, how to have clearer
practices and guidelines for participation. We also have a big
list of possibilities. And we've spent a lot over of
the last few months talking about these things. I promised earlier I
wouldn't dig too deep into the specification,
but these are the kinds of things
that we're thinking about. And this is really what we need
input from the community for. So again, things
like reusable groups. That's the idea that you
could define things and refer back to them with being able
to write less boilerplate over and over. Things like alternative
schemas, if you don't want to use
JSON schema, or even if you want to use a
newer version of JSON schema other than the one
we support officially. Those are things that
we're considering. We've talked about
adding multisecond paths. Actually, I'm super-excited
about overlays. That's the idea that
you could separate some of the
implementation concerns from the specification itself. So rather than mixing in all of
your specification extensions, those implementation
level details, to be able to have a
separate file that you can think of as a layer on top,
you would merge those down. Again, I would
encourage anybody who's interested in these things
to please participate. It's the community involvement
that makes us move. These are the various
ways you can contribute. So I would recommend visiting
the project on GitHub. There are issues you could
file or participate in, pull requests. We have lots of passionate
arguments about things. I would recommend reading
the development guidelines that you apply your changes
against the right branch, that kind of thing. We have that weekly conference
call that I mentioned. We have meet-ups. And if you want to join
them or even host them, you should please
get in touch with us. The easiest way to do that is
via OpenAPI Spec on Twitter. That's probably the easiest
way to quickly reach out to us. But things look pretty good
and please participate. Part 2-- specifications
in the API lifecycle. So contracts-- OpenAPI is
really a contract-based approach to things. And really, this is an
agreement between the client and the server. So the server says,
hey, this is the way I want people to talk to me. And if you talk to
me, I can promise that I'm going to
be somewhat stable and be around for awhile. And the client's like,
hey, that's cool. And so you register
an application. And you are able to make
requests against that. But I really do think of
it as this formal contract and agreement between
these two sides. I'm going to ask you to
use your imagination. This is, as you can tell, in
the style of Homer Simpson. But Legal would not let me use
Homer Simpson in my slides. So mentally substitute
this with Homer Simpson, because apparently that's OK. Sweet, sweet declarative,
compile-time contracts. I actually imagine
myself as Homer Simpson when I think about
OpenAPI in this way. What it is, is I love that
you're so declarative, you can understand all the
various capabilities of an API. It's very declarative. And what I mean
by compile time is that, as you build
your application, the interface is hardened. You compare this to things
like HATEOAS, Hypertext As The Engine Of
Application State, where the client
can only do what the server says is allowable
from the state that you're in. This is much more declarative. And you can think
of it as slices of functionality that you can
expect will work in this way consistently. A contract defines the
boundary of responsibility. And they're great because
this formal agreement lets the client and server teams
understand the expected behaviors so that I
know what to expect back when I ask in this way. Contracts have been
around for a long time. I've already mentioned
WSDL and WADL. Before that, we had
things like CORBA. And we've had other
contracts as well. There are different flavors. I'm going to mention
HATEOAS before GraphQL. But what I like about
OpenAPI, as I mentioned, is its declarative nature. And as I mentioned
earlier, it really grew out of putting
the client first. What is it that people
are going to know in order to be able to call my API? Google doesn't use
OpenAPI for its own APIs. Why? Well, Google runs things
at really big scale. And Google needs to have
a binary-based format. And so they use proto buffers. And they have open sourced
something called GRPC. And if you come
in within a couple of orders of magnitude
of Google scale, you might consider it too. But we also recognize
that exposing our APIs with JSON flavors is important. So we have a gateway
that sits in front. And it basically takes
that GRPC and exposes it as JSON over HTTP. Most of our APIs can be
expressed as open API in that way. The way I think about this is
that if you like contracts, and you've got scale
problems, GRPC is a great fit. If you have adoption problems,
I would go with OpenAPI. If any of you have attended
any of Apigee's sessions before, you've probably
seen a slide like this that is how we think about the
API lifecycle in general, the core lifecycle being
those icons in the center. And this covers a lot. And if you ever look at Kin
Lane, the API Evangelist site, he's got pretty similar lists. API management's has
been around for awhile. These categories
are pretty good. It looks like people
want pictures. Wait one second. 3, 2, 1. Good. I want to focus on just
the core lifecycle bits. This is everything from
imagining and designing your APIs through
deploying, publishing, and maintaining those,
analyzing that traffic and how you then
maintain it over time, protect against threats,
real-time monitoring. But what's interesting to me
is how many of these stages are better informed
by specifications. They add value in lots
of different stages of the lifecycle. And I'll walk you through
a couple of these just to give you a flavor
of what that is. Documentation is the
most obvious one. For many years, people
thought Swagger was Swagger UI just because they'd
see the documentation and think that was it. It was really a much
deeper and layered system. But specs-driving documentation
is the number one reason that gets people to
write specifications, in my experience. Everyone understands that
in order for a developer to consume your API, they have
to understand how it works. They need documentation. Maintaining
documentation is a pain. And doing that by hand
is kind of even worse. And whether you treat
your API specifications as truth or possible truth--
and what I mean by that is, say you're generating your API
specifications from annotations in your source code. You can consider that to
be truth, more or less. If you write that description
and maintain it out-of-band, it is a description
of a possible truth. It may be just as true as the
ones driven from annotations. But in the case where you're
writing it out-of-band, that's where you may want to
do automated tests to make sure that your specification
stays, in fact, in line with what you're actually
exposing with your APIs. So specs-driving documentation
is the single biggest reason to use an OpenAPI spec today. But there are lots of others. So we use specs. This is in Apigee Edge. When you go to create a proxy,
which you do, essentially, in order to be able to
attach policies to control as a part of API management,
how you control traffic and access to the services
that you're offering, if you have described
your API using OpenAPI, we can use that information
to help you figure out how to manage your API. Specs also can inform
implementations you may generate code in the
back end, whether it's stubs, or whether it's something
more sophisticated. Specs can drive mocks. This one seems
obvious in many ways. But it's surprising
how few organizations take advantage of it. The nice thing
about driving mocks is it lets you start building
your client in parallel with the server implementation. That's a pretty good
benefit right there. Now, you don't have to
wait for the server to get stood up before you can
begin to build your client. It also is a good way to
just put it through its paces as you're in the design phase. Or say you're a financial
services company, and you don't want
your developers making live requests to your
actual production backends. You could attach that to a mock. And have them send requests
without using real money. More sophisticated,
of course, would be to have a parallel system
that didn't use real money. But this is a good way to start. Specs can also power
test generation. Here is a snapshot of a project
from a colleague of mine, Noah Deitz. He has a project
called OATTs, which is OpenAPI Test Templates. These are ways in which you
can make assertions and run automated tests that
help keep your API specification in line with
what you're actually doing. It's pretty neat. I encourage you to check it out. You could use specifications
to classify traffic at runtime or to validate
payloads at runtime. I mentioned earlier
generating SDKs for clients or to
do server side code. There's a lot that specs do. But given that this
talk is about API design and how that OpenAPI
influences it and its opinions, I want to really
talk about this. This is the spec
editor in Apigee Edge. But you've probably seen lots
of these out in the wild. As you incorporate
specifications early in your process,
you get better APIs. I'm going to talk
about this a lot more for the rest of the talk. But being able to design
and see your API-- when I go back to 2014
when we started the working group for Swagger 2,
people didn't actually understand at the time why
having a YAML-based syntax mattered. And it matters, so we
can do things like this. The ability to write
in a web browser a specification,
that's a big deal. And the ability to get
real-time documentation, this is like
documentation-driven development. And it's a way in which you can
make better APIs before you've even written a line of code. So before we go into the
OpenAPI influence on API design, I want to review some
key API design principles that we will then apply to
that and bring it all together. Did anybody read this book? It's been out for awhile. I see a few hands. Good. I would encourage you to. You can find this on
our website, Apigee.com. Even though it was
published in 2012, it continues to be
really relevant. It's been cited
by organizations, like whitehouse.gov
in the Obama years. It continues to influence
a lot of thinking. And it's a pretty simple
pragmatic approach to building interfaces
that developers love. And a number of the examples
that I'm going to pull come from this. And this was really gathered
from collecting the patterns that we were seeing that we
were working with our customers and working out in the wild and
then synthesizing that down. So it's an evidence-based
approach to API design. There are four
patterns from this that I want to call out today. If you want more,
please read the book. But one, reuse, don't reinvent. Obvious. Again, these are all
basically common sense. That's all design is really is
common sense and creativity. Two, resource-oriented. And when I say that,
I mean the R in URL. Three, I'm going to
talk about names and why they are so critically
important in this area. Then four, just a general
principle-- when in doubt, do what's best for developers. And by that, I mean
your consumers. Reuse, don't reinvent. Web technologies-- when we
talk about web API design, for me, the first web API that
I saw and fell in love with was Twitter sometime
in 2007, I would say. And what was amazing
to me about Twitter was that I understood
how to use their web service, the actual
website, and use Twitter as a user of their
web interface. But switching from that to
their API was really easy. Back then, you could use
your basic authentication. The same credentials you were
using to sign into to the site, you would use to
sign your requests. And the way they'd
organize their API was very similar
in its hierarchy to how their website
had been designed. I mean, that's not an accident. And so it was just so
amazing and beautiful to me that I could get at
my data, not just in the way that they said
I could, but in the way that I wanted to. And a lot of what made the web
work is what makes web APIs work too. So JavaScript is the
lingua Franca of the web. It is why JSON emerged as a
rival and successor to XML. So JSON is a key
piece of web APIs. And HTTP is another great thing. If you think back to right
before this style of JSON over HTP came out, everyone
was doing RPC, more or less. And that's perfectly fine. It just wasn't leveraging what
was really great about the web. It was tunneling
a bunch of things, like the actions
through the payload. And by using what makes HTP and
the web great, we got web APIs. And that's important
enough to call out they are resource-oriented. So if you use the
web, you understand that things have locations. And this is why it
was so easy for me when I first got into APIs
and web APIs through Twitter, it was because I already
understood how the web worked. I knew that oh, you go to a
blog, and there are posts, and then posts are entities. This kind of hierarchy is
reflected in good URL design. And it just makes it easy to
think about how the site works and how to take the
context of the service and apply it to how
you access its data. It's tremendously powerful. You don't have to teach the
basic mechanisms of accessing data and functionality. This is third actually-- naming. So this is one of my favorite
quotes in computer science by Phil Karlton. "There are only two hard
things in computer science-- cache invalidation
and naming things." There's a version of this
that wasn't from Phil. Apologies to Phil. "There are two hard problems
in computer science-- cache validation, naming things,
and off-by-one errors." But naming-- think how hard
it is to create a good user interface that's a UI. It takes a lot of
design and rework even before you
write a line of code. APIs are no different than that. So all you have is URL
safe characters, really, to deal with when you're working
with your resource design. This means that the names of
things have really great power. And one of the things I
like to do in API design is to involve my tech
writers because you really want people who actually care
and think about words a lot. And so not only do
tech writers spend a lot of time trying
to think about how to break complicated things down
to make them easy for people who are approaching
a subject area, but they also tend to know a lot
about other parts of your API. And so they can help you
keep your API consistent. And the third bit, this is what
I just alluded to a minute ago, is that they care about words. Think about how hard it is
to name a variable well. That's hard. Anybody here play
Adventureland or Zork? I'm dating myself here. Oh, no. Wow. Anyway, I don't have time
to do a demo of that. But if you're familiar with
it, you were in a room. You see a lamp on a table,
and you say, get lamp. And to me, when I'm designing
an API, I'm thinking about that. How do I make it
obvious from these words how you work with this system? The way I think about it
is that your developers are taking a journey
through your API that's not unlike Zork. And all you have to
work with is text. And it's your job to keep them
from being eaten by a Grue. It'd be a funnier joke
if you'd all played. God! Anyway, so you have one job. The API's job is to
make the developer as successful as possible. The orientation for APIs is
to think about design choices from the application
developer's point-of-view. If you look in the
lower right-hand corner of this little
blue section, this is the Japanese
expression of Shoshin. My apologies if I'm
saying it poorly. I don't speak Japanese. But Shoshin, it's the
concept of beginner's mind. It's a Zen concept. So the example I like
to give here is-- who knows what IMEI stands for? Wow, I expected more telco
people in the audience today. It's the International
Mobile Equipment Identity. If you look in your
phone's settings, you'll probably see
your IMEI number. When I saw my first telco-based
API, I thought, what's that? It's a device ID. It's that curse of
knowledge that you have and that's really hard
to step outside of. And that's why taking API
design to other people is really important,
specifically people who are
possible developers outside your organization
and understand how they see the
words that you've chosen because it is difficult
to avoid the bad ones. So Shoshin, the beginner's
mind is another place I'd like to go when
designing APIs. So now that we've touched
on specifications, why they matter, why OpenAPI
is important, and basic design principles, we can
put them all together. But as I started
with, just remember, OpenAPI is not going
to magically make your API awesome. But it does have some opinions. And I find it's a whole lot
easier to work with them than to fight them. And this matters whether you
are building micro services, or whether you're building
full-blown public API programs. So in the rest of this
talk, we'll cover-- and I'll make sure there's
time for questions-- we'll cover these six ways
that OpenAPI guides API design. One, JSON. We'll use JSON schema. You'll see why that
matters in a second. I'm going to walk you through
each of these in detail. Two, signatures-- how
the signature mechanism works in OpenAPI and
why that's important. Three, warning, do not
vary your response models from parameters. Four, collections
and entities are a nice pattern and a good fit. That's from the
API design e-book that I mentioned earlier. Five, versioning and how you
can approach it with OpenAPI. And six, defaults
and pagination. So OpenAPI leverages
JSON schema. And it was in a draft at the
time that we launched v3. And in fact, we were
a little worried that it was a dead end
of a specification. But it's been revived
a lot recently. But we picked a draft, and
we can't just update it without breaking things. That's why when I talked about
the big list of possibilities, it's on there. But we didn't take JSON
schema entirely as is. One difference between
version 2 and version 3 is that we added any
of and one of to that. That had been a common request. But what's important
to remember, and one of the challenges you
face in working with OpenAPI is that, really, JSON schema is
a validation language and not a modeling language. And if you remember that, it
will help you on your journey. Two, anyone recognize this? When I think of
a signature, it's John Hancock's, the one
that springs to mind, that big one in the center. But if you look really closely,
you can see path and verb. A lot of people don't
realize that OpenAPI also signed the Declaration of
Independence. (WHISPERS) It's not true. (NORMAL VOICE) It is a unique
pairing of a path and a verb that really defines the core
of what's in an OpenAPI spec. That is its signature. And what I mean by that
is that if I'm a gateway, and there's traffic
passing through, then I should be
able to identify, based on what I know from the
specification, which operation it maps onto in that spec. That's the signature mechanism. I kind of cheated
the plus media type. I didn't let them sign. If you are going to have
multiple media types, you can use that as a way-- it's next layer of signature. But path and verb-- if you think in terms of
path and verb, it will help. Number two, don't vary
response models by parameter. I've tried to protect the-- I shouldn't say guilty. This API came about,
I think, around 2006. So it predates a lot of things. But you can see that
what we have here is-- where is it? There we go. Oh, I put it in red. Good. The method equals. You are passing in
what the signature is in the query string. And because that can appear
anywhere in the query string, it can be a lot
harder to figure out what the signature
mechanism is if you're in a layered system
like a proxy. When Wordnik set out to build
their own stack for APIs, they wanted to have a nice
clean signature mechanism. And that's why we have
the legacy that we have today of path and verb. And that's a perfectly
good way to do things. That's basically the
way the web works. So just a warning, don't vary
response models by parameters. It's funny. This is one of the things that
comes up a lot in the community requests for how the next
edition of the spec should go. And we continue to
resist it, in part, because it adds another
burden on tooling authors, as I said before. Three, I think we're up to-- collections and entities. And so what I mean by
this is, like, /dogs, or this could be /posts. That is the collection. And then you've got the
specific entity there. So if I've got /dogs,
and I do a post to /dogs, I'm creating a new dog entity. And I will get back a
unique ID that defines that and that specific dog entity. And then I can do
things like update it, or delete it, or get it. And so collections and
entities are a really nice way to represent the
hierarchy of your system. And it's a way in which you can
use the names of those entities to help people understand
how to work with your APIs. It's also useful
for API management. Because now, because I've
got the signature mechanism and because I've got this
way in which I can think about the structure
hierarchically, I can then apply policies
to specific areas. Say I want to throttle-- maybe throttle and dogs is the
wrong word to put together-- say I want to throttle
dogs but not cats. I could decide to do that
because I have these kinds of-- I think I need a better
example than that next time. Sorry, PETA. Another useful thing
that I probably should have mentioned
during the naming bit is the singleton resource. Imagine this was users. And users 1, 2, 3,
4 happened to be me. Having a /me-- and I
forget who pioneered that. Facebook was early
on that pattern. But it's nice to have these
convenience singleton methods that map onto these things. And you can still apply policies
in the same way to that. Versioning-- nothing causes
more controversy in API design than versioning. And I'm here to
give you permission to do versioning the way
you think is right for you. However, do think what's
best for your developers. I remember when Facebook used--
hopefully, they don't do this anymore-- but it used to be
able to pass in the version you wanted in the query string. And people always
forgot to do that. And things would break. The downside of
versioning in the resource is that it feels kind of
wrong to version the resource. But it's also obvious. And so you have to
figure out what's right for your developers
and make that trade-off. But what I wanted to talk
about is the way in which OpenAPI has opinions here. So one of the things we
added in the version 3 of the specification is the
servers replace the host. And we added a way in which
to templatize that server. So you can, in fact, in
your server's information, you can put the version. Used to be able to do
that with a base URL. Now, you can do it in
the servers as well. The only caveat I would give
here and something to be careful of is that
it may be that you want a separate specification. If you're putting
versions in your servers, you might as well think of
those as different contracts because someday, you're
going to retire one of them. But if you choose to
do the Twilio style, if I remember correctly,
Twilio has got at least 60-- it's probably got,
like, 100 now. But they have a lot of
versions that they keep. And that works for them. And they use a date-based
format to do that. So I give you permission
to use what works for you. But do look at what's
worked for other people. Defaults and
pagination-- again, I think this comes back to naming. Make good choices in
how you name things. We took a look around and
saw a bunch of patterns. I think my least favorite
was Twitter's, at the time. It was RPP, which stood
for Request Per Page. And that's just not
intuitive, right? Limit and offset are
nice because people who use databases are familiar. This is common language. But with OpenAPI, at
least, what I really want is a consistent way
to apply pagination to all of my collections. And the ability to
define that in one spot and reuse that definition
over and over again is really important. The pagination is
actually a great place to use hypermedia too. I think it's the most
obvious case for hypermedia. If you can give
people back a link to the next page of results,
consider doing that. And you should be able to
do those kinds of things using OpenAPI. So here are your
three takeaways, then I'm going to open
this up to some questions. One, investing in API design,
it always pays benefits. Its so much easier
to make a change early in that process
than to do it later. We all know this, and yet, we
continue to push it off and not do it properly. Invest in API design,
even using specifications to help that process go better. Two, the promise of specs-- by having a formal
machine-friendly description of your services, you will
do less work over time. Levering specifications
throughout the lifecycle will help you do less work. Yay. And the third bit is don't
fight OpenAPI's opinions, if you're going down
the OpenAPI route. Hopefully, you have a
better understanding of some of the ways in
which it sees the world. I'm going to add a
number four, which is please call it OpenAPI. It's important for the standard. [MUSIC PLAYING]
