11. Complete REST API Design

0:00API design is something that as a

0:03backend engineer you will spend a lot of

0:05time working on and thinking about and

0:08it is one of the most important videos

0:11in this playlist and in this video we

0:14are going to talk a lot about uh

0:17designing apis a lot of Concepts

0:20surrounding uh apis in general and we'll

0:23be mostly focusing on rest API there are

0:26different technologies that people use

0:29to build API

0:30uh we have RPC calls and we have graphql

0:36etc etc so in this one we are going to

0:39only focus on rest API one of the most

0:42used API standards now the problem with

0:46API design is we have all these

0:49resources and we also have this common

0:52standard which is called a rest API or

0:55restful API standard and years of

0:58research and many many developers

1:00particularly backend Engineers

1:02experience over the years and but still

1:05even now when someone who is learning

1:08backend or in the early stages of their

1:12journey into backend engineering they

1:14still get confused by certain questions

1:17questions like should the URI path

1:19segment be plural or singular or when

1:23updating a resource should you call

1:25patch or should you call put right

1:28different different http methods and

1:32also if it's a non- crud operation

1:34meaning if it's not a fetch operation or

1:37create operation or an update operation

1:39or a delete operation it's it's a custom

1:42action something that you want the

1:44server to perform it's called an action

1:47call so which method should you use

1:50since it it sounds like update should

1:53you go with patch orput or since it's

1:55creating something should you post etc

1:57etc like questions like these and also

2:00what uh HTTP status code to use for

2:04different different scenarios a lot of

2:06questions like this even now we still

2:09get confused about all these questions

2:11and the reason is when people were

2:14developing these standards uh these

2:16widespread HTTP API standards the state

2:20of the internet and the state of the web

2:24and the state of the clients and the

2:25state of the servers were very different

2:28from what we have today and and

2:30previously when these standards were

2:33being developed we were heavily using

2:36MPS also known as uh multi-page

2:40applications and these days if you uh

2:43are aware of the front end side of the

2:45ecosystem then we heavily make use of

2:49single page applications know where in

2:51the first API call the browser makes a

2:54request and downloads all the JavaScript

2:56that is required required and it

3:00performs all the routing on the client

3:02side using the browser's path and URL

3:05etc etc it's a completely client side a

3:08client heavy application now the purpose

3:11of this video uh is to standardize not

3:15to create new standards but as the

3:18standards already exist to extract

3:21certain rules and guidelines from this

3:23existing standards we aim to stick to

3:26these guidelines to make it as

3:28convenient as possible possible for

3:31everyone to follow A single standard and

3:33a consistent styling pattern when

3:37designing apis know designing apis

3:40designing payloads and documentation etc

3:43etc everything surrounding API design

3:46this way we won't have to question these

3:48issues anymore these common issues that

3:50backend Engineers face in day-to-day

3:53lives we can simply move forward with

3:56our development now we already have this

3:59standard in place and by sticking to

4:01them we can focus on our business logic

4:03instead of worrying about whether our

4:05API is restful or not or whether we are

4:07following the latest industry standards

4:09or not etc etc so in this video we will

4:12explore API design from end to end

4:14starting from how to design your

4:15resources how to design your routes how

4:17to return success responses how to

4:20return error responses which status code

4:22to use what kind of data to accept and

4:25much much more essentially everything

4:27related to API design so that we can

4:29concentrate on our business logic after

4:32this video we can move on from standards

4:35and we'll get into execution phase now

4:37before we start about the technical

4:40stuff the actual API designing part

4:43let's talk a little bit about the

4:46history of where we are coming from and

4:49why we are talking about it so that we

4:51have a little more context so in 1990

4:55Tim berners Le started a project called

4:57the worldwide web to share knowledge

5:01with the whole world that was the

5:03initial motivation for starting what we

5:06call as Internet today and this project

5:09was built to facilitate the sharing of

5:13knowledge and information globally and

5:16with that goal team mesly within a year

5:20or so invented all these different

5:23concepts or Technologies first one URI

5:27what we call as uniform resource

5:29identifier second one HTTP the HTTP

5:33protocol that uh we use

5:36underneath to communicate between client

5:39and servers we have already covered how

5:41HTTP works and etc etc in previous video

5:43so you can check that out third HTML

5:47HTML is basically the markup language

5:50which we use to construct web pages what

5:54you can call is the skeleton of a page

5:57fourth the first web server fifth the

6:02first web browser and sixth the first

6:06what you see is what you get editor an

6:11HTML editor which was built directly

6:14into the browser now he built all these

6:18things which we still use today by the

6:21way and we use the advanced and the more

6:25developed version of all these

6:27Technologies we still use Uris we still

6:30use make use of HTTP protocols now uh it

6:33started with HTTP 1.1 then now we have

6:37HTTP 2.0 and 3.0 etc etc we still make

6:40use of

6:41HTML right we still use HTML we have a

6:45lot of different types of web servers

6:47these days we have a lot of different

6:48types of browsers these days etc etc and

6:51we also have the browsers uh in built

6:53HTML editor right so he invented and he

6:57came up with all these new technologies

6:59and Concepts within an year or so but

7:02soon now the problem arises the problem

7:07was the project which was known as the

7:12worldwide web was headed towards

7:14breakdown because of the exponential

7:16growth of its user base within a short

7:19period of time a lot of users a lot of

7:22people started using this new technology

7:24which is known as the worldwide web and

7:27the Creator uh Team Bal Le he had not

7:30accounted for all this uh scale all this

7:34number of users when he was building the

7:36project this was not accounted for so to

7:39scale the web to accommodate this large

7:43user base new techniques standards and

7:46components had to be introduced the

7:49previous one the all the mindsets and

7:53all the Technologies and all the

7:54planning that went behind creating or

7:57coming up with all these Technologies

7:59was not enough to scale the web to

8:02account for the huge user base that it

8:05was acquiring every day it was scaling

8:08exponentially now at this point we have

8:11one other major contributor to the

8:13project web so around

8:161993 Roy Fielding the co-founder of the

8:20Apache HTTP server project became

8:23concerned about the web scalability

8:25problem that we just talked about the

8:27web was not ready to accommodate this

8:30large user base the thousands and

8:32thousands of users and people that were

8:35using the worldwide web project every

8:37day to address this issue uh and make

8:40the worldwide web more scalable he

8:43proposed a couple of

8:45constraints that could help achieve the

8:47goal and these constraints are number

8:50one client server which we still follow

8:53by the way the client server model this

8:56constraint basically emphasizes the

8:58separation of con concerns between the

9:00client and the server the client handles

9:04all the user interface the user

9:06experience while the server manages data

9:09storage and business logic which we also

9:11call as the front end and back end this

9:15separation allows each component to

9:17evolve independently and to improve

9:21scalability that's the first constraint

9:23the second constraint is uniform

9:26interface this constraint simplifies the

9:29overall system architecture by

9:31establishing a standardized way a

9:34standardized way of components different

9:37different components that the web

9:39comprises of to communicate with each

9:42other it also includes uh four subc

9:46constraints which are called resource

9:49identification resource manipulation

9:51through

9:52representation self-descriptive messages

9:55and Hyper media as the engine of

9:57application State we have also sub

9:59constraints under this one the uniform

10:01interface the philosophy of uniform

10:03interface the uniformity provides a

10:05consistent interface across all the

10:08services third one layered system now

10:11this says that the architecture composed

10:14of hierarchical layers and each layer

10:17can only see and interact with the

10:19immediate layer below it and this allows

10:22for better scalability security and the

10:24ability to add intermediate components

10:27like load balancers and prox servers Etc

10:31which we use today to scale our web

10:34applications to cater to millions of

10:37users right and and this happens without

10:41affecting the system's core

10:42functionality now fourth cach cach uh

10:46responses from the server must be

10:48explicitly labeled as the cachable or

10:51non-cashable that's what this constraint

10:52says the server should label different

10:55different responses as whether it should

10:57be cached or not by the client and when

11:01the clients need they can cash the

11:04responses which helps reduce the server

11:07load uh improve Network efficiency and

11:10enhance the user experience by providing

11:12faster response times now fifth one is

11:17stateless now stateless we have already

11:19covered in a much more depth in the

11:22previous video I think it was the HTTP

11:24video uh this basically means that each

11:27request from the client to the server

11:30must contain all the information

11:33necessary to understand the and process

11:35the request the server basically will

11:38not remember what your previous request

11:40was about with each request you have to

11:42include all the information necessary uh

11:45so that the server can identify you and

11:47the server can take your data understand

11:50it and process it that's what stateless

11:53means and the server does not store any

11:56client context between requests and this

11:59in turn improves reliability scalability

12:02and visibility since any server can

12:04handle the request let's say you are

12:06scaling your web application and you

12:09have added two more servers and there is

12:12a load balancer in between which

12:14forwards your traffic depending on

12:16different different algorithm like round

12:17robin etc etc and because of this

12:20stateless constraint all the servers can

12:25process request from the same client

12:27because of the statelessness nature of

12:31the web because all the requests consist

12:33all the information that the server

12:35needs to process the data and the sixth

12:39one which is code on demand this is an

12:42optional one uh which means that servers

12:45can temporarily extend client

12:47functionality by transferring executable

12:49code like JavaScript to the client and

12:53this is only an optional constraint in

12:55rest

12:55architecture because it provides

12:58flexibility to add client side

13:00functionality when we need it uh while

13:02maintaining other constraints and etc

13:04etc this is not something you will see

13:07getting used heavily these six are

13:10basically all the constraints that Roy

13:13Fielding came up with to solve the

13:16problem of scalability in web and later

13:19on Fielding worked with Team Berner Le

13:23and both of them together worked to

13:26increase the scalability of web and and

13:29to standardize their designs and

13:32together they wrote a specification for

13:35the new version of HTTP which we today

13:39know as HTTP 1.1 the first major version

13:43the first standard version of the HTTP

13:46protocol and then in the year 2000 after

13:50the scalability crisis of web was avered

13:54Fielding Roy Fielding named and

13:57described the web's architecture style

14:00in his PhD dissertation and it was

14:03called as rest representational State

14:07transfer which was Roy fielding's PhD

14:09dissertation that was the name that

14:12Fielding gave to his description of the

14:14web architectural style and which today

14:18we know as rest apis and if you go and

14:22search Roy Fielding rest paper you can

14:27directly open this and and read the

14:30first document that was written about

14:34Rest apis by ra fielding and you can get

14:38more insight more context and what uh

14:40LED them to come up with all these

14:43patterns come up with all these Concepts

14:44etc etc right it is a must read if you

14:47are a backend engineer reading this

14:48gives you a lot of context about where

14:52all these Technologies originated from

14:54all these Technologies patterns

14:56standards that we have today okay great

15:00now that brings us to why is it called a

15:04rest API what does it actually mean if

15:08you read the paper that was uh written

15:11by Roy Fielding you'll definitely get

15:12the idea why was he calling it rest

15:15architecture or restful architecture or

15:17rest API but if you want to make it

15:21brief why the name rest why the name

15:25representational State transfer then we

15:28can up with some points number one is

15:34representational the first part of this

15:36name r which means representation this

15:40basically means that resources on the

15:43internet resources on the web which

15:45means data or objects are represented in

15:48a specific

15:49format they have a specific

15:52representation depending on the specific

15:54servers and specific clients and these

15:58representations can be in various

15:59formats it can be in

16:01Json that is the most popular uh

16:04representation format that we have these

16:06days but we also have

16:09XML and we also have HTML so different

16:14different representations depending on

16:16different different context for example

16:18a server to server communication will

16:21depend on the Json based representation

16:23while a server to client based

16:26communication depend on the HTML ml

16:29based communication right that's what

16:31representation means when we are talking

16:34about web's architecture the rest API

16:37architecture the same resource can have

16:39different representation based on the

16:41client's needs so a user for example

16:45let's say we have a user resource which

16:48might have different different fields an

16:49ID field a name field a created at field

16:55etc etc so let's say we have a user

