Full transcript
0:00[Music]
0:05hello my name is lukas guzenstock and
0:07i'm the co-author of the book designing
0:09apis with open api and swagger i'm
0:12excited to be speaking at manning's api
0:15conference and i will talk to you about
0:18from domain model to api an approach to
0:21api design first
0:25hello everyone and welcome to my talk
0:27from domain model to api an approach to
0:29api design first
0:31my name is lucas soderstock and i am a
0:34freelance software developer technical
0:36writer and api consultant
0:39also
0:40i'm co-author of the book designing apis
0:43with swagger and open api
0:46which i'm writing together with josh
0:47ponellat this book is currently in
0:50manning's early access program and will
0:52be available in full very soon
0:56so
0:57let's get started and talk about api
0:59design first
1:01so
1:02if we have an api we want to have an api
1:05definition that describes how this api
1:07works and ideally this api definition is
1:11also machine readable
1:13and
1:14the standard for machine readable api
1:16definitions is open api
1:20now there's one way to use open api and
1:23that is to have an existing api take
1:26your implementation and then either
1:29through auto generation or manually
1:31document that
1:32implementation
1:34as your api definition and then you can
1:37use that open api definition and you can
1:40generate reference documentation using a
1:43tool like swagger ui
1:46however what if we turn that process
1:49around and instead of starting with code
1:52and later create a definition
1:54we started with api design and then from
1:57our api design we create an api
1:59definition
2:01and the advantage of going api design
2:04first
2:05is that we can not only generate the
2:08reference documentation and we can now
2:11do it even before the api exists
2:14we can also use the api definition to
2:18generate some code automatically for
2:20example client sdks
2:22for example server stubs or we can
2:25create a full mock server based on the
2:27api definition
2:29and
2:30we can use that for testing so we can
2:32test whether the code matches the
2:35specification i mean the api definition
2:39so
2:40in this way the api definition becomes
2:43the single source of truth
2:45because the api definition comes first
2:48and then it drives all the other
2:50artifacts and the whole api life cycle
2:54now if we want to go api design first
2:57maybe the first question that we should
2:59look at is
3:00how do we design an api
3:06to
3:07use a practical example
3:09we will start with a web application
3:12called pet sitter
3:13and that's the example which is taken
3:16from our book and
3:18i'm basically presenting you the gist of
3:21two chapters of our book where we
3:22describe this process of
3:25starting a project going api design
3:28first
3:31so
3:32um let me introduce you to uh one of the
3:34protagonists of our book it's um jose
3:37and he's
3:39a dog owner and a big fan of dogs but
3:42because he's busy with his business he
3:43sometimes needs some help and he needs
3:46to hire someone to take his dog for a
3:48walk
3:49and to streamline that process he has
3:52this idea of creating a marketplace
3:54called pet sitter
3:57he
3:58writes down
3:59just like a napkin sketch his idea for a
4:02pet sitter so he says
4:03um on pet sitter people can sign up and
4:06they can either be a dog owner or a dog
4:08walker
4:09and then the dog owners they can post
4:11jobs to the marketplace and the dog
4:13workers they can apply to these posted
4:15jobs
4:18and apart from these functional
4:20requirements he also decides that he
4:22wants to use apis in this project and
4:25more specifically
4:27he wants to build an application with a
4:30separate front end and back end and he
4:33wants to build with a team of one
4:35front-end developer and one back-end
4:37developer and the approach is he wants
4:39to
4:40develop the api api design first as a
4:43team and then each developer can
4:46implement their part separately and
4:48ideally in the end everything works
4:51together because both work on the same
4:54api definition
4:57to
4:59create your api design in the first step
5:01you don't even need open api you don't
5:03even need a computer you can also do
5:05that on a whiteboard
5:06and
5:07what you do
5:08is a process called domain modeling
5:12and the idea behind domain modeling is
5:14that you create software representations
5:16of concepts in the real world
5:20so you look at the
5:22domain of your project and then you
5:24identify the concepts or the nouns that
5:27you have there and then you look at what
5:30kind of attributes do they have
5:32how do they behave what can they do what
5:34can be done to them
5:36and what are the relationships between
5:38those concepts
5:39and once you've collected all this
5:41information and put it together you have
5:43a domain model
5:45and the domain model can be visualized
5:48for example in a uml diagram
5:52which is what we'll do um
5:55so in this is the final which will show
5:57the examples now
6:00so
6:01the pet sitter team starts brainstorming
6:03and they think okay we have an app so
6:06our app has users so user is one of our
6:09concepts and since it's a marketplace
6:13the job is another concept and since
6:16this whole thing is about dogs
6:18we should also put a dog concept into
6:20our domain model
6:22and after identifying these concepts
6:25they add attributes
6:27for example for the user you have things
6:30like an email address and a password
6:32and for jobs you have the time when the
6:34job starts and what is the ex
6:36exact activity that you um
6:39should do and for the dog you have
6:41things like the dog's name the age or
6:43what kind of breed of dog it is
6:49so we've identified concepts and we've
6:51added attributes and now we have to look
6:52at behavior and relationships
6:55and to do that it's very helpful to
6:57write down user stories
6:59and user stories
7:01basically describe from the user's
7:04perspective how they interact with the
7:06software and by writing down user
7:09stories you can
7:11find out okay what kind of behavior and
7:13relationships do we need and
7:16i will
7:17not discuss the user stories
7:20right now because
7:22we have limited time in this talk and i
7:24want to focus on the aspect of going
7:26from domain model to
7:28api design so i will just present you
7:31the final domain model where we have the
7:34user job and dot concepts and while
7:36writing user stories the team realized
7:38okay because people apply to jobs we
7:41should have a job application concept
7:43and all these concepts now have
7:45attributes and they have actions and
7:47there are relationships between them
7:52now the next step is how do we get from
7:55this domain model which we've visualized
7:57in uml
7:58to an api design and then to an api
8:01definition
8:02and actually these aren't two separate
8:05steps we can do this both at once
8:08because
8:09we can take the domain model and we can
8:11directly write down our api design in
8:14open api and so we have the api
8:17definition
8:18but how do we do that
8:21so
8:22we can take the concepts that we've
8:24identified and the attributes and we can
8:26convert them to json schemas
8:30and then we can look at the behavior and
8:33the actions and we can
8:35define operations
8:38so path method combinations
8:40and finally for the relationships
8:43we may have to
8:45change the schemas and add
8:47information and also into the operations
8:50but we'll get to that in a bit
8:53so let's get started with the first
8:56um the json schemas so
9:00on the left side we have the user
9:03concept in our domain model and on the
9:05right side we have the open api file
9:07which contains
9:09a user schema under component schemas
9:11and as you can see
9:13the attributes in the domain model and
9:16the
9:17properties in open api they are the same
9:20the only thing that we did at this point
9:23was adding data types
9:26and
9:29when we look at relationships let's take
9:31another example we have a job concept so
9:34sometimes we um have to add some
9:37properties because we want to um
9:40represent the relationship by putting
9:43its id the idea of the reference
9:45resource as a property
9:47and sometimes we want to make a direct
9:49schema reference because
9:51we want to include
9:53one schema into another
9:57okay so we've got schemas but how do we
10:00design now accrued restful api and
10:04a lot of people when they talk about
10:05restful apis they actually mean this
10:07crude so groot which comes from the
10:11field of database management systems
10:13stands for create read update delete and
10:16that's the basic operations which you
10:18can do on data
10:20and
10:23looking at them in the context of an api
10:26with a crude api we generally have two
10:29types of endpoints so we have collection
10:31endpoints
10:32for all the schemas that we have for
10:34example if we have a user schema we have
10:36um the pluralized noun
10:38users and we have an endpoint
10:41users that's a collection endpoint
10:43and we have resource endpoints uh where
10:46we take the collection endpoint and we
10:48add slash and the identifier of one
10:51specific instance of that schema
10:53and yeah that's the two basic endpoints
10:56that we should have in our api design
10:59and
11:01then we can take these for operations
11:04create read update delete and we can map
11:06them to
11:08http methods so we can use post for
11:11creating and we typically use the
11:13collection endpoint for that because
11:15we're adding something to the collection
11:17um we can read and we can read the
11:19collection endpoint where we get
11:22a list of
11:23items and we can access an individual
11:25resource and if we want to change or
11:28delete a resource we can use the put
11:31patch and delete verbs on the resource
11:34endpoint
11:37so
11:37let's take an example look at the user
11:40concept
11:41so um i'm skipping the login action here
11:44because it doesn't directly map to these
11:46crew things and
11:48we don't necessarily need it here
11:50because we'll take care of
11:52authentication in different ways so i'm
11:54so let's let's just skip this and look
11:56at the four other actions and what you
11:59can see here is that
12:01there's a very good mapping between the
12:02actions and the crude verbs for example
12:05register
12:06when we register a user gets created so
12:09register is actually our create action
12:12and so we have post slash users
12:14and
12:16we have
12:17view modify and delete and those map to
12:20read update and delete and we use the
12:22resource endpoint for this
12:25so this is pretty straightforward and
12:28when we look at the job this time i'm
12:30skipping create modify and delete
12:32because again it's it's the same
12:35it's the same thing but what i'm showing
12:37you here is that
12:39we have three different actions and they
12:41are all read
12:43in crude so
12:45but they map to different endpoints so
12:48we have list all that's the collection
12:50endpoint we have a view for a specific
12:53job that's the resource endpoint
12:55and we have list my own
12:57and here we actually take that action
13:00and we generalize it a bit and say okay
13:02listing my own jobs that's a specific
13:05case of listing jobs for a particular
13:07user
13:08and we can add something else to our api
13:10design which is called a subresource
13:12collection endpoint where after
13:16after one
13:18schema types so users and the resource
13:21endpoint for with special user we add
13:24another schema for
13:25a related
13:27we add another um
13:29related schema yes
13:32and the next question is okay so we have
13:35these operations but what should be the
13:37input and output the request and the
13:39response for these and here we can reuse
13:43the schemas that we created before and
13:45very often we don't have to do a much
13:47else for example for create job we can
13:50use the job schema which we reference
13:52here from the component section
13:55as our request body
13:57and
13:58this is
14:00the action list jobs for users
14:02and as you can see here we have a
14:05response body where we have a schema
14:08and
14:09that schema has an items array and
14:12inside that items array again we
14:13reference the same job schema so we can
14:16we can reuse our schemas everywhere in
14:18the api and the api remains consistent
14:23sometimes we have to think a little bit
14:25out of the box though
14:26so
14:27creating a job application that's again
14:30straightforward but what does it mean to
14:32approve a job application
14:35but
14:36yet again we can very often for these
14:38actions map them to
14:40the crude paradigm by saying okay
14:43what does a proof mean
14:44approving a job application means
14:47changing its status from
14:49let's say applying
14:50to approve and by that
14:53logic we have
14:55created or we have mapped the approve
14:57action to
14:59an update verb and we can
15:01use it in our same consistent
15:04crude approach
15:06so
15:07let me summarize so
15:10when we want to go from domain model to
15:12api
15:13we can
15:15generally convert all our domain model
15:17concepts into json schemas in our open
15:20api file
15:21and these are reusable
15:23in different areas of the api for
15:25requests for responses for being
15:27referenced in other schemas
15:31we can generally to have a consistent
15:33architecture we can use
15:35resource and collection endpoints as our
15:37operation paths
15:39we may not need to add all of them but
15:41for the schemas where we have actions
15:43that need them we can add those paths
15:45and then um
15:47by having the crude actions create read
15:49update delete which roughly mapped to
15:52http verbs
15:54we can look at all the actions in our
15:56concepts and try to interpret it as one
15:58of these and based on that
16:00add it to our api design
16:04and
16:05that's all from my site thank you and
16:08let's stay in touch if you want to talk
16:10more about api design
16:12you can reach out or follow me on
16:14twitter my handle is at lucas rosenstock