Up next in 10
Design-first APIs with OpenAPI spec by Nano Vazquez || React Virtual Conference
14K views
Nov 9, 2023
Ready to learn new stuff? If today you are modeling APIs using Google docs, this talk IS FOR YOU. You’ll learn how to design your APIs from scratch with OAS/Swagger, and all the bonuses you could get for free without adding a single line of code: a mocking service, auto-generated code & docs, API testing, and so on. About Speaker: Full-stack developer with 15+ years of experience in software development. International speaker. Microsoft MVP. Co-organizer of React in BA, vOpen Tech and DevDayAR. Currently working as a Principal Software Engineer for MuleSoft, a company that provides software for integrating services and applications. C# Corner - Community of Software and Data Developers https://www.c-sharpcorner.com
View Video Transcript
0:00
Hi everyone, I'm super excited to be here
0:04
And as I mentioned earlier, we're going to talk a little bit about the same first APIs
0:09
We're going to focus on OPN API spec, which is just one of the different ways to do it
0:15
But I believe that it's going to be super helpful for you to start with this
0:20
And if you know something that does the same job, it's actually good to learn something new
0:28
So let's get started. So as I mentioned, I believe this is the key message of this talk
0:37
This is what I learned in multiple projects. The biggest challenge to solve is not only the knowledge
0:44
It's also communication. And most of the time, communication is the main thing to solve in a technical project
0:52
So the idea of this talk is to give you tools to focus on that
0:56
and since we are geeks, we like to solve technological challenges. We're going to use technology for it
1:02
So let's get started. Some useful links for you. This is the first one is a link to the presentation
1:08
So if you want to go through it on your laptop, you can click on that link
1:14
And also you can review the slides later. And also there's a workshop that is about this presentation
1:22
It's not 100% accurate. And actually you may find some bugs, but it's a GitHub repo
1:28
So if you find any bugs, feel free to send the PR. And they're gonna be linked to her
1:33
So the next level, I mean, I'm working on the second phase of this workshop
1:37
and it's gonna be super helpful if you guys wanna send me something
1:41
like a pull request or an issue or something to improve. Now, a little bit about me
1:48
I'm a full-time developer as I mentioned earlier. I'm an international speaker
1:52
I really like to talk. Although English is not my first language, I really like to learn and try to be the best speaker about a particular topic
2:06
And for that, I need to talk with more people and I need to share what I know and listen to a lot of people
2:15
So that's why I'm here. I recently changed the companies and now I work as an engineering manager at Modo
2:22
but this is brand new, it's like this is my first week in model so that's why we
2:27
talked about MuleSoft first and now I'm mentioning that but you may want to
2:33
ask me, if you want to know more about MuleSoft, you can also pick me and I'm
2:37
gonna do my best to help you with that. As I mentioned earlier, I'm a Microsoft MVP
2:43
and co-organizing multiple conferences and I'm gonna go and mention all of them
2:47
because you have a screenshot here but if you want to know more, feel free to
2:51
to contact me using Twitter and I can expand more on this
2:56
All right, so let's talk about the scenario. And I want to mention the scenario
3:01
because I really believe that when we build something, we need to focus on what we wanna achieve
3:06
And that means what are the objectives of the things that we're doing
3:11
and most precisely, what are we trying to solve? So for that, the first thing you need to understand
3:17
is the scenario you're at. And that's why I'm gonna try to cover it
3:23
It is a sample scenario, but it's something that we did. Actually, it is a real life example
3:27
So the idea of this presentation is to talk about this real application
3:33
This is the V Open Tech website. And the reason why I mentioned in this particular example
3:41
is because when we created this conference, V Open, we decided to make it a Latin American conference
3:49
that is held in multiple countries. We're talking about four countries right now
3:53
Of course, given the situation we have this year, we're going to have a virtual conference this year
3:58
but last year we had the event in Argentina and Uruguay. And next year we're planning to have it in Argentina, Uruguay, Chile
4:06
Colombia, and Mexico. So this is how big this conference is. And since we are talking with multiple local communities
4:17
we want to make this collaborative and open source. And that's why we decided to spin up an API
4:23
to gather all the information of all the conferences around the Latin America, and also website
4:29
And that's how big this is. And of course, we have a mobile application
4:34
that is used during the conference. It is not only an application for attendees
4:38
it's also an application for organizers and for sponsors. So everything is centralized in an API
4:46
And the idea of today is that we're gonna talk a little bit about a few functionalities to
4:52
figure out how we can do this in the real life, how we do this in the real life. So let's get into it
4:58
Now, I mentioned earlier the team is composed of different people working remotely with different
5:05
cultural differences, but it's not reality differences. It's like they have a different way
5:13
of approaching the same problem. And the idea is that because we are remote
5:20
it's always hard to try to sync up. So usually when you are working in the same office
5:27
you can approach that person directly and ask the question right away
5:31
But when you are remote, and we know this because of this year
5:35
it's harder. So it's not as simple as it seems. Now, what about the use cases
5:41
So the idea is that we're going to cover three use cases today
5:45
but of course, it spans to more use cases. The idea is that this API or the thing that we're going to build
5:52
is going to retrieve all the speakers of a particular conference. Let's say we're talking about the conference in Argentina
5:58
So we can configure our API in a way that it receives a country, Argentina
6:03
and it retrieves all the speakers of the Argentina conference and the edition of this year, right
6:11
because we have multiple editions, one per year. Now, the same way we wanna see all the activities
6:18
of a particular conference. Again, the Argentina conference in 2019, let's say
6:22
And that is gonna be used by the website to list the agenda, but also to the mobile application
6:27
when I use it to display the same information, but it is for me. As I mentioned, this is important
6:34
And also the agenda covers speakers and activities. And that's why I wanted to mention this first
6:39
because you usually beat something on top of small things. And that's what we're gonna try to discover today
6:48
And last, the idea is that when you have the agenda and you attend to a particular presentation like this one
6:55
we wanted to get early feedback from the attendees. And that's why we added some right endpoints
7:02
to post information about the feedback, right? And I'm talking about REST
7:07
probably I said posting on purpose, but I want to add into it if you don't know what I meant
7:12
I'm gonna try to explain it. Now, since we kind of raised our hands
7:18
but let's try to do a quick exercise. The idea is that I'm gonna mention
7:22
different ways of doing this. We gonna try to find the best way of doing this with less effort right Because we kind of lazy developers and we don want to do a lot of work manually We want to automate everything So let get into it
7:35
So the first approach, right? Raise your hands, the ones that have pasted this before, right
7:43
Have you heard this before? Somebody is telling you, hey, can you send me a document of your service
7:49
When I say docs, I'm talking about the document, right? It could be a real physical document
7:54
and that cannot be done if you're working remote so that doesn't work also we're talking about
7:59
Google Docs so let's say Google Docs is the answer right what's the problem what's the problem with
8:06
it right let's say you don't have it and the answer usually is just use it just use my service
8:14
you will always tell you what you need to do or how you can integrate with my service if you just
8:18
Now, that's kind of a problem, right? Because maybe by just using it is not enough
8:27
And what happens if the service is down? So the next step is, okay, I'm going to give you the doc
8:32
I don't need a Google doc. I'm going to give you the, sorry, the code, a link to my code
8:37
And then you will figure out exactly how to integrate with my service
8:42
This is the usual phrase you hear when this happens. it's like, okay, I don't need docs for my code
8:49
By just reading at the code, you will figure out exactly how to integrate
8:54
Now, what happens if you code has bugs? You're basically not explaining the intention of your code
9:02
because the bug is telling a different thing to the reader. So that's one example of the problems that you may have
9:10
And there's another example in the screenshot that basically is by reading at the code
9:14
or by using the service, that's not really, I mean, that's not explains exactly how you can use a service
9:23
because of bugs and because the service could be done. So you are basically blocking somebody
9:29
that wants to use your service. And then again, let's use the usual or real Google Docs
9:35
which is the traditional solution, right? The problem with this is that all of this is manual
9:41
and it's not part of your code. is not even part of your service
9:45
It's something that is parallel and that is manually updated. So the problem with this
9:51
and I have been referring this in the past, is that people doesn't update the documentation very often
9:56
So sometimes you read something in the old docs, but then when you use the service
10:02
there's a different behavior. So although this is better than just giving you the GitHub repo
10:08
and the endpoint, let's say, or the URL of the service, it's not enough
10:13
it's not enough we need to do something better so let's figure it out now as a summary let's
10:21
say you don't have docs let's say you want to enter into a service and you you can't receive docs you you just received the url so that's to me not the ideal solution it's actually the worst
10:30
solution now let's say you the documentation is the code okay that's slightly better but it's not
10:37
enough as i mentioned earlier if you have a bug then it's hard to explain the intention of your
10:42
code to the consumer. And last you have is a Google Docs or a Doc documentation, which is
10:49
I believe better than the other two, but again you still have something to fix because it's manual
10:56
Now the question I raised to you, is there a better way? Yes, there is, and you may know about
11:03
this. And if you don't know it, I suggest you guys to start looking at, for instance, Google APIs
11:09
they do a really good job about documenting their APIs because they want people to consume those APIs
11:15
and the best way to help other people to use them is to give something like
11:21
an API portal this is one of the names of this type of documentation
11:25
but more or less it's an automated documentation of your APIs that explains
11:30
not only how to use your APIs in terms of call you're looking at an HTTP request
11:36
you're looking at a technical documentation maybe you have some examples so you can learn how to use them but also there there is some text
11:44
there is some there are some descriptions of what you use what you should expect about the usage of
11:50
this service which is actually made by humans right the machines kind of automate this so it
11:57
involves the two pieces like automated documentation that it can be retrieved while you are coding
12:04
but also human documentation and explained the intention and that's I believe the the best of
12:09
worlds so now the question that you may have is okay that this is great but how can I do this
12:15
should I have to build something and the quick answer is no there are tools around
12:21
that you can use for this so let's let's see something about it and let's start with this
12:26
writing your first was talking so before we explain what an OS document is I need to give
12:33
you some background so first of all we're going to use swagger now and swagger is an open source
12:38
software framework that is it is now a platform and we're going to use that platform to build
12:46
these os documents or open epn documents so the idea is that this platform will give us
12:52
a automated documentation code generation and test case generation and it's only going
12:58
is gonna require us to build a document, right? An OAuth document
13:03
So we're gonna get some things for free by just writing some document
13:08
I wanna see what that means in a little bit. Now, I mentioned this earlier
13:12
so maybe this is the first time you hear about it. When I say OAuth, I'm talking about Open API
13:20
Swagger was the former name of Open API. That's why you're probably gonna
13:25
you wanna hear it or you wanna see it the internet. My idea is that when I talk about Swagger
13:31
I'm talking about the platform that we're gonna use right now, right after this slide
13:36
But when I'm talking about Open API, I'm talking about standard, a way to write a document
13:41
The document is gonna be written in JML. And it's gonna be a contract of your API
13:47
And we are using standard because the tools that we're gonna use can understand that standard
13:52
and give us a lot of goodies for free. And this is not just a standard because I say so
13:59
This is standard is backed up by all of these companies. And it's been like the de facto standard
14:05
for writing the contracts of your APIs. So I really strongly suggest you guys to start using
14:13
Now, let's go back to the use cases because before I start writing this standard
14:17
and explain you the rules, I want to recap of what we need to do
14:21
As I mentioned, we need to retrieve the list of speakers my conference
14:26
There are going to be more than just one conference, but to later I just write a simple example
14:32
Then I need to list the activities of my conference, of a particular conference
14:37
With that, I want to be the agenda. And last, I want to go through the agenda
14:43
and start providing feedback for each of the activities, or maybe each of the speakers
14:49
Now, let's get our hands dirty. Let's start with the first demo
14:54
which is my first open API doc or OS doc The API that I going to open SireHub I going to create an OpenAPI document from scratch
15:05
I'm going to use the version 3.0, which is the latest one
15:09
I'm going to show you how to build an OpenAPI document. I'm going to try to explain to you the basics
15:15
The rest is going to be up to you and I suggest you to start with the workshop I created
15:21
and I'm going to show you guys the link later. But for starters, this is good enough
15:27
And if you know about rest, it's gonna be super simple. Otherwise I'm gonna try to explain what I'm doing
15:33
And we're gonna see how much we can get by just writing some of these contracts
15:38
So let's get into it. Now, this is Swagathub. Again, the URL is app.swagathub.com
15:44
You can even just Google it and you will find it. And this is my account
15:49
I created a few APIs before, API contracts, because this is not a real API, this is just a document
15:56
This platform will give you a lot of things by just writing some documents
16:01
So I'm going to create a new one. I'm going to use openAPI3.0, and I'm going to use a template
16:07
I'm going to say React Conference Demo, version 1.0. I'm going to use the same name and title
16:17
I'm going to be the owner, and the visibility is going to be public
16:21
I'm gonna activate this automob API. We're gonna see what this means later
16:27
And I'm gonna get this conference, this document. And as you see, this is just a document
16:34
This is just YAML. Doesn't mean anything else, but the power of this platform
16:37
is that by just writing this YAML, we will get a lot of things. And let's get into it
16:43
So I'm gonna switch back to this. Let's go back to the things that we need to do
16:48
Let's start with the first one. I'm probably going to just show you the first two
16:52
but then I'm going to show you the real deal because I have it in my third tab
16:56
But the idea is that I'm going to show you how to list the speakers of a conference
17:02
And for that, first of all, we need to decide what the shape of a speaker is
17:07
So let's go to this build up a sample. I'm going to just copy paste all of this
17:16
Don't worry about this for now. I'm just gonna go through this slowly
17:21
But the idea is that the Swagger or the OWAS, sorry about that, the OpenAPI spec has two main attributes
17:30
One is paths, where we're gonna put our endpoints, or we're gonna define our endpoints
17:35
And the other one is components. And this one is used to define objects, schemas
17:40
or the shapes of the entities that we're gonna use. So in this particular case
17:44
we're gonna list the list of speakers. I'm gonna create a speaker schema
17:49
I'm gonna say that the type is object, just because it is a demo
17:54
I'm gonna just mention a couple of things that I want them to be required, but for now this is not needed
17:59
And then I'm gonna list some of the properties of this option, right
18:03
And this is trivial for if you have done this before in code
18:07
right, because I'm mentioning, I'm saying that the speaker is gonna have an ID
18:11
it's gonna have a name, it's gonna have a description, you don't have a new HURL, you have an account, you have an account, right
18:16
and give you, for each one of them, I give you some examples. And of course I mention it when I'm telling Swagger
18:26
hey, this is the format. Even though I'm saying the type of string, I need more information to OpenAPI
18:31
and to Swagger as the platform to tell the format, right? In this particular case is UUID, sorry
18:38
In this particular case is URI. That's pretty much it, the rest are regular strings
18:45
So we have to see at the left that you have the schema
18:50
well-defined and at the right, you will see that there is already a documentation of it
18:57
I'm gonna see that later on, but let's say this is good enough
19:01
It's not, right? Because I'm gonna now go to the speakers endpoint
19:06
and I'm gonna copy everything. This is like a TV show where the cook is like
19:13
getting all everything from behind the scenes. Sorry about that, but we don't have enough time
19:18
And the idea is that I'm now telling Swagger, hey, I want to build this path, right
19:26
And I'm basically telling them that my API is gonna have this path
19:30
which will retrieve the list of speakers of a particular conference and just using the edition ID
19:37
as the identifier of the conference. With this, I'm telling the swagger
19:44
or this is what you're using to define where the edition ID parameter is defined
19:53
And as I mentioned earlier, speakers is not enough. I need to define edition ID
19:57
So when you have to define a parameter, you need to use a different syntax
20:07
Remember that we have schemas. This is for objects, but when you have parameters
20:12
you just need to add another attribute, which is under components, which is parameters
20:18
And there you go, we have an edition ID, and I'm saying that the name of the parameter
20:22
edition ID is part of the path, is of course required. We have some information about it
20:27
and the schema of the parameter is just the type string. Right
20:34
So with this, I think I have almost everything, right? No, I don't
20:38
because I wanted to also show you guys that you can also define an error response object, right, or a schema
20:46
So let's grab it from my previous API
20:56
And this is similar to what I did before, right? I'm just creating another schema, which is a type object, and the name is error response
21:03
and it has only one property, which is the error message, right? And this is one of the examples
21:08
So if I go to this, I'm going to see my other schema worksheet
21:15
And with this, we can now see the speaker's endpoint. And I'm going to go through it from top to bottom
21:21
The idea is that I'm using a custom parameter. I don't know exactly what's going to be there
21:26
Maybe it's 2018, maybe it's 2019, maybe it's 2020. But the idea is that I'm modeling this by using Edition ID
21:34
Again, the definition of it is right below in the component slash parameters section
21:41
And this endpoint allows to get operation. It retrieves a list of speakers
21:49
And it has two responses. One is 200. It returns all the speakers of the edition
21:54
And the other one is default. But it's usually that this is used to say, okay, if it's not 200
21:59
then you need to see the default result, which is an error, right
22:05
So we're basically saying, if you receive a 200, it's a success response
22:10
and this is what you're going to get. And basically saying that I'm going to get
22:15
or the schema that my application's JSON response is going to be an array of speakers
22:19
a collection of speakers. But if not, if it's not 200, then I'm going to get an error
22:23
I don need to explain anything else right Now what the beauty of it Do you see this at the top right Which just view documentation Okay I going to click on it And we going to see the same thing that we seeing here
22:36
But I'm going to use another tab just to show you the details
22:41
Oh, still not loading. Let's wait for it. But you see at the right that you have the endpoint
22:51
And the beauty of this is that I can actually try it out
22:56
So let's say I click on this. Thank you. And it shows me the code operation
23:02
It's showing me the headers. And it's giving me the answer. Right
23:07
And it's of course an example of it. And the beauty of this is that I'm getting information
23:15
and it's using the examples that I used before. It's not a mocked up information, even though it is
23:23
but it's not a degenerated. I'm just actually telling what it needs to use
23:27
So it gives the consumer a better idea of what he or she is gonna be dealing with
23:34
And of course, it's talking about default operations. So this is so great, basically
23:41
And now I'm gonna fast forward and say, Let's say I completed all the endpoints
23:49
And there you go, right? And let's see what we'll cover right now, right
23:53
I mentioned that we have the get speakers, the get activities, and now we have the post to send some feedback
24:00
Now for that, not only I need the speaker schema option, I need also the activity, the feedback
24:06
and maybe a little bit more, and the response, right? And the good thing about this is that
24:11
I'm gonna switch this one, is that now, I have a link, a public link that I can share with the consumers of my API
24:22
To not only see the documentation, the live documentation of my contract
24:27
of my API with a lot of things that I didn't call yet
24:34
And the beauty of it is that they can try it out
24:39
So again, there's no real API working behind the scenes. There is something called booking service
24:47
And we are getting a real response. And now we're going to see a little bit more about it
24:52
But I owe you the definition of this mocking service. So the idea of Swagger is that they give you a URL
25:04
that will return mocked responses of your API using the examples that you provided to the documentation
25:11
And this is for free. This is what you get by just writing all the contract of your API
25:20
I didn't, you saw me, I didn't add any code to it. So this is great to me
25:24
So let's go back to the presentation. Quick summary. We saw
25:30
We get a web-basedator with autocomplete. I didn't show, I probably didn't show you already
25:36
but basically when I try something here, I get some information. So this is useful because if you are not used to write OpenAPI
25:47
these are hints that will help you to write about it. But it's super easy once you start writing a couple of things
25:53
Now, you get for free real-time auto-generated API docs. The thing that you saw on the right
25:59
but not only that, the URL that I show you, all of these are the generated
26:04
So it's any documentation that you can use and it's real-time and light documentations
26:09
tied to your contract, not to your Google Doc that you need to manually update
26:14
And last, we get an auto API mocking service or mocking integration, which means that your consumers
26:21
can start hitting this endpoint and figure out exactly how to build something on top of it
26:28
So this is great. Let's go to the second demo because this is even greater
26:33
Let's say you want to test this API, right? and this is not enough, right
26:41
This documentation is not enough. So one of the things that Swagger gives you
26:45
is the ability, sorry, is the ability to export my API. I'm gonna use JSON and Resolve, sorry
27:00
And this particular API has integration with tools like Postman. So if you're used to use Postman, instead of this URL
27:09
you can send the JSON to your consumer. Let me see if we can
27:21
There we go. And by just doing a few clicks, you
27:30
will get your own connection. Not sure which one it is because I did this a couple of times, but you will get a fully-fledged collection in Postman with all the information
27:44
So let's say your consumer is more used to use Postman, then you can give them this endpoint
27:51
And you will get the same result, right? Let's say I write 2019 here
27:57
And again, I'm getting a real response. Not only that, I can go and click on
28:05
check if I can do. I can use a core and I can open up a terminal
28:15
Sorry, and I can do the same. So let's say your consumer is used to use core
28:22
and they can use it. So I show you three ways of consuming an API
28:26
And I got all of this by just writing this document. right this channel so to me this is great but let's see other tools that we can use
28:36
to continue our implementation now we give the consumer a way to to build their own ui or api or mobile application but we can
28:54
give them more we can give them a client sdk basically client sdk is a way to wrap
29:01
a how you communicate with the particular service how you made a fetch or a call or the call request
29:07
in a way that is easier to the to the mobile developer to use and communicate with your
29:14
with your api so the third demo is about how to build a client sdk how to get the client sdk for
29:21
free with only again writing a document. So I'm going to show you how to do this
29:28
Basically we go to sport, play in SDK, and as you see there are multiple options. I'm gonna click
29:34
text and fetch and I'm gonna download it. And again as a tv show I have already configured all of
29:40
this earlier because we don't have enough time. And again this is part of the workshop so you can
29:47
and see a really good read in me and details if you go to the workshop
29:52
Let's go back a little bit to exercise two. And as you see in exercise two
30:04
ready to zoom in. I have two folders here. One is the Tyscript fetch client generated
30:10
which is something similar to what I downloaded before. And then the node conf file 2018
30:14
This is an example of a consumer of my API. So let's say I'm building this conference
30:21
This is a website. And this is a React, React app application
30:26
And the good thing about it is that it has a service. Nocon service that talks with my API
30:33
to retrieve the list of speakers. And all of this is in edited from the Nocon API
30:40
which would say something that I created using the same approach. And this is basically this
30:48
Now we're gonna match what is written here with the code. So what I got by downloading this .zip file
30:55
is that I got an API, sorry, auto-generated that has all of this information, particularly
31:03
let's try to find the get speak, you know, edition, get activities, right
31:09
And all of this is well documented. It's also automated. I didn't add any code to it
31:15
I can just write a service in my consumer, or by just using this client that is auto-generating
31:23
the code is awful, but at least it works, right? For instance, it's a way to get all the speakers
31:28
in my conference, and it's used by my code. Let's say this is the speakers
31:33
It's then used by the App.js, the component amount to return all the speakers
31:37
So when I click on NPM start, I'm going super fast because I don't have time
31:41
but you get the point, right? I'm spinning up a new website that lists the speakers
31:49
and it's connected to the Mocking series outside of the speakers. So what you see, this is the website
31:59
Let's see the network call. There you go. This is the mock service
32:07
And it's getting another speaker, which is me. So again, I did all of this without any single line
32:12
of call, only in the consumer. But hopefully, you are not also a consumer
32:16
But if you are, the only thing you need to do is that. So that's great
32:21
And the good thing about this is that all of this is fully integrated with VS code
32:26
or to understand Tiescript and you will get all the documentation, not only Tiescript, sorry, documentation
32:32
In particular case, I'm using Tiescript because I get all of this for free But if you have a different language that you wanna use you can use it and your ID will understand how to use it And I haven tested all of this
32:49
but you have more than 30 languages for your kind of SDK
32:53
C Sharp is another example. You have in Go. I use Tilescript
32:57
There's an Angular version and so on. Now, ideally, you might want to do this
33:05
But this is just an example, right? Let's say I write a document
33:09
an open API document in Salfa with the control of my API
33:13
Then I store that document in GitHub because I want a version
33:18
Then I create a client SDK and I store that in GitHub
33:24
but I use NPM, Maven or Nugget to publish that client SDK
33:31
And last, the consumer of my API, they only need to install that package
33:38
in their own website or application or mobile application to use. So next time, let's say I add something new
33:46
I just need to publish a new version of this kind of SDK. And then I need to notify somehow or tell my consumer
33:54
that there's a new version available, new features, which could mean a new endpoint or a bug fix, etc
34:00
But more or less, probably you know about this. Let's do a quick recap just in case
34:05
First of all, by having the SDK, you have an auto-generated library
34:09
that will simplify the usage and the consumption of your API. We mentioned this before, we have multiple languages
34:15
although we haven't covered all of them because we don't have any time. Sorry, we don't have enough time
34:21
You may want to test or use the language that you need. And last, this is fully prepared to be managed
34:29
the same way you manage a package that your consumers use. All right
34:38
Now, the last piece of it, right? I have defined the contract of my API
34:44
I have created automatically a client SDK that my consumer will use
34:49
that will ease implementation of the usage of my API. but I still need to implement my API, right
34:56
Because everything is mock. All right. Ideally, I will show you how to do it
35:04
but we don't have enough time. So we need to do something different, right
35:10
And that's what the fourth demo is about. What I'm gonna show you is basically a way
35:16
to scaffold an API which is named server stub Again we found that in a single line of code So although the code is auto and is pretty ugly it will help you to spin up let say a server in the Internet
35:31
to replace this mock service that Swagger is giving you in a way that you can work on the infrastructure
35:38
have something that at least is going to give you some mock information
35:43
But then once you have that service up and running, you can then worry about the real implementation
35:48
So let's get it. As I mentioned, this is named service tab
35:57
in the Swagger Hub platform. And like the client SDK, there are multiple ways of building or scaffolding one
36:06
I'm gonna use Node.js server. And there you go. So let's say I can see that file and use it
36:17
Now, what I'm gonna show you, and this is the exercise three of the workshop
36:27
is that, so in this particular case, NodeConf is the website that is a consumer of my API
36:38
TypeScript fetch is the service, sorry, it's a client SDK, and Node.js server is a server
36:43
So the client SDK haven't changed. It's still showing you the get edition activities
36:53
or get edition speakers, right? It's doing the same thing. But this client SDK is prepared to be consumed this way
37:01
It's about to know conf. So this is practically the same call we had before
37:06
but now we are instantiating the node API by using a server stub URL, right
37:13
and we're gonna use localhost instead of the automog, but let's say you have this deployer's work
37:18
you wanna change the URL, your deploy website with a new, with a real deal, right
37:24
So in this case, you clearly see that I'm gonna use the mock version
37:28
I'm gonna use something else. And let's, sorry, let's start with noconf
37:36
And let's start this creator, create app application. Hopefully this won't work because I haven't started my API, my Node.js API
37:50
And as you see, it's not working. So this is real. This is a demo and it's working as expected
37:55
So what I need to do next is that I need to start my Node my Yachtly Node service And you see that it using localhost and there something extra here So let start with this
38:11
So what's the good thing about these automated service tasks? It's that you get the same documentation that you saw in Swagger for free
38:19
So although it's not the same because the sites are different, you're getting the same features, right
38:26
You're getting all the documentation right next to your call, or this mock to go and you get a way to test all of this
38:35
The same way I showed you this before, right? And this is working again
38:41
This is a real server that is getting information. It's hitting the mock service
38:45
but this can be some changed with the real deal. Maybe sometimes you won't need it
38:50
but let's try the real deal, right? So let's go to the Node Conference
38:54
and then refresh it. And since I have started, I'm going to show you
39:00
probably you haven't seen it, but this service is working in localhost.it. You are seeing a different output
39:08
You are seeing that I'm hitting my server and you are seeing all of this information
39:15
that is represented in the website, right? And again, I haven't wrote a single line of code
39:23
to do all of this. All of this was for free and I only had to write an open API document for it
39:31
So that's pretty much it. So let's end with a summary. My suggestion, instead of writing
39:44
instead of giving a URL with the service to the consumer, instead of giving the GitHub URL
39:50
instead of giving the documentations in Google Docs, Write your ROAS document first
39:57
That's the first thing you need to do, the first and foremost thing you need to do
40:00
Then you will get for free all of the things that I show you
40:04
the client SDK, the documentation automated, and the server staff, which will enable other people
40:09
to go right away. We're not going to block anyone. So that's the beautiful of this
40:14
You can get in a couple of days something that other people can use to build their own things
40:19
on top of what we are building. Right? And with all of that, you will get a profit
40:26
Well, not really, right? You still need to implement the real plugin, so..
40:31
But you get the profit. All right. That's all I have to share
40:35
Thank you for your time
#Business Plans & Presentations
#Communications & Media Studies
#Event & Studio Photography
#Online Communities
#Programming
#Teleconferencing
#Voice & Video Chat