17:00resource a database resource let's

17:03assume so a user resource this can have

17:07different different representation

17:08depending on different different clients

17:10let's say this can be represented as a

17:12Json right for an API client let's say

17:15another server is making a request to

17:17get this object or get this resource

17:19then this can have a Json based

17:22representation but if we want to send

17:25some uh UI data to the browser then we

17:29can represent this as an HTML document

17:32or as some kind of HTML representation

17:35right for the client which is a web

17:37browser so that's what we mean by

17:39representational in the restful

17:41architecture coming back to the second

17:43part state representational state

17:46transfer so what do we mean by state

17:48here State basically refers to the

17:51current condition or attributes of a

17:54particular resource the current property

17:57of a resource the state of the resource

17:59and each resource let's say we had a

18:02user resource here so each resource has

18:05a state that can be transferred between

18:08client and server and the state is

18:11driven by the resource representation so

18:14taking an example let's say we have a uh

18:18e-commerce site let's say we have Amazon

18:21we have Amazon and we have a shopping

18:24cart in the cart we have a couple of

18:26items so a shopping cart State includes

18:30all the items the quantities of the

18:32items and the total price so that we can

18:37call as a state of a particular resource

18:39of a particular module that we have in

18:42our web application that is transferred

18:45between a client and a server with each

18:47API call and the last part which is

18:52transfer representational State transfer

18:55the third part talks about transfer what

18:57does transfer mean so transfer basically

19:00indicates the movement of resource the

19:03movement of resource representations

19:05between client and server so obviously

19:07since we have a client server model the

19:10primary intention of that is sending

19:12data between client and server and the

19:14client and server can exchange different

19:17representations of the same resource we

19:20have a client here and we have a server

19:22here and the transfer of data happens uh

19:26through a common standard which is

19:29HTTP and we have uh different different

19:33methods associated with that which is

19:36get post uh put delete patch options

19:40head etc etc right we have all these

19:43different different uh methods which we

19:46use to send data between client and

19:49server for example when you get a web

19:51page when you uh send a get request to a

19:54server for a web page you are

19:57transferring a repres presentation from

19:59server to client using an common HTTP

20:03method which is get so when we combine

20:07this when we combine all these three

20:09elements uh which is called

20:11representational State transfer or also

20:15known as rest or restful or rest API

20:18this describes an architectural style

20:21where one resources are representated in

20:25different formats we have different

20:27different formats we have J on we have

20:29HTML we have XML etc etc first thing is

20:32resources have different different

20:33formats second the state of these

20:36resources can be transferred between

20:38server and client client and server

20:41first is the format of the resource the

20:43second is the state of the resource

20:45third clients and servers communicate

20:49between each other by sharing these

20:51representations of a resource okay the

20:54representations can be different but the

20:57idea is client and server communicate

20:59with each other using these

21:01representations and third the system

21:04this whole system follows specific

21:06constraints specific constraints to make

21:09the whole workflow more scalable right

21:12which we have already discussed so

21:14that's what we mean by restful API or

21:19rest architecture that's the history

21:22behind uh where and when and how we came

21:26up with this whole architecture this

21:29whole model of representing resources

21:32and transferring resources between

21:33client and servers and different

21:36different formats etc etc right this is

21:38all the theory that you need to

21:41understand on a very high level you

21:42don't need to remember any of it but

21:45this gives you a little bit of context

21:47of where and how we came up with all

21:50these things and where are we currently

21:53let's start with a URL and this is what

21:56a typical high level structure of a URL

22:00looks like know in any website that we

22:02visit this part what we call is the

22:05scheme uh whether it can be HTTP or it

22:09can be https the secure version the

22:11encrypted version then we have the

22:15authority or the domain it can also have

22:17a subdomain but in this case we have the

22:19main domain which is sly.

22:22XYZ then we have the resource or the

22:25path so this part uh uh is called the

22:29resource that we are trying to access

22:32and this symbol the forward slash symbol

22:36represents a hierarchical relationship

22:39between different resources and then we

22:41have the query parameters which we use

22:45in usually get apis to pass some kind of

22:50key value pairs to give more information

22:52to server about uh some kind of filters

22:56parameters etc etc then we have

23:01fragments uh this section usually uh

23:05navigates you to a particular section of

23:07a web page if this is present in the URL

23:11when you first time navigate to a web

23:13page if you have a fragment then the

23:17browser Scrolls you to that part of the

23:20page okay so this is what a typical uh

23:23website URL looks like now we since we

23:27are talking about apis and best apis

23:29starting from this what would a an API

23:32URL or an API route will look like so we

23:37can start from this we will obviously

23:39have the scheme so let's imagine we have

23:42the encrypted version the secure version

23:44htps then we will have a subdomain so

23:47I'm talking about the industri standard

23:50right this is not a rule uh this is more

23:52of a standard or best practices that

23:55most companies follow uh when they are

23:58implementing when they're creating their

24:00backends so usually it starts with a

24:02subdomain of the main with a subdomain

24:06of API so API dot let's say example

24:12example.com okay this is the subdomain

24:17part subdomain part then we have

24:20versioning most apis implement or follow

24:23some kind of versioning pattern and

24:25usually through routes so this will

24:28follow something like V1 or V2 etc etc

24:32then we reach the path or the resource

24:35that we are trying to access so let's

24:38imagine it is a it is an API which is

24:42like good reads if you are aware of good

24:45read it's a platform where there are a

24:48lot of books there are a lot of authors

24:51and books are associated with authors

24:53you can provide your reviews feedbacks

24:56etc etc it's a whole community about

24:58readers and authors and books Etc if

25:02this API is of good RS then an apaa

25:07which fetches all the list of books will

25:10have something of a structure like this

25:13so then we write the name of the

25:15resource so book now the first rule is

25:20in an API when you're designing a route

25:23when you're designing an API in the path

25:25segment whatever resource that you you

25:28are providing whatever resource your

25:31client is trying to access or whatever

25:32resource the backend is serving that

25:36should always be in the plural form it

25:39is a standard that all the resources in

25:42your path segment of the URL should be

25:44of plural form so ideally it should be

25:47books okay then we have this API uh

25:50which has the subdomain api. example.com

25:52SL we have the versioning here and then

25:55we have books this is an API to list all

25:58the books to fetch the list of all books

26:02similarly we can have another API so

26:06let's say we remove this this this let's

26:10say we have another AP which fetches a

26:14single book so up to this point we have

26:19bit constant right uh of course the we

26:23can have different different versions of

26:25the same API but for the sake of this

26:28example let's imagine up to this point

26:31we are in the version one only and this

26:33part is constant we will have the scheme

26:35https then we will have the subdomain

26:38api. example.com then we'll have the

26:41version in which is the V1 but in the

26:43second API we want to fetch the

26:45information for a single book so what

26:48will the path look like now there is one

26:50mistake here which most people do is

26:53since we are fetching the information of

26:55single book uh people make this as a

26:58singular now right they make this slash

27:01book or then whatever the book ID etc

27:04etc you should not do that because um

27:07even though you are fetching the

27:09information of a single book but the

27:11resource that it is concerned about this

27:14resource which is the book resource that

27:17is represented as a plural noun when we

27:22are dealing with path segments in the

27:23URL so even if this is about a single

27:27book we have to put we have to make it

27:30plural here so it will still be books

27:33then we have the ID now uh since we are

27:38talking about URLs one thing that you

27:40have to uh keep in mind when you're are

27:43designing apis are the readability the

27:46representation of URLs in browsers or

27:49different different client environments

27:51couple of things that you have to

27:54remember is you should not put spaces or

27:57under scores etc etc these characters in

28:00a URL whether it can be a uh slug or

28:04whether it can be an ID know whatever

28:07part that you're dealing with for a

28:09route you should not put spaces or

28:12underscores in a URL the thumb roll is

28:16if you have a phrase which has spaces

28:19and you want to put that into the URL

28:21let's say uh we have this API and we

28:24want to fetch the information of a

28:26single book and we want to fet the

28:28information using the slug of the book

28:30now slug is basically the name or some

28:35property of the book let's say the name

28:38of this book is Harry Potter the name of

28:41this book is Harry Potter now the slug

28:45of this book will be a human readable

28:50representation of some property of that

28:53resource which is ideal to put inside a

28:57URL

28:58which means first thing that we do to

29:01convert this into a slug is we make all

29:04of this a small case even though we can

29:07put Capital case but because the URL

29:10will be traveling to different different

29:12environments it will travel to different

29:14server environments different client

29:16environments different operating system

29:18we don't want to mess with the case

29:21mismatch etc etc right so first thing

29:24that we'll do is we make both of this as

29:27smaller is the first change is the part

29:32okay this is the first change second

29:34every time we have a space we will

29:36replace that with a hyphen now we have

29:40the final slug which is Harry Potter and

29:43now we can put this into a URL so/ book

29:47SL Harry Potter one thing that I

29:51mentioned a while bag is I said whenever

29:53we use this character the forward SL

29:56character in a URL uh uh in an API route

29:59in a path segment this means there is a

30:01hierarchical relationship between these

30:04resources so for example this API this

30:09says that we have a resource a

30:12collection of resource which are called

30:14books in our server in our database or

30:19wherever your storage is and that is the

30:23first level of hierarchy the second

30:25level of hierarchy is we want to access

30:27one particular resource from that

30:29collection of resource that resides in

30:32our database or some kind of storage so

30:36this is what I meant whenever we use the

30:39path segment you have to uh think of

30:42this as a hierarchical relationship

30:44between different resources okay so I

30:47think that's pretty much all the primer

30:48about URLs uh that we need to talk about

30:52right now we'll of course explore more

30:55about how to design your routes in

30:57different different apis

30:58when we get to the demo part okay so

31:00moving on another important concept that

31:03we have when we are talking about restas

31:06is em potency this is a very important

31:10theoretical concept uh of course it has

31:13a practical implication but the concept

31:16of item potency basically means the

31:19property of certain operations in which

31:22performing the same action multiple

31:24times has the same effect as performing

31:27it once

31:28which means an action which you have

31:31performed using an API call it does not

31:33matter how many times you perform that

31:35action the effect the side effect the

31:39change that happens in that environment

31:42Remains the Same it does not matter how

31:44many times you perform that action

31:46that's what we mean by em potency so in

31:48this context in the context uh where we

31:51are talking about rest apis item potency

31:55basically means it does not matter how

31:57many times the client performs a

32:00particular request the outcome the

32:03result of that request in the server

32:05environment Remains the Same so even if

32:08I call an API once or I call the API

32:12thousand times the outcome of that the

32:15result of that should be the same if we

32:18call a particular API or a particular

32:21action is item poent now as you already

32:24know when talking about different

32:26different actions that we can perform

32:28using API calls we come to the concept

32:33of HTTP methods and in the previous

32:36video of HTTP we have already discussed

32:38this in depth what are the different

32:41types of methods how they work what are

32:42the properties Etc ET so we have around

32:45five major kinds of methods that we use

32:49to handle different different data

32:52operations okay we have get we have post

32:56we have put we have patch and we have

32:59delete okay these are the five major

33:02methods we have other methods also head

33:04and options etc etc which um head is

33:07used to patch the headers information

33:10and options is used to uh options is

33:13used in our course flow to find out

33:15whether the origin is allowed or not etc

33:17etc right but majorly these are the five

33:21kinds of methods that we use for data

33:23transfer between clients and servers now

33:25relating the concept of emut see two s

33:29methods uh gives us a lot of insights

33:31into which method should we use in which

33:34context okay now the get call which we

33:39usually use to fetch some information

33:42from the server now this method is used

33:45to retrieve data from a server and it is

33:49em potent a get method or a get action

33:53on a server is considered as item poent

33:56because it does not matter how many

33:58times you perform a get request you will

34:00get the same outcome right let's say we

34:03in the previous example we are fetching

34:05a list of books we fetching a list of

34:07books so it does not matter how many

34:10times you call this API you'll get a

34:13list of books and now you must be

