Coding

What is a RESTful API? | Creating a REST API with Node.js

  • 00:00:02 welcome to a brand new series on this
  • 00:00:04 channel in this series we'll have a look
  • 00:00:06 at how we create a restful api with
  • 00:00:10 nodejs
  • 00:00:10 let's dive right into it
  • 00:00:15 so let's start building a restful api
  • 00:00:18 with nodejs and for that first of all
  • 00:00:21 let's have a look at what exactly a
  • 00:00:22 restful api is what it's made up off and
  • 00:00:26 what we should keep in mind whilst we
  • 00:00:28 build it so what is a restful api
  • 00:00:31 actually well restful stands for
  • 00:00:34 representational state transfer and the
  • 00:00:38 whole idea behind a restful api or
  • 00:00:41 behind that name really is that we can
  • 00:00:45 use it to transfer data around now that
  • 00:00:48 sounds bigger than it maybe is the
  • 00:00:52 general purpose of why we want to use it
  • 00:00:54 is that it's an alternative to a
  • 00:00:56 traditional web page for cases where
  • 00:00:59 that traditional web page just doesn't
  • 00:01:02 fit our needs let's maybe have a closer
  • 00:01:04 look at this so what is a restful api
  • 00:01:07 imagine we have a client which is our
  • 00:01:10 browser so we are the client and we have
  • 00:01:13 some server obviously like a web page
  • 00:01:15 there we send a request for example if
  • 00:01:18 we enter something into the URL bar and
  • 00:01:21 we get back a response and for a normal
  • 00:01:24 web page as you know that's a couple of
  • 00:01:27 HTML pages 40 different URLs we enter so
  • 00:01:31 we have a starting page we have a
  • 00:01:33 products page an order page something
  • 00:01:36 like yet that is a traditional web page
  • 00:01:39 now if you're building a single page
  • 00:01:41 application it's going to be a bit
  • 00:01:43 different there you also send a request
  • 00:01:45 and you get back a response but you
  • 00:01:48 really only have to step only once
  • 00:01:50 because you get back one HTML page which
  • 00:01:53 contains a bunch of JavaScript in the
  • 00:01:56 end that will then dynamically re render
  • 00:01:58 that page but this is how web pages work
  • 00:02:02 now that's great for a traditional web
  • 00:02:05 apps but what about other cases where we
  • 00:02:09 also want to reach out to some server
  • 00:02:11 but where we don't really need HTML
  • 00:02:14 let's have a look at some of these cases
  • 00:02:16 we still got a server and by the way a
  • 00:02:19 server here also means that we probably
  • 00:02:22 have some database running on the server
  • 00:02:25 or running on another server but
  • 00:02:28 connected to this server and now let's
  • 00:02:30 have a look at different clients maybe a
  • 00:02:33 mobile app running on our smart phone
  • 00:02:36 and that mobile app obviously all needs
  • 00:02:39 to store and fetch data the problem just
  • 00:02:43 is it doesn't need HTML for that the
  • 00:02:46 data is not transferred as a text file
  • 00:02:48 or something like this or as HTML file I
  • 00:02:51 should say instead we use some other
  • 00:02:54 data format and we really are just
  • 00:02:55 interested in that data a similar case
  • 00:02:58 is if our client is some code some
  • 00:03:01 application think of the Google geo
  • 00:03:04 location API where we can send
  • 00:03:07 coordinates and we get back a parsed
  • 00:03:09 address for example that all there is a
  • 00:03:12 restful api just to give a little
  • 00:03:15 spoiler here and the idea here is that
  • 00:03:17 once you of course need to send data and
  • 00:03:21 get data we're not interested in an HTML
  • 00:03:24 page we just want to exchange data so
  • 00:03:27 that we can use it in our code and
  • 00:03:29 finally I already mentioned it the
  • 00:03:31 single page application case here we
  • 00:03:34 actually have a web app but only for the
  • 00:03:37 first request we need HTML for all
  • 00:03:40 subsequent requests we only want to
  • 00:03:43 exchange data send some data to the
  • 00:03:45 server fetch some data from it and
  • 00:03:47 therefore here we all just need one HTML
  • 00:03:51 page and no more thereafter you can't
  • 00:03:56 build all of that with a traditional
  • 00:03:59 server-side setup because a restful api
  • 00:04:02 in the end is also just a normal server
  • 00:04:06 the big difference in the end is that we
  • 00:04:09 don't care about this HTML stuff we just
  • 00:04:12 want to send data back and forth and
  • 00:04:14 that restful api is are stateless
  • 00:04:16 backends they don't care about the
  • 00:04:20 individual client which connected to it
  • 00:04:23 so if we have our client here and we
  • 00:04:26 have our restful server which is a
  • 00:04:28 normal server having some urls it is
  • 00:04:31 able to accept requests on and so on
  • 00:04:34 then we might have these endpoints so
  • 00:04:37 these are the urls supported by our
  • 00:04:40 servers
  • 00:04:42 these URLs then each might all support
  • 00:04:45 different HTTP words so we have get and
  • 00:04:49 post requests but we might also be able
  • 00:04:51 to support a delete request for example
  • 00:04:53 here to delete a user or the same for
  • 00:04:56 posts maybe we have a patch request
  • 00:04:59 that's all the HTTP verb which exists or
  • 00:05:02 for products maybe just a get request so
  • 00:05:04 this is how our restful api could look
  • 00:05:06 like we have a couple of URLs and each
  • 00:05:09 URL then possibly has a couple of
  • 00:05:12 different HTTP words and therefore types
  • 00:05:15 of requests it supports and then from
  • 00:05:18 our client we can send a request if
  • 00:05:21 we're having a web app we would call
  • 00:05:23 this an ajax request a synchronous HTTP
  • 00:05:26 request one where we don't send a
  • 00:05:28 request that get back a new page but one
  • 00:05:31 where we send a request our current page
  • 00:05:34 keeps on running and eventually we get
  • 00:05:37 back a response which we then if we're
  • 00:05:39 talking about a web application
  • 00:05:41 typically handle with JavaScript to
  • 00:05:44 re-render the dom or do whatever we need
  • 00:05:46 to do with that response and if we have
  • 00:05:49 some other kind of application like a
  • 00:05:51 mobile app then we still would have some
  • 00:05:53 tools provided by Java or Swift whatever
  • 00:05:56 it is whatever you use for writing that
  • 00:05:58 app that would be able to send a request
  • 00:06:01 and handle a response you get back this
  • 00:06:04 is the idea behind the restful api we
  • 00:06:07 have a server with urls supporting
  • 00:06:10 different types of HTTP requests for the
  • 00:06:13 given urls but all we do is we exchange
  • 00:06:18 data now if we have a look at this setup
  • 00:06:23 here this data is typically exchanged in
  • 00:06:26 JSON format it's not a must though you
  • 00:06:30 can send XML data URL encoded data like
  • 00:06:34 where you have like query parameter
  • 00:06:36 style foreign data you're not limited to
  • 00:06:39 Jason I'd say the one thing you
  • 00:06:42 typically always have is you're not
  • 00:06:44 sending HTML around though theoretically
  • 00:06:47 you could also do that and parse it but
  • 00:06:49 not with the goal of rendering it
  • 00:06:52 through the browser because these API
  • 00:06:54 endpoints here
  • 00:06:55 not going to get targeted directly by
  • 00:06:58 the browser in a sense of the user
  • 00:07:01 entering any of these URLs that's not
  • 00:07:04 going to happen
  • 00:07:04 all these URLs are going to be targeted
  • 00:07:07 by background requests like XML HTTP
  • 00:07:13 Ajax request sent from JavaScript or the
  • 00:07:16 equivalent for a mobile app this is how
  • 00:07:19 we use it and we use it to exchange data
  • 00:07:22 because that is essentially the only way
  • 00:07:26 we can connect a single page application
  • 00:07:29 or a mobile app to some back-end they
  • 00:07:32 don't want HTML they want the data they
  • 00:07:34 want to send data to so this is the idea
  • 00:07:38 behind a restful api now if we go into
  • 00:07:43 theory land here then this is not
  • 00:07:46 necessarily a restful api a restful api
  • 00:07:50 is a clearly defined construct and just
  • 00:07:53 having a couple of URLs with different
  • 00:07:56 supported HTTP endpoints it's
  • 00:07:59 theoretically just a back-end and an api
  • 00:08:01 you create it we often call all these
  • 00:08:05 API is restful though because it's the
  • 00:08:07 word or the expression for a back-end
  • 00:08:10 that is not a traditional server sending
  • 00:08:13 back HTML but data but theoretically we
  • 00:08:17 got a couple of constraints that really
  • 00:08:19 turn an API into a restful api we have
  • 00:08:23 six such constraints where one is
  • 00:08:26 optional I know this is really
  • 00:08:28 theoretical we're also going to build
  • 00:08:31 one in this serious so that it's a bit
  • 00:08:33 easier to grasp I guess so the first
  • 00:08:36 constraint is a client-server
  • 00:08:38 architecture if we're building a restful
  • 00:08:40 api then we have a clear separation of
  • 00:08:43 concerns between our back-end which is
  • 00:08:46 there to manage data do calculations and
  • 00:08:48 send us back data and our front-end
  • 00:08:51 which could be a single page application
  • 00:08:53 or a mobile app which is responsible for
  • 00:08:56 the UI our restful api awls is stateless
  • 00:09:00 so we don't store any client context
  • 00:09:03 like a session on it that's super
  • 00:09:05 important our restful api doesn't care
  • 00:09:08 about the clients connecting to
  • 00:09:09 it it doesn't care if it's reached by a
  • 00:09:12 single-page application and the mobile
  • 00:09:14 app and maybe some other application it
  • 00:09:17 doesn't store anything which clearly
  • 00:09:21 binds it to one of this applications
  • 00:09:23 like a session it's not handling
  • 00:09:25 sessions it's not it's not caring about
  • 00:09:27 sessions and this is going to become
  • 00:09:29 important when we add authentication we
  • 00:09:33 have cache ability in a sense that a
  • 00:09:35 restful api typically should also well
  • 00:09:38 express itself or tell the client
  • 00:09:42 whether responses can be cached or not
  • 00:09:45 and this is all the kind of case if you
  • 00:09:48 don't explicitly set up and there's just
  • 00:09:51 some default going to get used but you
  • 00:09:54 you can clearly define if for example
  • 00:09:57 for a get request you want to cache the
  • 00:10:00 response you want to allow the browser
  • 00:10:01 to cache the response and for how long
  • 00:10:04 that should be the case or if you would
  • 00:10:07 absolutely want to for a bit any caching
  • 00:10:09 because you know that your data changes
  • 00:10:11 so frequently that caching doesn't make
  • 00:10:14 sense
  • 00:10:14 so you can set up caching responses here
  • 00:10:17 too to really make sure that the client
  • 00:10:22 is using the API in an efficient way and
  • 00:10:25 this is just something you yeah you can
  • 00:10:28 do in a sense of you can clearly tell
  • 00:10:31 that caching should be enabled for
  • 00:10:32 example we also can build our restful
  • 00:10:36 api in some layered system which means
  • 00:10:39 the client connects to some server but
  • 00:10:41 that server doesn't necessarily have to
  • 00:10:44 be our final API could be some
  • 00:10:47 in-between server which forwards the
  • 00:10:50 requests or which sends back a response
  • 00:10:52 but behind the scenes also reaches out
  • 00:10:54 to our API and as I said we're really in
  • 00:10:57 theory land here but we just don't have
  • 00:10:59 to guarantee that our restful api or we
  • 00:11:02 don't give to guarantee I should say
  • 00:11:03 that our restful api is the final point
  • 00:11:07 in a traveler or in the journey of the
  • 00:11:09 request coming from the client we also
  • 00:11:12 have a uniform interface which means
  • 00:11:14 that resources are identified in in
  • 00:11:19 requests so we send a request to let's
  • 00:11:21 say slash users and
  • 00:11:22 and a get request that clearly
  • 00:11:24 identifies one resource the users get
  • 00:11:27 resource and that the data we transfer
  • 00:11:30 can be decoupled from the database
  • 00:11:33 schema so if we store a user in a
  • 00:11:35 certain way in the server-side database
  • 00:11:38 we don't necessarily have to transfer it
  • 00:11:41 like this to the user we can deviate
  • 00:11:43 from that schema although it's good if
  • 00:11:47 we have self descriptive messages and
  • 00:11:49 links to further resources for example
  • 00:11:51 if we send a request to get users we
  • 00:11:55 would probably get back a list of all
  • 00:11:57 the users and then it would be really
  • 00:12:00 good if for each user object we don't
  • 00:12:03 just get let's say the ID but we also
  • 00:12:06 get a link to which we would have to
  • 00:12:09 send a subsequent request to get the
  • 00:12:12 data for that user so that we don't have
  • 00:12:14 to guess about the API endpoint we would
  • 00:12:17 send a request to because there is
  • 00:12:20 something crucial to keep in mind of
  • 00:12:22 course when you're building an API you
  • 00:12:25 only have these addresses you only have
  • 00:12:28 these URLs and if you're not aware of
  • 00:12:31 them if you have no documentation to
  • 00:12:34 look it up and if the API doesn't send
  • 00:12:37 information about other addresses back
  • 00:12:39 in responses then you have no chance of
  • 00:12:42 using that API because how would you
  • 00:12:44 know to where you send a request if you
  • 00:12:48 compare it to a web application a
  • 00:12:49 traditional what I mean where you have
  • 00:12:51 multiple HTML pages there the user would
  • 00:12:55 navigate around with links so there we
  • 00:12:57 also have that information about other
  • 00:12:59 pages we can wizard and it's kind of the
  • 00:13:02 same gear for the restful api it's good
  • 00:13:05 if we provide this information back to
  • 00:13:07 our clients and then optional request is
  • 00:13:10 code on-demand that means that
  • 00:13:13 theoretically it would be allowed and
  • 00:13:15 still be a restful api if we implement
  • 00:13:18 it such that it gives the client back
  • 00:13:22 some executable code and that's not
  • 00:13:24 something we're going to build here so
  • 00:13:26 it really just means it doesn't have to
  • 00:13:29 be just data it could also be some code
  • 00:13:32 that the client can execute raw
  • 00:13:35 than just data for that code and again D
  • 00:13:39 is here these constraints are all just
  • 00:13:42 theory constructs so these are really
  • 00:13:46 just that's the theoretical definition
  • 00:13:49 of a restful api we're going to build
  • 00:13:52 one here and we're going to build one
  • 00:13:53 that works and that makes sense so don't
  • 00:13:56 don't learn that by by hearts that you
  • 00:13:59 don't need you know all of that be aware
  • 00:14:01 of that stateless thing is really
  • 00:14:03 important the clear separation between
  • 00:14:05 client and server dad seemed to be the
  • 00:14:08 most important things to me because
  • 00:14:10 that's something which often is hard to
  • 00:14:14 grasp and you often get asked well how
  • 00:14:16 can angle or your angular or a
  • 00:14:19 single-page application how can I create
  • 00:14:22 a session on the server and the answer
  • 00:14:24 is you can't really do that because in a
  • 00:14:27 single page application you use a
  • 00:14:29 restful api because you only need the
  • 00:14:33 data and a restful api shouldn't really
  • 00:14:36 care about the client connected to it
  • 00:14:39 shouldn't really manage sessions because
  • 00:14:41 you never reload pages anyways so that's
  • 00:14:44 important to know you're independent
  • 00:14:46 from the client you're stateless now
  • 00:14:49 enough of the theory let's build a
  • 00:14:52 restful api in the next video