34:15thinking what if uh while you're are

34:18making these API calls someone else

34:20creates another book and the result

34:22changes the response of the API changes

34:25in the subsequent calls of the G and and

34:28that's true but that is not what we

34:31consider when we are talking about item

34:33poent item poent basically means from

34:35the client using an API call what side

34:38effect can you cause in the server and

34:40whether that side effect is different

34:42with each API call or that remains same

34:45during the first API call or the 1,000

34:48API call okay now and because of that

34:52reason the get call is considered item

34:54poent it does not matter how many times

34:56you fetch some information you do not

34:59make any change with your API call in

35:02the server environment okay it is just a

35:05fetch operation that's why the get is

35:07called an item Buton method similarly

35:10the patch method and the put method

35:13these two methods that we generally use

35:15to update some data in the server to

35:18update a particular resource or a part

35:22of a resource we use patch when we up we

35:25want to update a part of a resource

35:26let's say a single single field or two

35:28three fields of a resource in the server

35:31in that case we use patch we use put

35:33when we want to completely replace the

35:35representation of resource in the server

35:38using the client payload so let's say we

35:41have a user object in the server it has

35:44ID it has name it has created at etc etc

35:49and for an update operation if we want

35:52to update the name of the user if you

35:56want to use the p method then we can

35:59just send the name field with the new

36:01value of the name and the server will

36:03handle it accordingly it will just

36:05update the name but using put method

36:09what it does we have to send both the ID

36:12the name the created all the fields in

36:15that payload so that the server can take

36:17that payload and completely replace it

36:20with whatever instance of that user

36:22object the server has currently now it

36:24is true that um most of the time put and

36:28Patch is used interchangeably and that

36:31is fine that is fine to some extent uh

36:36as long as you using your API internally

36:39but let's imagine you are building some

36:42kind of public API in that case you have

36:45to implement your API specs in a way

36:48that sticks to the standard as much as

36:51it can so that other people other

36:54Engineers who want to integrate your API

36:56do not get confused because they assume

36:59that you are following a standard but

37:01you are not so if you are using put when

37:05you should be using patch then that

37:07gives some kind of wrong assumption and

37:10it might be a confusing situation but

37:13again it does not cause as much of a

37:15harm because obviously from the behavior

37:18of the a people can tell whether it is a

37:21patch operation happening or I put

37:22operation but yes uh you should always

37:25try to stick to the standard stick to

37:27the semantic standard that the rest a

37:30offers so if you want to update a

37:34particular resource partially then use

37:35patch if you want to completely replace

37:38the representation of a resource then

37:40use put okay now patch and put are also

37:45called as emed because let's say we are

37:48updating the name of the user with a new

37:51value let's say the previous name of the

37:53user was a and we want to replace it

37:56with the new payload which is B okay so

38:00we make our first API call and we send

38:03this payload okay and the name of the

38:07user becomes from A to B that's the side

38:10effect that we caused using our API in

38:12the first API call what happens in the

38:14second API call the name of the user is

38:17already B but we make the same API call

38:19with the same payload now from B it

38:22again changes to B okay now that

38:25continues it does not matter how many

38:26times you all that API it can be

38:29thousand it can be million but the

38:30result will be same after each operation

38:33the state of the user Remains the Same

38:35the name is still B you are not causing

38:38different side effects with each API

38:40call that's the reason patch andp put

38:44any kind of update operation with the

38:46same payload will obviously be item now

38:49we have ruled out get and patch and put

38:53as uted methods next up is delete now

38:56what do you think delete is whether it

38:58is item button or not now imagine again

39:01we have this user object uh which has an

39:04ID name and created at field and we make

39:08a delete API call to the server and we

39:11deleted this user this user does not

39:14exist that is the result of the first

39:17API call what happens in the second API

39:19call you make the same request to delete

39:23the API uh to delete the user which has

39:26the ID as one okay you made the same API

39:31call in the first payload with the user

39:33ID one and you are making the same API

39:35call again with the user ID on you want

39:37to delete this user in the second API

39:40call since this user is already deleted

39:43the server checks your payload it checks

39:45whether the user exists or not and it

39:48sends you an error that this user does

39:50not exist it sends you a 404 error since

39:54you are trying to perform some action on

39:56an entity which does not exist that's

39:59the reason you are getting a 404 error

40:00but did you cause any side effect in the

40:03second AP go you did not because in the

40:06first API call you deleted the user in

40:08the second API call nothing really

40:09happened the server just checked whether

40:11the user exists or not and it send you

40:14an error but nothing really changed no

40:18state of the entity changed in the

40:20server it it had no side effects that's

40:24the reason it does not matter how many

40:25times you call this delete API call

40:28you can call it a million times you'll

40:29get the same error million times that

40:31this user does not exist you only made

40:35the change in the first API call and

40:37that's the reason delete is also

40:39considered as an item poent method at

40:41last we reach post now this is the only

40:47method in the HTTP semantics which is

40:50considered as a nonm poent method

40:54because when we use a post request

40:57usually the post request is used when we

41:00want to create a new resource or a new

41:03entity in the server so taking from our

41:06previous example which was a book API if

41:10you want to create a new book we want to

41:12add a new book to our inventory in that

41:15case we'll send the name of the book and

41:19some kind of description some kind of um

41:22weight Dimensions Etc different

41:26different properties of the book and we

41:27will take this payload put it in the

41:31body and we send this to the server in a

41:34post call and the server receives it it

41:37takes the payload and it performs some

41:40kind of database operation and in it

41:43inserts that uh entity into the database

41:47it creates a new book now that's that's

41:50what happened in the first AP call in

41:52the second API call let's imagine you

41:54made the same payload with the same name

41:56description ion bit Dimensions etc etc

41:59you just took the Cur of that request

42:02and you executed that Cur again you made

42:04the same API call again what happens now

42:07there is a chance

42:09that um in this API the name has to be

42:14unique if that is one condition that

42:17your server is following or your

42:19database is following then you might get

42:22an error which is the name cannot be

42:25duplicate ET

42:27but for the sake of this example and it

42:30for the sake of real world scenario it

42:33is often the case that names can be

42:35duplicated right multiple books can have

42:38the same name right the that's that's

42:41the reason we differentiate between

42:43different books from their IDs not from

42:46the names so that's the reason uh when

42:49you make the same API call in the second

42:51time what happens the server takes your

42:54payload it performs the same operation

42:56and it inserts it into the database now

42:58you have the second book with the same

43:00information right but with a different

43:02ID IDs are usually generated at the

43:04database level uh whether uu ID or some

43:07kind of Serial value 1 2 3 4 ET IDs are

43:09generated at the database level that's

43:11the reason you can have multiple books

43:13with the same kind of properties name

43:15description weight Dimensions etc etc

43:17but the IDS will be different that's the

43:19reason an error does not occur that's

43:21the second API call and this is the

43:24pattern with each API call you are

43:26creating a new book and when you if you

43:29call this API a thousand times you'll

43:31have a thousand new books now what we

43:35discussed what is the property of what

43:36is the condition of idency the side

43:39effects that you cause in the server

43:42should not be different with each

43:44request right but it's the opposite

43:48happening for the Post calls right with

43:50each API call you are creating a new

43:51book the side effects are changing and

43:54that's the reason post request post

43:56methods are are called nonm poent

43:59Methods now one more thing about post is

44:02whenever we have a noncured operation an

44:05operation an action that does not fall

44:08under any of the methods that is defined

44:11by HTTP spec right it is not a fetch

44:14operation it is not an update operation

44:16not a create operation not a delete

44:18operation it does not fall under any of

44:20the methods in that scenario because of

44:23the existence of scenarios like these

44:26the s spec the rest AP spec has made the

44:30post method as open-ended which means

44:33whenever you find yourself in a scenario

44:36where you cannot put some action

44:39some uh action in any of the existing

44:43methods then you can put that under the

44:46post call in the post method so let's

44:48imagine we have an API which uh says we

44:53which is like send email okay we have

44:56this AP and when we call this we can

44:59send an email to a client so let's say

45:04the payload the body of this API call

45:06looks something like this target is some

45:09email address right and when we make

45:12this API call the server takes it and

45:15extracts the

45:17payload the target email and sends the

45:20email that is basically the

45:21functionality of this API now the point

45:25that I'm trying to make here is what

45:27HTTP method that you would assign to

45:30this action or this API because it say

45:33send email but is this a fetch operation

45:37it's not right it is some kind of action

45:39we want to tell the server that do

45:42perform this action whether it is a

45:43create operation it's not it's not an

45:46update or delete operation either that's

45:49the reason it is called a custom action

45:51in the HTTP or rest AP terminology so

45:55whenever we have scenarios like is

45:57whenever we have custom actions the

46:00operations or API calls which we cannot

46:03categorize under any of the Curr

46:05operations those are the situations that

46:08we can make use of the post method which

46:11is meant to be used for custom actions

46:14as for the rest TP specification okay

46:16and that's pretty much all about HTTP

46:19methods uh when we are talking about

46:22rest

46:23apis now let's move on to some demo

46:26right

46:27how exactly do you start with your API

46:30design how do you actually design the

46:33interface for your API the interface

46:36that other clients whether it is server

46:39based clients or browser based clients

46:42any kind of clients can uh talk to can

46:45interact the first thing if you are a

46:48backend engineer the first thing before

46:51you start coding before you write any of

46:54the business Logic the first thing you

46:56should do

46:57uh while creating an API is designing

47:00the interface for the API the interface

47:03should be intuitive it should be

47:05delightful to use and it should not be

47:08vague it should follow most of the

47:10standards of uh rest apis and the reason

47:14for that is the reason for following

47:18standards the reason for

47:21following restful standards is to

47:25eliminate uh confus usion eliminate

47:28assumptions or any kind of human related

47:32errors in your whole workflow what that

47:36means is let's say you are designing

47:39your apis and you did not follow any of

47:43the standards and uh whenever you should

47:47have used put you used uh post and you

47:51used delete operation to perform fetch

47:54operation ET ET you messed up the AP

47:57interface completely intentionally now

47:59as a result someone the consumer whoever

48:02that is any engineer who is integrating

48:05your API the only way the only way for

48:09them to find out all the behavior of

48:12your API starting from the successful

48:15Behavior and the error behavior and how

48:17the payloads are structured how the data

48:20is structured and what uh method to call

48:23ET the complete API integration workflow

48:27for them to figure it out completely

48:30they have only two options they have to

48:32either read your code if it is open

48:34source or it is someone within your

48:37organization who has access to your code

48:39or they have to try out different

48:41methods and see as a result of the

48:43deoration if it is expected or not and

48:48you can see that that that's a lot of

48:50room for error a lot of room for

48:53confusions and assumption etc etc now

48:56having a common standard and following a

48:59particular standard in your workflows

49:01especially when you're designing API

49:03interfaces gives you and all the

49:06consumers of your apis the advantage

49:09that they do not have to do any kind of

49:11guess work most of the behaviors are

49:14already defined in the standard so

49:17assuming that assuming the standards are

49:20uh at least 80% followed in most cases

49:24the the effort and the time to integrate

49:27the API decreases a lot when you follow

49:30standards and uh there are less bugs

49:34there are less confusions and there are

49:36less synup calls with the uh whoever is

49:39integrating your apas Etc ET because all

49:41the uh you have been following all the

49:44standards the documentations are in

49:45place you have an interactive API uh

49:47playground etc etc now there is almost

49:51no room for errors or confusions right

49:54that is the advantage of following

49:55standards following best practices so

49:58that the creator of the API and the

50:01consumer of the API already have some

50:04some kind of knowledge that this API

50:07will have these kinds of behaviors and

50:10there is no guess for involved there the

50:12first thing what is the first thing that

50:14you should do as a backend engineer when

50:16you are creating an API you should start

50:18with is from your UI design interface it

50:22could be uh figma or any other kind of

50:25software that your designer or your

50:29product team uses to build wireframes or

50:32uh user stories etc etc now that's the

50:35place you should start with when you're

50:37designing an API because when you follow

50:40the wireframe you have an idea that how

50:44the end user not the frontend engineer

50:47the engineer F consumer API will

50:50interact with it you but you will have

50:52an idea that how the end user the users

50:55who are going to use your platform are

50:58going to interact with data in general

51:02so uh usually this is how it works you

51:04have your users they interact with your

51:07platform the platform is built by your

51:11front end engineer and your front-end

51:14engineer consumes whatever API that you

51:16have built and you in turn interact with

51:20different different databases Etc as

51:21like you know the DB level so in a way

51:25when you look at the W frames the

51:27designs of how the users are going to

51:31interact with your platform you have a

51:34very good understanding of how the user

51:38the first level of consumption are

51:41related to the last the low level of uh

51:46consumption which is the database right

51:49and forgetting about all this

51:52middlemen that comes into play whenever

51:55uh we have the whole SAS platform Etc

51:58once you have the clarity on how your

52:01users are related to your data and

52:04that's an excellent point to start your

52:07actual API interface design because at

52:11this point you will find out what are

52:13the resources so since we are talking

52:15about restas the first important concept

52:18the first important

52:20entity uh that we should cover is

52:23resources now the resources are

52:25basically any any kind of nouns that you

52:29can identify from your wireframes or by

52:32talking to your clients by understanding

52:35the requirements after you understood

52:37all the requirements whether by um from

52:40the whether from the wireframes or from

52:43talking to different people the product

52:44people or client people etc etc once you

52:47have the requirements from those

52:48requirements whatever noun you can find

52:51okay of of course this is an

52:53oversimplified uh definition of what are

52:56resource in a backend workflow but

52:59mostly this rule works this is a kind of

53:03a thumb rule so whatever nouns you can

53:05find from there are your resources so

53:09imagine it is a uh project you are

53:13working on a project which is a project

53:17management SAS a project management

53:20platform okay uh something like uh jira

53:24or linear etc etc you working on a

53:27product which is similar to J linear

53:30which is a project management platform

53:32now after going through all the

53:34wireframes all the figma designs and

53:35after talking to your clients your

53:37product people you can analyze your

53:40requirements and you can find out some

53:42of the nouns that come up in those

53:44requirements what could be some of the

53:46nouns the obvious ones are since this is

53:49a project management platform it will

53:51have projects right this is the first

53:54noun what is the second noun your users

53:58obviously it's a project management

53:59platform it will have users users are

54:02another noun then you can have

54:05organizations users can be part of

54:07different different organization so that

54:09is another uh resource that you can come

54:12up with then each project will have

54:15tasks associated with it there is

54:17another noun then uh task can be um

54:21organized with different different tags

54:24so tags are another noun similarly as

54:27you can see the pattern once you have

54:29analyzed your figma designs you can

54:31easily come up with these resources and

54:34you can note it down and once you have

54:36all the resources noted down you have

54:38figured out uh what are the different

54:40different resources that your back end

54:43that your platform will have okay the

54:45nouns the top level entities after this

54:49uh usually you jump into the database

54:52schema right since uh this video is only

54:56about the rest DPA side of it which

54:58usually comes after you have done with

55:00your DB schema designs the next video of

55:02course deals with uh all the DV schema

55:05designs and different different concepts

55:06of databases so we'll skip this part how

55:11you design your DV schema how you um

55:14interact with your databases all the

55:16concepts surrounding Etc ET we'll leave

55:18this for the next video we'll focus only

55:20on the rest of part this is what the

55:22workflow looks like once you have

55:23identified all the resources from your

55:26fig designs you jump into your DB schema

55:28design and after you done with your DB

55:31schema design you get to your API

55:34interface design part since we are not

55:36talking about uh the DB schema design

55:38and all in this video we'll just do a

55:40very quick uh schema design so that we

55:43can continue to the rest API phase of

55:46the API design workflow since we have

55:49skipped the database schema design part

55:52which we'll cover in the next video

55:54Let's imagine you are done with your

55:55databas schema design and you have these

55:58three tables okay uh since it's a

56:00project management platform you started

56:02with these three tables you have the

56:04organization table where you will keep

56:06track of all the organizations that

56:09exist in your platform then you have

56:11project uh what are all the projects

56:14that exist within an organization then

56:17you have task uh inside task you will

56:20keep uh track of what are all the tasks

56:22that are created inside a project so for

56:26the sake of this demo and for the sake

56:28of this video uh we are building the API

56:32interface for a project management

56:33platform and we will get started with

56:36this schema design we have an

56:38organization table we have a project

56:39table have task table with this we will

56:42start our API design now the next thing

56:45to do we have already uh gone through

56:48our figma designs and understood all the

56:50requirements we have come up with all

56:51the nouns all the resources that we have

56:54to create and using the resources we

56:56have created all the database schemas

56:59and now we have database tables now we

57:02have we already know the resources of

57:04our platform now we need to create apis

57:07for that the next thing to do since we

57:10already have this schema the next thing

57:12to do is finding out what are the

57:15actions that a client a typical client

57:19who will interact with your API needs to

57:22perform on our server what are the

57:24actions and you can get started uh with

57:28some template actions using our crud API

57:31endpoints right uh a typical resource

57:33will have fetchall uh get a single

57:36resource update delete create etc etc

57:39right using that you will you will list

57:42out all the actions that you need to uh

57:45the users need to perform using your API

57:48which we usually call is CR operations

57:51create read update and delete and after

57:53you know all the actions you'll jum jump

57:56into the API interface design part and

58:00for the API interface design part we'll

58:02use this Tool uh which is called

58:05insomnia uh it's an alternative to

58:08postman it is an alternative to postman

58:11but it has lesser features and it's a

58:15lighter in weight as compared to postman

58:17so we'll make use of this tool to uh

58:20design the interface of our API what

58:23should the API of this platforms look

58:26like right remember we are designing the

58:28interface for this API which means that

58:31uh we are designing how clients who are

58:34going to consume our API who are going

58:37to integrate our API what the apis will

58:39look like how they will interact with

58:42etc etc right the interface point we are

58:45designing the interface Point not the

58:47execution point which includes writing

58:51whatever programming language that

58:52you're writing your server in etc etc

58:54your actual business logic

58:56your database interactions Etc ET we are

58:58not going to cover that in this part we

59:01are only going to be concerned about the

59:04design of your API okay with that uh

59:08let's start so we have identified three

59:11uh major resources in our API which are

59:14uh organization project and task right

59:18so we have to design API surrounding

59:20these three resources starting with

59:22organization and we have also identified

59:25what are the actions that clients need

59:27to perform with our a so according to

59:30those we have come up with five

59:33different kinds of actions for

59:34organization uh create organization get

59:37all organizations get a single

59:39organization and update organization

59:42delete organization etc etc right so

59:45let's start how the AP will look like I

59:47will create a new HTTP request so the

59:51first let's design the get all

59:54organizations AP so it is it will be a

59:56get API because we are doing a fetch

59:58operation right now the next thing is

1:00:01we'll write the URL of our server now

1:00:05this is subject to change uh when you go

1:00:07to production uh the domain will change

1:00:10the scheme will change from HTTP to

1:00:12https and since I am running it in Local

1:00:14Host the scheme is HTTP and the domain

1:00:17is Local Host and my server is running

1:00:20on Port

1:00:213000 that's that and since it is just a

1:00:24demo we have not uh integrated

1:00:26versioning here but usually uh apis will

1:00:29have some kind of versions here/ V1 then

1:00:31the actual path will come but here we

1:00:34are not doing versioning as of now so we

1:00:37are done with the URL part now comes the

1:00:39important part the actual route the

1:00:41actual path segment which is going to um

1:00:44identify what is that that we are trying

1:00:47to fetch from the server since it is an

1:00:50API so let's rename this to list

1:00:54organizations right

1:00:56list all organization so this is what it

1:00:59looks like right as I already said uh we

1:01:02don't put Capital case in the path

1:01:06segment so we write organization and we

1:01:08have already mentioned that uh it should

1:01:11always be plural the resource part so it

1:01:14will be organizations this is what a

1:01:17typical list uh resource API looks like

1:01:21you have the domain you have the

1:01:22versioning if it exists and then uh the

1:01:26resource name in plural so this is

1:01:29ideally the list API and when we call

1:01:33this we are getting the empty response

1:01:38okay the empty response so let's jump

1:01:40into the second API uh which is the

1:01:42create organization AP then we'll have a

1:01:45better idea about how the get one works

1:01:47right create organization and this will

1:01:50be a post operation because we are

1:01:53creating a resource in the server right

1:01:55it's a create operation that's why we

1:01:57are using the method post uh let's just

1:02:00copy this and paste this now here our

1:02:07URL looks pretty much the same for list

1:02:11organizations and for create

1:02:13organization and the reason for that is

1:02:16the server differentiates between these

1:02:19two API calls using the HTTP method if

1:02:22it is a post method then this route goes

1:02:25towards the controller which handles

1:02:27creating an organization and if it is a

1:02:30get call with the same URL it goes to

1:02:32the controller which deals with listing

1:02:34all the organizations right so this is

1:02:36what a typical create operation for a

1:02:39particular resource looks like uh we

1:02:41have the as usual the servers address

1:02:44and Slash the name of the resource in

1:02:48plural form okay now this is a post call

1:02:52so we have to attach the payload the

1:02:55data that the server needs to create an

1:02:57organization so if we look at the

1:03:01organization schema we have to exclude

1:03:04these three Fields these are database

1:03:07handled Fields right the ID the created

1:03:10it and updated it these are handled from

1:03:12the server side so we exclude these from

1:03:15the payload now these three Fields the

1:03:19name the status and the description

1:03:22these three Fields can be passed from

1:03:24the client side using a pay Lo so let's

1:03:26pass these three name status and

1:03:29description name will provide as Arc one

1:03:33status since it's a Json payload we have

1:03:36to wrap all the fields in double codes

1:03:39so second is status status let's say is

1:03:43active and the last one is description

1:03:46is some some description right and these

1:03:49are payload and when we run this we get

1:03:54this right we have have an ID which is

1:03:57created in the server s side and we have

1:04:01the created at which is also created in

1:04:03the server site and then we have the

1:04:04name status and description which we had

1:04:07passed in the payload that is provided

1:04:09here so this is the first thing that we

1:04:12should notice here in a typical post API

1:04:14call uh after calling the response is

1:04:18usually 2011 which we return when we

1:04:22create a resource in the server if a new

1:04:24resource is created cre then we return

1:04:26the status code AS 2011 which means U

1:04:30created okay and then we return the

1:04:33newly created entity as it is in the

1:04:37success response that's why we have

1:04:39received the newly created organization

1:04:40here okay this is what the typical post

1:04:43interaction looks like now going back to

1:04:46our earlier list organization when we

1:04:50call this now now we are getting the

1:04:53entry the organization that we created

1:04:56the organization that we created just

1:04:57now using the post call okay here the

1:05:00status code is 200 because 200 uh we

1:05:04return 200 status code when it is a

1:05:06successful response 2011 is when we

1:05:09create something but 20 is when it is

1:05:12just a success response we are sending

1:05:14some kind of data etc etc right

1:05:18this another thing to focus here is

1:05:21What's Happening Here uh we have a data

1:05:23field we have a total field we have a

1:05:25page field we have total Pages etc etc

1:05:29and this thing is called pagination the

1:05:32terminology is pagination and why do we

1:05:36actually need pagination the need for

1:05:39pagination pagination is basically a

1:05:41technique uh which is used in server

1:05:43side when uh we are doing some kind of

1:05:46API call where a list of a particular

1:05:50resources returned in this case we are

1:05:52requesting a list of organizations

1:05:54whenever we have an API call like this

1:05:56which returns a list of some kind of

1:05:58resource and depending on the

1:06:00requirement we use this technique we

1:06:02implement this technique which is called

1:06:04pagination what it does it does not

1:06:06return all the resources that exist in

1:06:08the database in the server side in that

1:06:11particular request right it returns a

1:06:14particular portion of the data in the

1:06:19response okay and since at this point we

1:06:22only have one organization so I cannot

1:06:24uh show you the difference but we'll

1:06:25create a couple of organization we'll

1:06:27see how the pagination works right so

1:06:29let's understand the theory first so

1:06:31this is the this is why we use

1:06:33pagination if we have a lot of data in

1:06:36the database and when the client makes

1:06:39an API call so we only return a

1:06:42particular portion of that data in the

1:06:44response so that first thing Json

1:06:47serialization and deserialization as we

1:06:50have already covered in the previous uh

1:06:52some video that is a heavy operation

1:06:54right so if we let's say send a,

1:06:58organization in the response so

1:07:01serializing a th000 organizations into a

1:07:04payload which is transferable across uh

1:07:08internet is a resource heavy task right

1:07:12it can introduce some kind of delay in

1:07:15our API it can have some kind of

1:07:17performance impact so that is one reason

1:07:20the second is if the server takes a

1:07:23little longer to send the response then

1:07:26the client uh the whatever the front end

1:07:28platform that is requesting that is

1:07:30using this API that will also have some

1:07:33kind of perceived delay and the user the

1:07:36end user who is using the platform they

1:07:39will notice the difference right they

1:07:40will notice there is some kind of 3

1:07:42seconds and 4 seconds of delay that is

1:07:44happening because the client is fetching

1:07:46a thousand organizations in the list API

1:07:49call even though even though the on the

1:07:53first look on the first look when

1:07:55someone is using the platform they will

1:07:58only see let's say a 10 or 20

1:08:00organization right if they want to see

1:08:03more organization they'll obviously have

1:08:05to scroll right now because of that kind

1:08:08of scenario people have come up with

1:08:10this technique called page nation in

1:08:12page Nation what happens in the initial

1:08:14call you return some portion of data

1:08:17usually from the first and sorted by

1:08:19some parameter let's say the created

1:08:21parameter you return the latest 10

1:08:25organization in the first API call right

1:08:29then when the user the end user clicks

1:08:31on page two or if it's an infinite

1:08:33scroll Scrolls down you make another API

1:08:37call and you say this part I already

1:08:40have give me the next portion this

1:08:43portion of the data right and then you

1:08:46take this and you show it to the user

1:08:48similarly when the user goes on page

1:08:50three you ask for this portion and you s

1:08:53this data and this is how it works at at

1:08:55once you only fetch let's say 20 or 30

1:08:58organizations and show it to the user so

1:09:00the user is also not overwhelmed network

1:09:03is not overwhelmed and the client in

1:09:05server perform better and that is the

1:09:07advantage of pation and this is often

1:09:10used whenever we are implementing some

1:09:12kind of list API so in this case we are

1:09:16listing organizations right that's why

1:09:19we have implemented pagination here now

1:09:21the second thing to notice here is what

1:09:24are the fields that we are returning

1:09:26from in a pag response the first part is

1:09:29data whatever portion of the data we

1:09:31have to return that we return in the

1:09:33data field the second is total now this

1:09:37total field Returns the total count of

1:09:40all the organizations that is in the

1:09:43database and using this information the

1:09:46client can s some kind of metadata to

1:09:49the user that um you have around 50

1:09:53organization but at this page you are

1:09:55only viewing 10 right it can show some

1:09:58kind of UI like this 10 or 50 something

1:10:00something so for representation purpose

1:10:02for UI purpose we return a field which

1:10:06which uh shows the total count of all

1:10:09the resources that exist in our database

1:10:12which is independent of what portion of

1:10:15the data we are returning it is

1:10:16independent of the page response next is

1:10:19we return the Page Field uh which page

1:10:22which portion of data that the server is

1:10:25is returning for this response this

1:10:28response which page it is associated

1:10:30with which portion it is right we have

1:10:33to assign some kind of number some kind

1:10:36of identifier the portion of the data

1:10:39that we are asking from the server

1:10:41that's the reason we call it a page and

1:10:44in this the server is saying this

1:10:46response is for page one you are doing

1:10:50page one then we return total Pages how

1:10:52many pages in total there are and we can

1:10:55use this to show some kind of nice UI

1:10:58interactions or uh if it's an infinite

1:11:00scroll we can check for each time we are

1:11:03making the API call we can check whether

1:11:06uh the page and the total Pages if they

1:11:09are both same then we stop making the

1:11:10API call so because now that we know

1:11:13that uh we have reached the end of the

1:11:15pages right so this also provides some

1:11:19nice functionalities it helps the front

1:11:22end make some decisions about whether to

1:11:25make the next API call or not etc etc

1:11:28this is what a typical paginated

1:11:31response looks like now let's go to the

1:11:34create a and create a few more

1:11:36organizations right let say organization

1:11:392 oration three organization 4 oration

1:11:44five okay we've created Five

1:11:47organizations and when we go to the list

1:11:50API and we call this we're getting all

1:11:53five now that we have

1:11:55around five organizations how do we

1:11:58access let's see how the pageon actually

1:12:01works and how the client can ask for

1:12:04different different portions of the data

1:12:06using different different parameters

1:12:08since it is a get call the only way we

1:12:11can send data from client to server some

1:12:13kind of payload data is using query

1:12:16parameters now the server takes two kind

1:12:18of parameters for controlling how the

1:12:21pagination works the first one is limit

1:12:23limit basically means what is the count

1:12:26of data that you want in each response

1:12:29since we have five entries five

1:12:32organizations what if we do limit is two

1:12:36each time we only want two organizations

1:12:38right the second parameter is page which

1:12:42portion of the data that you want by

1:12:45default if we don't send page and limit

1:12:48the server should and remember since we

1:12:51are in designing the interface try to

1:12:54focus what are the points uh the server

1:12:56should Implement right if the client

1:12:58does not send anything in limited page

1:13:01the server should set some kind of

1:13:03default values for these so by default

1:13:06the server sets the value of page as one

1:13:10if the client does not send any kind of

1:13:13uh parameter in the page parameter same

1:13:15way the limit will be set to something

1:13:17like 10 or 20 if the client does not

1:13:19send it but here we are explicitly

1:13:21sending it so let's make this request

1:13:25what happens when we do limit two and

1:13:27when we make this request the server

1:13:29returned us two organizations sorted by

1:13:32created at know the latest organizations

1:13:35that's why we are getting organization

1:13:37five and organization four because

1:13:39that's the order that we created we

1:13:41first created organization 4 then

1:13:42organization 5 that's why we are getting

1:13:45in this order okay second in total the

1:13:48server is returning how many entries are

1:13:51present in the database yes we have five

1:13:53organizations but we are returning two

1:13:56okay because the client has passed the

1:13:58limit as two then which portion of the

1:14:01data that the server is returning which

1:14:02is which page the server is returning

1:14:05which is page one and how many pages are

1:14:08there in total there are three pages

1:14:10because if the limit is two and the

1:14:14total number of organizations are five

1:14:18then then to send all the data to

1:14:21clients the server has to make three

1:14:24pages in The First page there will be

1:14:25two entries in the second page there

1:14:27will be two entries in the last page

1:14:28there will be one entry okay that's how

1:14:30pation works so when we do page as two

1:14:34and we keep the limit as two and then we

1:14:37make this request this is what we get we

1:14:40get organization 3 and organization two

1:14:42in the response basically we have this

1:14:47whole data portion where we have let's

1:14:50say uh organization 5 4 3 2 and one when

1:14:55we make page as one we get organization

1:14:59five and organization 4 basically this

1:15:02portion when we make Pages two we get

1:15:05this portion right three and two and at

1:15:09the last when we'll make page three we

1:15:12should ideally get only the organization

1:15:14one because in the in the last page

1:15:17there is only one

1:15:19entry let's change this to page three

1:15:22and we got organization one and single

1:15:25response because we are asking give us

1:15:28the page three the last portion of the

1:15:30data so the total is five the current

1:15:33page is three and the total pages is

1:15:35three okay these are basically the

1:15:37metadata about what is the current state

1:15:41of pation and this is how the client can

1:15:43and the client should interact with your

1:15:45apis right you should allow for a limit

1:15:49parameter and a page parameter so that

1:15:51the client can uh conditionally and

1:15:53programmatically access different

1:15:54different portions of the data so that's

1:15:57pretty much all about pagination how the

1:15:59server should Implement pagination okay

1:16:03a typical list API also has other

1:16:06parameters let's say let's get rid of

1:16:08this okay let's get rid of these we

1:16:11don't want to uh look at page Nation

1:16:13anymore and when we send this we get all

1:16:15the five organization because by default

1:16:17the server sets the limit s 10 or some

1:16:20random value because even if the client

1:16:22does not send anything in the limit

1:16:24parameter the server should set some

1:16:27number as limit and page one as default

1:16:31parameters right now let's talk about

1:16:34sort in a typical list API we a server

1:16:38should also support sorting and this is

1:16:41how it looks like we can pass one

1:16:44parameter for defining by which field we

1:16:48want to sort by okay it is typically

1:16:51written as sord by and here we can

1:16:54provide the name of the field that we

1:16:55want to sort by so here let's say we

1:16:59want to sort by name we are saying we

1:17:01want to sort by name okay and when we

1:17:03send this you're getting oration 5 4 3 2

1:17:061

1:17:08okay no difference as of now now let's

1:17:11add another parameter which is called

1:17:14sort order

1:17:16and here let's send ascending and when

1:17:20we do that here as you can see by

1:17:22default the server was returning all the

1:17:27organizations in the descending order so

1:17:30by now you should have realized this

1:17:32rule the rule that the server should

1:17:36ideally ideally take as many as it can s

1:17:41defaults and by S defaults I mean it

1:17:44should not depend on the client to send

1:17:47obvious fields for example in a list API

1:17:51by default even if the client does not

1:17:53send anything we still got a response

1:17:56right we did not get any validation

1:17:57error that you are missing this

1:17:58parameter you're missing the page

1:17:59parameter um that made our whole

1:18:02experience way better because we did not

1:18:04have to pass obvious Fields obvious

1:18:07fields are such as page if the client

1:18:10does not pass the any explicit page the

1:18:14server should set the default pages one

1:18:17similarly for limit if limit is not

1:18:19passed you should set a default limit

1:18:22either 10 or 20 something okay same way

1:18:26even if the client does not do any kind

1:18:29of manual or explicit sorting the server

1:18:32should do some kind of sorting by

1:18:35default so that the response of the data

1:18:38does not change between different

1:18:40different API calls if you don't sort by

1:18:43some parameter in the server before

1:18:44sending the response each time the

1:18:47client makes an API call it will get the

1:18:49response in a random order because the

1:18:51database does not store and entries in

1:18:55any kind of sequence you have to

1:18:57explicitly do sorts that's the reason by

1:19:00default if you're creating an API

1:19:02especially a list API you should have

1:19:05some kind of default sort parameters so

1:19:08by default what uh we usually do we take

1:19:12the created at field take the created at

1:19:15field and we sort by this field and sort

1:19:18by what order we sort by descending

1:19:20order now this is the natural state the

1:19:23default state of sort even if the client

1:19:25does not pass anything because it's a

1:19:28obvious response right we want to list

1:19:32all the entities all the resources in

1:19:35the descending order of their creation

1:19:38basically all the latest entries right

1:19:40that is a natural thing to assume from

1:19:43the server side that's the reason this

1:19:45is considered a s default when it comes

1:19:48to sorting scenarios in list apis but if

1:19:51the client does want to do some kind

1:19:54kind of explicit setting the server

1:19:56should also support two parameters for

1:19:59sorts one is sort by by which field of

1:20:04the resource that you want to sort by it

1:20:06can be name it can be status it can be

1:20:09ID Etc it depends on your implementation

1:20:12but it should have some uh fields from

1:20:15the resource entry same way uh we should

1:20:19take another parameter which is called

1:20:20sort order what order the client wants

1:20:24the sort to happen in by default again

1:20:27even if the client passes a sort by

1:20:29field you will still have to set the

1:20:32default that sort order if not passed

1:20:34you should set it as descending that is

1:20:36the reason when we did not pass any sort

1:20:39order we still got our data our response

1:20:42sorted by name in descending order

1:20:44because descending is the default state

1:20:47of sort order that the server sets even

1:20:50if the client does not send any sort

1:20:52orders but if the client sends ascending

1:20:56as sort order then the server takes that

1:20:58into account it takes the field it sorts

1:21:01names in ascending order that's why we

1:21:03got organization 1 2 3 4 5 in the

1:21:06ascending order this is how sorting is

1:21:09implemented in a typical list API we

1:21:12have covered page naations we have

1:21:13covered sorting there is one last thing

1:21:16that is usually supported in a list API

1:21:19which is called filtering so let's

1:21:22remove this and and what filtering means

1:21:25is um even if it's a list API the client

1:21:30wants to filter that list by some

1:21:32parameters right so let's say let's go

1:21:36and create an organization in the body

1:21:38we see organization as six and in the

1:21:42status instead of active we do archived

1:21:46and we create this and this is created

1:21:48and we got a 2011 response now we go to

1:21:51list and when we send this we are

1:21:52getting this or oration six the latest

1:21:56one right and the status is archived now

1:21:59what if the client has some kind of

1:22:02button some kind of switch using which

1:22:05the user can filter the list by saying I

1:22:09only want all the organizations whose

1:22:11statuses are active or whose statuses

1:22:15are archived basically some kind of

1:22:17filter functionality and this is how we

1:22:20add support for filteration in a typical

1:22:23list API so so we take the name of the

1:22:26field uh so let's say the client wants

1:22:28to filter by status so we add a

1:22:31parameter which called status and inside

1:22:34this the client can pass what is the

1:22:37status that it wants to filter by so if

1:22:42we pass archived and when we send this

1:22:45we only get the list of all the

1:22:48organizations whose status is archived

1:22:51same way if you pass active and when we

1:22:53send this we only got all the

1:22:56organizations which has the status as

1:22:59active and this is called filter okay

1:23:03and is just one field we can also filter

1:23:06by other fields so let's say uh we add

1:23:10another parameter and the filter is name

1:23:13one the list of all the organizations

1:23:15whose name is let's say or and when we

1:23:18send this we are getting only one

1:23:20response because um in this scenario in

1:23:23this example we only have one

1:23:25organization which has the name r for

1:23:28and that's the reason the API is

1:23:29returning this okay so with that we have

1:23:33covered pagination filtering and sorting

1:23:37all the features that a typical list API

1:23:41should have okay now moving on let's

1:23:44create an update API create a new

1:23:46request and it is a patch request right

1:23:51the thing is I have personally not used

1:23:54used a put implementation of an update

1:23:57APA as much because usually what we do

1:24:00we take some fields of a resource of an

1:24:04entity and we want to update those we

1:24:06never want to replace the whole entity

1:24:09with a payload that is passed from the

1:24:11client okay uh it it was usually a

1:24:14practice when we were building MPS or

1:24:17multi-page applications but in the

1:24:19single page applications where the data

1:24:21is mostly Json heavy we usually pass

1:24:25partial fields of a resource and we only

1:24:27want to update those fields so mostly

1:24:31you will see patch getting used for

1:24:33update appear instead of put and that is

1:24:36usually best practice because um if it's

1:24:39partial Fields then patch conveys that

1:24:42semantic meaning in a better way as

1:24:45compared to put which is a little

1:24:46confusing uh but mostly developers use

1:24:49put and Patch interchangeably so try to

1:24:52stick to the standards uh you patch

1:24:54whenever you are updating partial Fields

1:24:56oft a resource okay it's a patch request

1:24:59and we have to uh provide the servers

1:25:01URL so the servers URL is this one paste

1:25:06it here organizations now which

1:25:08organization that we want to update so

1:25:11this is where a dynamic parameter comes

1:25:13into play we have already explored what

1:25:15are Dynamic parameters etc etc and our

1:25:18routing video so for now we'll just go

1:25:21ahead and use it so Dynamic parameter is

1:25:23usually uh some kind of string that we

1:25:26can arbitrarily pass so let's fetch the

1:25:30list and let's say we want to update

1:25:33this we want to update the status of

1:25:36organization 6 so let's copy the ID and

1:25:38we take the ID and let's rename this to

1:25:41date organization okay and as usual this

1:25:46is the server's address we have the path

1:25:49which is the plural form of the resource

1:25:51organizations and after this we write to

1:25:54the slash we paste the idid of the

1:25:56organization and this is a valid route

1:25:59for a patch API con okay we want to

1:26:03update a single organization that's why

1:26:06we are passing the ID of the

1:26:07organization in the dynamic parameter

1:26:09now the pass request takes a body and

1:26:12we'll send a Json inside the Json want

1:26:15to update the status of the organization

1:26:19and the status is the existing status is

1:26:22archived we want to make get active Okay

1:26:25and let's call this and we call this we

1:26:28are getting the organization six and the

1:26:32status is active we are successfully

1:26:35updated it the updated the value of the

1:26:38status field and when we go to the list

1:26:40API call and we call this we are getting

1:26:43the status is active for organization 6

1:26:46now uh the typical response for an

1:26:49update or a patch API call the success

1:26:52response is uh the client sends the

1:26:55payload in the body and the server sends

1:26:57a 200 response since it did not create

1:26:59any resource it is a successful API call

1:27:02that's why it is sending 200 the

1:27:05response the success response and in the

1:27:08response we are sending the updated data

1:27:11of the organization okay this is what

1:27:13the typical practice looks like for a

1:27:16patch IPI call now similarly what if we

1:27:19want to fetch the information of a

1:27:22single organization we want to patch the

1:27:24information so that's why it'll be a get

1:27:26call so let's first copy copy this and

1:27:29create a new request let's rename this

1:27:33to get okay get AR and this is a get

1:27:37call and let's paste this one and

1:27:40getting the information of a single

1:27:43organization and updating the

1:27:45information of a single organization and

1:27:47deleting a single organizations mostly

1:27:49what you will see all these three apis

1:27:52the get update and delete for aing

1:27:54single organization the route will look

1:27:56similar we'll have the server address

1:27:59we'll have the path parameter with the

1:28:01plural form of the resource and with a

1:28:03slash with a forward slash we'll have

1:28:05the ID in the dynamic parameters place

1:28:08okay this is what the route will look

1:28:10like and since it's a get call we uh

1:28:14don't pass any body or anything and we

1:28:16can just execute it and we got the

1:28:18information of the organization we have

1:28:20passed the ID of the organization 6 and

1:28:22we got the organization six with status

1:28:25code 200 because it is just a successful

1:28:27response we did not create anything we

1:28:29just fetched information okay at last we

1:28:33have a delete call we want to delete an

1:28:36organization so let's uh create an HTTP

1:28:39request and rename this to Arc and the

1:28:43method is delete let's paste this as I

1:28:47said the get call update call and delete

1:28:49call of a single organization apis will

1:28:52look similar the route will look similar

1:28:55the only thing that will differentiate

1:28:57them is the method whether it is a get

1:28:59method whether it is a patch method or

1:29:02it is a delete method okay and we are

1:29:04not sending anybody we are just sending

1:29:07the ID of the organization in the

1:29:09dynamic parameter and we execute this

1:29:11and when we execute this we do not get

1:29:13anything uh the response is empty but we

1:29:17got a different status code which is

1:29:19which is

1:29:21204 which means no content the server is

1:29:24saying that whatever uh operation that

1:29:28you're trying to do it was successful

1:29:29that's why the status code starts with

1:29:32200 series right 200 series all the

1:29:35codes in the 200 series are success

1:29:38responses whatever you're trying to do

1:29:40you trying to delete a resource that was

1:29:42successful but there is no content I can

1:29:45send you because it is a delete

1:29:47operation and it is successful you

1:29:50successfully deleted the organization

1:29:52there is no information about the

1:29:54organization that I can send you that's

1:29:56what the server is saying that's why we

1:29:59did not get any response in the response

1:30:01of the delete API call and this is the

1:30:03usual practice whenever we have a delete

1:30:04API call uh we send an empty response

1:30:07with status code 204 and now when we go

1:30:11back and we get the list organization we

1:30:15are getting the organization from

1:30:16organization 5 because we deleted the

1:30:18organization six and what happens uh

1:30:21when we come to the get call the get

1:30:24single organization API call and we run

1:30:26this we are getting organization not

1:30:30found as an error message and in the

1:30:32status code in the status code we are

1:30:35getting 404 so this is an ideal use case

1:30:39for status 404 which basically says that

1:30:44you are requesting a particular entity

1:30:47you are requesting a particular entity a

1:30:49particular resource which has the ID

1:30:51this one and that resource does not

1:30:54exist in the server since we have

1:30:55already deleted this that does not exist

1:30:58in the server that's why we are wrting

1:31:00returning error code of 404 which means

1:31:03resource not pound okay but in the list

1:31:08API call we do not get any error even if

1:31:12there are no organizations in the list

1:31:14it is empty we still do not get an error

1:31:17because in list API call we are not

1:31:20requesting for a particular resource we

1:31:22are requesting a list list of the

1:31:24resource right a list of organizations

1:31:26that is the reason we never send four

1:31:29or4 responses in list API calls a 404

1:31:33response is usually sent when the client

1:31:36is sending a particular resource ID okay

1:31:40a particular resource a single resource

1:31:42or a bunch of resource in different

1:31:44different

1:31:45representations when the client request

1:31:47for a particular number of resources or

1:31:49a single resource that is the use case

1:31:52when we should send a 404

1:31:54but if it is a list API call and we

1:31:56don't have any data let's say the filter

1:31:58does not match any data let's say in the

1:32:00params we pass a filter so we pass

1:32:05status filter and here instead of active

1:32:07and archived we pass some uh random

1:32:11value some random value and when we

1:32:14execute this we are getting data as an

1:32:18empty array and total is zero page one

1:32:21total Pages zero this is the kind of

1:32:23response we get in a list API call this

1:32:25response code is still 200 because it is

1:32:29a this is a list API call if you notice

1:32:31this we are not requesting a particular

1:32:34organization a particular resource that

1:32:37is the reason we should not throw 404

1:32:39here even if we have no data for this

1:32:42filter we do not say resource not found

1:32:45we say the data is empty this is a thumb

1:32:48rule that you have to remember that if

1:32:50it's a list API call and there is no

1:32:53data you should return an empty array

1:32:54with 200 response instead of returning

1:32:57404 404 is only return When the client

1:33:00is requesting for a particular entity

1:33:02which does not exist in the server okay

1:33:05with that we have covered all the CED

1:33:07operations C basically means create read

1:33:10in the read we have get and list we have

1:33:13update and we have delete cow operations

1:33:16we have covered all the crow operations

1:33:18and this is how the typical crowd

1:33:19operations based API design interface

1:33:21will look like now what we have a custom

1:33:24action by custom action I mean we want

1:33:27to perform some action on the server

1:33:31which does not fall under any of these

1:33:34categories it is not a create operation

1:33:36it is not a get operation or an update

1:33:37or a delete operation it is a particular

1:33:40action that we want to perform on a

1:33:43single organization entry let's say this

1:33:45is organization five and we want to

1:33:48Archive organization 5 okay now

1:33:52archiving an organization

1:33:54you can on the first look you can

1:33:56imagine that if we update the status

1:33:59field of an organization to status

1:34:02archived then it is archived right so

1:34:05ideally it should fall under patch right

1:34:09but that is not the case you want to

1:34:11perform some action you want don't want

1:34:14to update an entity even though at the

1:34:16end of the day it is updating the entity

1:34:19uh you are updating organization five

1:34:21from status active to archived but at

1:34:24the end of the day it is an custom

1:34:26action because let's say you want to

1:34:29Archive organization five right you want

1:34:32to make the status from active to

1:34:36archived now this is the action that you

1:34:38want to perform but you cannot simply

1:34:40just update the status field because

1:34:42when an organization is archived a lot

1:34:45of operations will have to be performed

1:34:48maybe all the projects that resides

1:34:50under that organization will also have

1:34:52to get get removed get deleted or some

1:34:55kind of operation maybe the users that

1:34:58are involved in that organization have

1:35:00to be sent notifications or they have to

1:35:04be sent emails right and all the tasks

1:35:07that fall under all the projects that

1:35:09fall under all the organization they

1:35:11have to be deleted right lot of actions

1:35:13have to be performed from server side

1:35:16when a particular organization is

1:35:18archived that is the reason updating the

1:35:21status field of an organization from

1:35:23active to archived is not actually

1:35:26archiving an organization it at the end

1:35:28of the day is an custom action you want

1:35:31to Archive an organization so now we

1:35:34have a use case where we want to perform

1:35:37some kind of custom action in this case

1:35:41the action is want to Archive a

1:35:45particular organization you want to

1:35:46perform this custom action on the server

1:35:48side for a particular organization right

1:35:51now as I have mentioned before whenever

1:35:54we have a use case which does not fall

1:35:57under any of the crud flows it is not a

1:36:00create get delete or update method then

1:36:03we can use post with the custom action

1:36:07to construct an API call to execute that

1:36:10custom action in the server set so let's

1:36:13do that in the next API we'll create a

1:36:17new request and let's rename this to

1:36:20Archive archive organization right and

1:36:25here from the name also you can see that

1:36:29up until here we have crud endpoints we

1:36:32have delete get update create list right

1:36:34from the names you can see that these

1:36:36are crud operations but at the end we

1:36:39have archive this is not a cud operation

1:36:42that's why we are classifying it as a

1:36:45custom action okay now how do you

1:36:47perform customer action we make it a

1:36:50post call we make it a post call then we

1:36:54take uh let's say uh let's execute this

1:36:58let's remove this and the ID of

1:37:01oranization 5 is this we take this ID

1:37:04let's paste this here and before that we

1:37:05need the servers address for that this

1:37:10one is the address let's spacee this

1:37:12here and here we have the service

1:37:15address here there is the root path with

1:37:18the organizations then we have passed

1:37:22which organization like we want to

1:37:25Archive organization five that's why we

1:37:27are passing the ID of organization five

1:37:30then at last we want to write the action

1:37:33that we want to perform so in this case

1:37:35it is an archive operation this is an

1:37:38archive action we have written archive

1:37:41now we have the route ready okay and if

1:37:44you notice here this completely follows

1:37:47a hierarchical relationship that we had

1:37:50uh mentioned earlier we have the service

1:37:53address so ignore this part from this

1:37:56path segment we can see that we have all

1:37:58organizations inside all organization we

1:38:00have a single particular organization

1:38:02and for that organization we want to

1:38:05perform some action so it is a clear

1:38:07hierarchical path that your API endpoint

1:38:10should ideally fall now when we execute

1:38:13this we are getting a response and in

1:38:15the response we have the organization

1:38:18five and the status is archived we have

1:38:21made organization five from status

1:38:24active to status archived as a custom

1:38:27action with post end point right and

1:38:30even though we have used post here we

1:38:32still got the Response Code as 200

1:38:35that's the reason you should not blindly

1:38:38assume that every post call will have

1:38:40the Response Code of 2011 which is the

1:38:43creator Response Code because there

1:38:46could be also custom actions custom

1:38:48actions like these which will return 200

1:38:51because they did not create any resource

1:38:53they will return 200 for custom API

1:38:56calls for custom action based API calls

1:38:59okay now with that we have covered all

1:39:02the API endpoints for the schema for the

1:39:05data model organizations okay now with

1:39:07that we have covered all the API end

1:39:10points for organization this schema now

1:39:14let's move on to projects right we will

1:39:16do this one more time uh so that you can

1:39:20internalize all the patterns that we are

1:39:22using while while designing our

1:39:24endpoints all the patterns that we are

1:39:26using while designing the interface of

1:39:29our API okay okay so now let's continue

1:39:35designing all the apas for projects

1:39:37right projects endpoints so going back

1:39:39to

1:39:40insomnia uh what I've done here I have

1:39:43created a folder called org and I've

1:39:46moved all the organization based

1:39:48endpoints inside the org folder so that

1:39:51it's easier to manage now that we'll be

1:39:52creating

1:39:53all the endpoints for projects this part

1:39:56is categorized as organization endpoints

1:39:59now we can minimize this create another

1:40:01folder and we'll name this as project

1:40:04and under this let's this let's create

1:40:08our first request which will be a post

1:40:12request and this time we'll do this L

1:40:15still faster since I've already

1:40:16explained all the concepts behind it in

1:40:18the previous endpoint creation flows so

1:40:21this time we'll just uh Focus Fus on the

1:40:23patterns but we'll move faster so we

1:40:27have the servers address which is htdp

1:40:30Local Host and the port is

1:40:343,000 slash since we are designing now

1:40:38the endpoint for project that's why as

1:40:41our pattern says the plural form of the

1:40:44resource in small case which gives us

1:40:48projects okay now this is for the post

1:40:53AP call okay now this route is ready now

1:40:57now what should go in the body since

1:40:59post request uh we are creating a new

1:41:02project what should go in the body a

1:41:04Json payload in the Json payload we can

1:41:08basically send name organization ID

1:41:12status description because the ID

1:41:14created at and updated at are server

1:41:16handle fields we do not uh accept that

1:41:19from the client payload we are only

1:41:22accepting name organization ID status

1:41:24and description so name will be some

1:41:26project name then organization ID will

1:41:29be some organization ID that is already

1:41:31existing and the status will be let's

1:41:33say planned and the description will be

1:41:35some kind of description okay so let's

1:41:38come here and name is let's say project

1:41:43one then we have

1:41:46organization id id is some random ID for

1:41:51now let's not worry about that then we

1:41:55have status let's say it is planned and

1:41:59in the end we have description the

1:42:02description we can pass some back okay

1:42:06now we have the payload ready now

1:42:08another thing to notice here is any kind

1:42:10of Json payloads whether it is a Json uh

1:42:13any kind of Json data whether it is a

1:42:15payload that we send from client to

1:42:17server or it is a response that we

1:42:20receive from server to client it should

1:42:22always follow the fields should always

1:42:25follow camel case right that is a common

1:42:29standard when it comes to Json so that

1:42:32is something you have to keep in mind

1:42:34whether you are accepting payloads or

1:42:35you are giving responses from server

1:42:37side always try to stick to Json

1:42:39standards if you are using Json as your

1:42:42calization format uh that way uh clients

1:42:46do not have to do a lot of guess work

1:42:48because it is already established

1:42:50pattern that Json Fields always follow

1:42:53camel case okay now let's hit this and

1:42:58we got a status 2011 because a new

1:43:01project is created and we got all the um

1:43:05fields that we have passed and the

1:43:07project entity that is created the

1:43:09typical create a using post let's go

1:43:12ahead and let's create another request

1:43:15and it will be a let's rename this to

1:43:18create project and we'll name this one

1:43:22to list project okay and this will be as

1:43:27usual a get call and we can copy the

1:43:29route of the post call because as I've

1:43:33already mentioned the routes of create a

1:43:37resource and list resource will most of

1:43:40the time look similar and the routes of

1:43:44get a single resource update a single

1:43:46resource and delete a single resource

1:43:48will most of the time look similar

1:43:50because of the semantic meaning that

1:43:53comes with them right so we don't have

1:43:55to make any other changes here it is a

1:43:59list call and when we send this the

1:44:02server senses all the projects that is

1:44:04inside the database okay so in the

1:44:07create one we can create a few more

1:44:09project

1:44:11two project 3 and in the list we can go

1:44:15ahead and we can do different different

1:44:18parameters can pass limit as one right

1:44:23if you pass limit is one we only get one

1:44:25response but when we add page with limit

1:44:30and the page is two here we are getting

1:44:32project three but when we are sending

1:44:35limit one and page two we'll ideally get

1:44:38project two because it is the next

1:44:40portion of the data that we are fetching

1:44:42from the server similarly this will also

1:44:44have sorts this will also have filters

1:44:46that we have already discussed in the

1:44:48previous endpoint while we are uh

1:44:50dealing with list organizations endo

1:44:53right we have create projects and we

1:44:55have list projects now another thing I

1:44:57want to mention here is when you are

1:44:59designing apis uh for a particular

1:45:02platform right as long as you are inside

1:45:05a single project so all the apis inside

1:45:09that project does not matter what the

1:45:11resources are here we have two resources

1:45:14we have organization and we have project

1:45:16but across different resources your

1:45:19query parameters and your Json payload

1:45:21should look similar and what I mean by

1:45:24that is let's say in the create

1:45:27organization if you see the body you can

1:45:30see the name uh the project has an

1:45:33organization has name and it has

1:45:35description and we are expecting those

1:45:37fields from the client now similarly in

1:45:39the create project also we have name and

1:45:42we also have description that we are

1:45:43expecting from the client now the point

1:45:46I'm trying to make here is you should

1:45:48always try to be consistent when it

1:45:51comes to the Json payloads so so in the

1:45:54create organization API you made

1:45:55description the key of description like

1:45:58this so in the create project API also

1:46:01we have to uh you should keep the key

1:46:05similar you should not like go ahead and

1:46:08DSC right this also expresses that this

1:46:11field is associated with the description

1:46:14field but since you already have an API

1:46:17where the Json payload contains a

1:46:20description field from that point on all

1:46:22all the apis that you design should

1:46:24follow a consistent pattern and if it's

1:46:27a description field then you should only

1:46:31uh then you should try to match that you

1:46:33should not try to rename Fields when the

1:46:37context is the same because because

1:46:40usually what happens when a front end

1:46:42engineer when some kind of client right

1:46:46they integrate your API they consume one

1:46:49API they integrate one API and from that

1:46:51point on that frontend engineer that uh

1:46:55client they make a lot of assumptions of

1:46:58how your API functions they make

1:47:01assumptions that let's say this is a

1:47:03create organization API right from this

1:47:05point on when they want to integrate the

1:47:08project endpoints they will make a lot

1:47:11of assumptions that the since the

1:47:13project also has a name field since the

1:47:15project also has a description field

1:47:17this is what the payload will look like

1:47:18for a project and it did look like that

1:47:21because that's the way you have designed

1:47:23it but imagine if you made the

1:47:26description field as

1:47:28DSC and the client the front end

1:47:30engineer without looking at the docs

1:47:32without looking at the specs of your API

1:47:35they executed the API right with the

1:47:38description field and they get a

1:47:39validation error now of course uh during

1:47:42development these kind of these kinds of

1:47:44things happen and that's totally fine

1:47:47but the point is you should not waste um

1:47:50the people who are integrating your AP

1:47:53you should not waste their time and you

1:47:55should not waste their effort you should

1:47:56not make them do guess work right your

1:48:00API should always follow a consistent

1:48:02pattern whether it comes to routes or

1:48:04whether it comes to payloads whether it

1:48:06comes to responses always follow

1:48:08consistent pattern once you create an

1:48:11API stick to that standard whatever

1:48:13styling that you have followed stick to

1:48:15that not make arbitrary decisions across

1:48:18different different resources for

1:48:20different different end points right

1:48:22always be consistent that's one of the

1:48:24most important characteristic of a good

1:48:26backend engineer the consistency of

1:48:30styling when it comes to API design

1:48:33similarly for list for create

1:48:36organization here we followed this

1:48:37pattern where uh the route is

1:48:40organizations the plural form of the

1:48:42resource now for the projects part let's

1:48:45say if we had did just project right now

1:48:48the person who is integrating your API

1:48:51judging and assuming from your create

1:48:54organization API they'll they'll assume

1:48:57that the create project API must also

1:49:00follow the plural form right because

1:49:02that's what the organizations API

1:49:04followed so if you do not follow the

1:49:07same style if you do not be consistent

1:49:10then they'll also get an error at that

1:49:12then they have to figure out they have

1:49:13to read the specs they have to read the

1:49:15documentation etc etc right which is a

1:49:18lot of drag and that is the reason uh

1:49:20that is the importance of sticking

1:49:22sticking to a particular style sticking

1:49:24to a global standard now let's move on

1:49:28let's create the rest of the apis we

1:49:31also have a get API let's create the

1:49:34rest of the apis we also have a get

1:49:37project API so what we can do copy this

1:49:41let paste this we have projects and up

1:49:44to this point we have to pass the

1:49:46project ID because it is a single

1:49:49project fetching API it is a get API

1:49:51which fetches a single projects that's

1:49:53why in the dynamic parameter you have to

1:49:55pass the ID of the project now let's

1:49:59execute this uh list projects and list

1:50:02this parameters and execute this let's

1:50:05copy some ID and in this let's rename

1:50:09this one to project and let's paste this

1:50:13ID and when we execute this we got the

1:50:16response for a single project right

1:50:18ideally uh with the Response Code of 200

1:50:22similarly let's go ahead and create the

1:50:27update API let's rename this project

1:50:30okay and here also we can let's copy the

1:50:34get project and here we can paste it as

1:50:37I've already mentioned the routes of get

1:50:40single resource update single resource

1:50:42and delete single resource will always

1:50:44look similar because of the semantic

1:50:46meaning that they represent behind the

1:50:48scenes now this is an update API so will

1:50:52do patch because we are sending partial

1:50:54Fields right and this will re require

1:50:57some kind of body so this what should we

1:51:00update the description let's update the

1:51:02description we are say the description

1:51:04is the existing description is some

1:51:07random value we'll change it so in the

1:51:09body we can send partial Fields so we

1:51:13just need to send the value of the new

1:51:15description field and here we can say

1:51:18that new description okay and when we

1:51:21send this we get a 20 when we send this

1:51:24we got a 200 response because it is a

1:51:26patch request and we got the updated

1:51:29entity and as you can see the

1:51:31description is new description yeah

1:51:33that's the typical behavior of patch

1:51:35similarly let's implement the delete

1:51:38request this one inside project new

1:51:41request and let's rename let's rename

1:51:45this to delete project okay and we can

1:51:49just copy this because it is a single

1:51:52project API and we make this method as

1:51:56delete and there will be no body Etc

1:51:59right and I can send this and as usual

1:52:04since it is a delete method we got a 204

1:52:07no content response and there is nothing

1:52:10in the response because it is a delete

1:52:12request and at last we have a custom

1:52:15action so in case of project we have a

1:52:17requirement that the client the front

1:52:20end can clone a particular project and

1:52:24when they clone it what happens that

1:52:27project all the values of that project

1:52:29gets cloned and a new project with a

1:52:32different ID is created in the database

1:52:34with that other operations might also

1:52:36get executed in the server side which we

1:52:39don't know about that is the reason it

1:52:41is a custom action and it is not a

1:52:44create action we could have also done

1:52:46that uh the client would also call the

1:52:49create project API and it could take all

1:52:52the values from the existing project it

1:52:54could pass uh all of them in the payload

1:52:57and create a new project with the all

1:52:59the same values it could simulate a

1:53:01cloning operation but but we don't know

1:53:05what clone means on the server side

1:53:07right if project clone can also mean

1:53:10that we have to take all the tasks that

1:53:13are inside that project and we have to

1:53:15also clone them right and maybe we have

1:53:19to send an email to the owner of the

1:53:21project that your project have cloned ET

1:53:23right the server maybe has to perform a

1:53:27lot of other operations when a project

1:53:29is cloned that is the reason we cannot

1:53:32simulate cloning operation using just a

1:53:34create project API right we have to

1:53:37explicitly create an

1:53:39endo uh with a custom action for cloning

1:53:43okay so let's go ahead and do that let's

1:53:46create a new one let's rename this clone

1:53:51project and this will be post call as

1:53:53you already know all the custom actions

1:53:55which do not fall under any crud

1:53:57operations are categorized under post

1:54:00because post is an open-ended method

1:54:02when it comes to rest APS specification

1:54:05so let's copy this one because the route

1:54:09will be similar we want to clone this

1:54:11particular project right let's paste

1:54:13this at the end we just write the name

1:54:15of the action this is how we designed a

1:54:18custom action based API we have the

1:54:21servers address

1:54:23we have the resource in the plural form

1:54:26we have the particular resource that we

1:54:28want to perform the action on and at

1:54:30last the name of the action this is what

1:54:32the structure of the API looks like and

1:54:34it does not have any payload uh for this

1:54:36use case but maybe you can take payloads

1:54:39maybe you can take um some fields that

1:54:42the client wants to override for a clone

1:54:43operation okay now when we execute this

1:54:47we get a project not found and 404

1:54:49response because we already deleted this

1:54:51project so let's go ahead and pick up a

1:54:54new project and replace this ID and then

1:54:57we execute this and we got it 20 one

1:55:02response now as I said you cannot assume

1:55:05from the method that since this the post

1:55:08method it will be a 20 1 response or

1:55:13since it is a custom action it cannot

1:55:15return 2011 because depending on what

1:55:18happens on the server side the Response

1:55:20Code might change because during in

1:55:22cloning the server creates a new project

1:55:25that's why the server returned a

1:55:28response which says

1:55:292011 which means I created a new

1:55:32resource for you okay we got a 2011

1:55:34response and the newly created resource

1:55:37and the name is Project to clone and all

1:55:39the fields that are similar to the

1:55:43project 2 entry that we had next this is

1:55:46the custom action based API for projects

1:55:49endpoint and with that all end points of

1:55:53project resource are completed hopefully

1:55:55by now you are able to establish all the

1:55:58patterns that goes behind designing all

1:56:00these apis and if you were to design all

1:56:04the apis for task so you would follow

1:56:07the same kind of pattern right you'll

1:56:09have a list API you'll have a get single

1:56:11task API you'll have delete update and

1:56:13you'll have some kind of Uh custom

1:56:15action right the patterns are same does

1:56:17not matter how many resources do you

1:56:20have the patterns still remain the same

1:56:23with these patterns you can go out and

1:56:26design as many apis as you want right

1:56:28the basics are the same the foundation

1:56:30is still the same now with that out of

1:56:33the way there are a couple of things

1:56:35that you have to keep in mind while you

1:56:37are creating your apas to provide a good

1:56:41experience to whoever is integrating

1:56:43your apas and whoever is maintaining

1:56:45your apas always try to provide an

1:56:48interactive documentation for your apas

1:56:51uh for for example start integrating

1:56:54Swagger tools like Swagger API which

1:56:56provide uh an interactive playground for

1:57:00trying out your apas right start

1:57:03planning that from your initial planning

1:57:05so that even so that you can use it to

1:57:08test your apas and whoever is

1:57:10integrating your apas they can use it as

1:57:12a form of documentation and as a form of

1:57:14testing right that's the first thing

1:57:17this is very important and one of the

1:57:20most important things that sets part as

1:57:22a backend engineer how consistently and

1:57:25how frequently you uh create maintain

1:57:29and update your open API or Swagger

1:57:32documentation second thing is make your

1:57:34apis intuitive and consistent which I've

1:57:38already mentioned all your routes all

1:57:42the patterns when it comes to your

1:57:43Dynamic parameters when you or custom

1:57:45actions or Json payloads all of them

1:57:48should follow a single pattern so if

1:57:51your following the global pattern the

1:57:54global standards of rest API then that's

1:57:56great right but even if you're not

1:57:59following that for some reason for some

1:58:01random reason that I cannot understand

1:58:04even if you cannot follow it but follow

1:58:07something right and stick to it do not

1:58:11change your styling do not change your

1:58:13patterns of your API in different

1:58:15different end points across different

1:58:17different resources right that is a huge

1:58:21pain point for or whoever is trying to

1:58:23integrate your apis keep the behavior

1:58:26keep the data format keep the naming

1:58:28everything consistent and intuitive

1:58:30third provide CN defaults and by this I

1:58:33mean uh as we saw in the pag generation

1:58:36API right even if the client does not

1:58:38pass a default page the server sets the

1:58:41default page as one if the client does

1:58:43not pass a limit parameter the default

1:58:46limit is 10 or 20 if the client does not

1:58:50part pass a sort field the default field

1:58:54is created at if the sort order is not

1:58:57passed the default sort order is

1:58:58descending similarly for post calls

1:59:01let's say there is a post operation in

1:59:04that case only require the amount of

1:59:07information that you absolutely need to

1:59:10create that entity otherwise provide

1:59:12some same defaults so even if it's a uh

1:59:16post call there are some fields for

1:59:18example in our earlier create

1:59:20organization API there is a field for

1:59:23status if you see here the organization

1:59:26has a field for status which can have

1:59:28active or archived but judging from the

1:59:32business logic judging from common sense

1:59:35right you can assume that when an

1:59:38organization is created by default it

1:59:41should be in active state right so from

1:59:43the client if the client does not pass

1:59:46the status field the server should by

1:59:49default set the status as active because

1:59:52it is a same default that part you can

1:59:55assume and it is a safe assumption so

1:59:58for feels like status you can take some

2:00:03status entry which makes most sense for

2:00:06your use case and provide that as a same

2:00:09default so that for creating an

2:00:11organization even if the client just

2:00:13passes name and a description and since

2:00:16the description is optional here even if

2:00:18the client just passes a name this

2:00:21organization is is successfully created

2:00:23with status active because on the server

2:00:25side you have provided same defaults

2:00:27that's what we mean by same defaults

2:00:30both in get a calls in post a calls

2:00:33similarly always avoid abbreviations uh

2:00:36like DEC for description etc etc right

2:00:41because the amount of information you

2:00:43have while creating apis while creating

2:00:45the interface for your apas is not the

2:00:48same amount of information that the

2:00:50people will have who are integrating

2:00:51your apis right so you cannot assume

2:00:54that if you provided some kind of

2:00:56abbreviation or some kind of short form

2:01:00of a field the people will be able to

2:01:04understand that and will be able to

2:01:05provide a appropriate entry for that

2:01:09field and that is the reason keep your

2:01:12peels whether it is payloads or whether

2:01:14it is query parameters keep them

2:01:17intuitive keep them readable and do not

2:01:21use use abbreviations and stuff right

2:01:24now these are just a couple of things

2:01:26that you have to keep in mind while

2:01:27designing your API interfaces and that

2:01:30is pretty much all that I have about API

2:01:33designing uh hopefully it will help you

2:01:36uh make decisions make good decisions

2:01:39make decisions faster and stick to a

2:01:42particular standards so that it is

2:01:44easier for people who are maintaining

2:01:45your apis and it is easier for people

2:01:48who are integrating and consuming your

2:01:49apis in the future as a backend engineer

2:01:52that's your responsibility to provide

2:01:55delightful to provide intuitive apis and

2:01:59always remember that an API a rest API

2:02:02at least is designed in the initial form

2:02:05it is not coded or it is not programmed

2:02:08right away at the first at the first

2:02:11phase of the API creation it is

2:02:14designed you have to make a lot of

2:02:16decisions to design your apis you cannot

2:02:18right away jump into programming that is

2:02:21the reason if you start uh with an open

2:02:24API playground like Swagger or some kind

2:02:27of um API clients like insomnia or

2:02:30Postman to design the interface for your

2:02:32apis it will provide you more insights

2:02:35into how your clients or how the

2:02:38consumers of your apis are going to use

2:02:41it and that will make you think and that

2:02:43will make you make your apis in a much

2:02:46better way in a much more intuitive way

2:02:49and that is the reason before getting

2:02:51into

2:02:52the coding part the programming of the

2:02:54API part regardless of the programming

2:02:57language that you're using whether it is

2:02:58go whether it is notes or any other

2:03:00language you should dedicate a separate

2:03:03session a separate session for just

2:03:05designing your interface the designing

2:03:08the interface for your apis without