‫Hey, welcome back.
‫Now let's talk about another style of APIs
‫which is called REST API.
‫We're first going to get familiar
‫with the general concepts and benefits of REST API.
‫And later, we'll learn how to define
‫a REST API step by step.
‫So what is a REST API?
‫REST is a relatively new style
‫that originated from a dissertation
‫published by Roy Fielding in the year 2000.
‫REST, which stands for Representational State Transfer,
‫is a set of architectural constraints and best practices
‫for defining APIs for the web.
‫It's important to note
‫that it is not a standard or a protocol,
‫but just an architectural style for designing APIs
‫that are easy for our clients to use and understand.
‫And it makes it easy for us to build a system
‫with quality attributes such as scalability,
‫high availability, and performance.
‫An API that obeys the REST architectural constraints
‫is commonly referred to as a RESTful API.
‫It's easy to understand the REST API
‫when we compare it to the RPC API style
‫that we learned in the previous lecture.
‫The RPC API style revolves around methods
‫that are exposed to the client
‫and are organized in an interface or a set of interfaces.
‫In other words,
‫our system is obstructed away from the client
‫through a set of methods that the client can call.
‫And if we want to expand our API
‫and allow the user to perform more operations on our system,
‫we would do that by adding more methods to the API.
‫In contrast, the REST API style
‫takes a more resource-oriented approach,
‫so the main abstraction to the user is a named resource
‫and not a method.
‫Those resources encapsulate different entities
‫in our system.
‫Also in contrast to the RPC API style,
‫REST API allows the user to manipulate those resources
‫only through a small number of methods.
‫In a REST API,
‫a client requests one of those named resources
‫and our system responds with a representation
‫of the current state of that resource to the client
‫where that representation can be used.
‫The protocol that is commonly used
‫to request those resources is HTTP.
‫It's important to note that our system
‫sends back only the representation of the resource state
‫and the resource itself can be implemented
‫in a completely different way
‫that is transparent to the client.
‫Let's clarify the statement with an example.
‫Let's say we're running an online news magazine
‫and the resource that we provide to the clients
‫is the homepage.
‫So when a client requests
‫the representation of that resource state,
‫they will get a webpage with a title
‫and a bunch of articles and pictures.
‫However, this is just the representation
‫of the current state of the homepage resource.
‫And in reality, our system can implement that resource
‫using many entities spread out
‫through multiple database tables, files,
‫or even external services.
‫This is what we mean by the resource being an abstraction
‫whose representation can be requested on demand
‫by calling our REST API.
‫Another big difference from the general RPC world
‫is the dynamic nature of the REST API.
‫In the RPC world, the only actions that the client can take
‫regardless of its state are statically defined
‫ahead of time in the interface description language.
‫However, in a RESTful API,
‫this interface is a lot more dynamic through a concept
‫called Hypermedia as the Engine of the Application State.
‫The way this is achieved is by accompanying
‫a state representation response to the client
‫with hypermedia links,
‫so the client can follow those links
‫and progress its internal state.
‫For example, if we have a chat or email system,
‫a client may send us a request for their current messages.
‫In response, we can send the client application
‫not only the object that represents all the information
‫about their messages,
‫but also an additional object that describes the resources
‫that the client application can use
‫to either get additional information
‫or take specific actions.
‫Now let's talk about how RESTful APIs
‫help us achieve high performance, scalability,
‫and high availability quality attributes.
‫One important requirement of a system
‫that provides RESTful API is that the server is stateless
‫and does not maintain any session information
‫about a client.
‫Instead, each message should be served
‫by the server in isolation
‫without any information about previous requests.
‫This requirement helps us achieve
‫high scalability and availability and let's see why.
‫If the server does not maintain any session information,
‫we can easily run a group of servers
‫and spread the load of the requests from the client
‫among a large number of machines,
‫completely transparently to the client.
‫So the client may send one request to one machine
‫and another request to a different machine
‫and he won't even notice.
‫Now, the second important requirement is cacheability.
‫That means the server has to either explicitly or implicitly
‫define each response as either cacheable or non-cacheable.
‫This allows the client to eliminate the potential roundtrip
‫to the server and back
‫if the response to a particular request
‫is already cached somewhere closer to the client.
‫As a side benefit to us,
‫it will also reduce the load on our system.
‫Now let's talk about the resources
‫and discuss what those resources can be,
‫how they should be named and organized.
‫In a RESTful API,
‫each resource is named and addressed using a URI.
‫The resources are organized in a hierarchy
‫where each resource is either a simple resource
‫or a collection resource.
‫The hierarchy is represented using forward slashes.
‫Now, a simple resource has a state,
‫and optionally, it can contain one or more sub-resources,
‫and a collection resource is a special resource
‫that contains a list of resources of the same type.
‫For example, if we have a movie streaming service,
‫we can have a collection resource called movies
‫and each sub-resource in that collection
‫is of the type of movie.
‫However, additionally, each movie,
‫which is a simple resource,
‫can have a collection sub-resource of its directors
‫and another collection sub-resource
‫that represents its actors.
‫Additionally, each actor, which is also a simple resource,
‫can have a profile picture sub-resource
‫and a contact information sub-resource.
‫Now, the representation of each resource state
‫can be expressed in a variety of ways.
‫It can be an image, a link to a movie stream, an object,
‫an HTML page, some binary blob, or even an executable code
‫like JavaScript that can be executed in the browser.
‫Now let's talk about some of the best practices
‫for naming our resources.
‫The first best practice is naming our resources
‫using nouns only.
‫Naming our resources using nouns makes a clear distinction
‫between the actions that we're going to take
‫on those resources for which we're going to use verbs.
‫The second best practice is making a distinction
‫between collection resources and simple resources.
‫The way we make that distinction
‫is by using plural names for collections
‫and singular names for simple resources.
‫If we look at the previous example,
‫we can see that the movies resource, directors resource,
‫and actors resource are all collections,
‫while the other resources are simple resources.
‫The next best practice is giving our resources
‫clear and meaningful names.
‫If we give our resources meaningful names,
‫our users will find it very easy to use our API
‫which will help prevent incorrect usages and mistakes.
‫Some overly generic collection names like elements,
‫entities, items, instances, values, or objects
‫should be avoided because they can really mean anything
‫and heavily depend on the context.
‫And the final best practice is the resource identifiers
‫should be unique and URL friendly
‫so they can be easily and safely used on the web.
‫Now let's switch gears and talk about the methods
‫and operations that we can perform on REST API resources.
‫As we mentioned earlier, unlike in RPCs,
‫the REST API limits the number of methods
‫we can perform on each resource
‫to just a few predefined operations.
‫Those operations are creating a new resource,
‫updating an existing resource,
‫deleting an existing resource,
‫and getting the current state of a resource.
‫As a side note, when the resource is a collection resource,
‫getting its state usually means
‫getting the list of its sub-resources.
‫Now because RESTful APIs are commonly implemented using HTTP
‫which already has several standard methods,
‫the REST operations are mapped to HTTP methods as follows.
‫When we want to create a new resource,
‫we use the POST HTTP method.
‫When we want update an existing resource,
‫we use the PUT method.
‫When we want to delete an existing resource,
‫we use the DELETE method.
‫And finally, when we want to get the state of a resource
‫or list of the sub-resources of a collection,
‫we use the GET method.
‫Now, in some situations,
‫we may want to define additional custom methods,
‫but those situations are uncommon.
‫The HTTP semantics give us a few guarantees
‫about those methods.
‫For example, the GET method is considered to be safe,
‫meaning that applying it to a resource
‫would not change its state in any way.
‫Additionally, the GET, PUT, and DELETE methods
‫are idempotent, which,
‫as we remember from the previous lecture,
‫means that applying those operations multiple times
‫would result in the same state change as applying them once.
‫Also, GET requests are usually considered
‫cacheable by default,
‫while responses to POST requests can be made cacheable
‫by setting the appropriate a HTTP headers
‫sent as part of the response to the client.
‫This feature of the HTTP protocol allows us to conform
‫to the cacheability requirements of a REST API.
‫Finally, when the client needs to send
‫additional information to our system
‫as part of a POST or PUT command, for example,
‫we would use the JSON format,
‫although other formats like XML are also acceptable.
‫Now let's learn how to create a REST API step by step
‫by going through a real life example.
‫The system we're going to design
‫is going to be a movie streaming service
‫which we already saw a few examples of.
‫The first step of creating a REST API
‫is identifying the different entities in our system,
‫which will serve as the resources of our API.
‫To keep things simple,
‫let's assume that the only entities we have
‫in our movie streaming service are users,
‫movies, reviews, and actors.
‫Now, the second step would be
‫mapping those entities to URIs.
‫In this step, we define the resources
‫based on the entities we identified in the previous step
‫and also organize their resources in a hierarchy
‫based on their relationships.
‫For example, users and movies are two collection resources
‫that are entirely independent of each other.
‫The actors collection is also independent
‫because the same actors can appear in different movies.
‫However, the reviews are going to be a sub-resource
‫of the movies collection because each review is associated
‫with only a single movie.
‫At this point, we have all the resources defined,
‫so the next step is choosing the representation
‫of each type of resource.
‫Theoretically, we can represent each resource
‫in any way we like,
‫but the most common way to represent a resource
‫is using the JSON format.
‫For example, the movies collection resource
‫would be represented as an object
‫containing an array of movie names mapped to movie IDs.
‫This representation makes it easy
‫to search for a particular movie by name
‫and also get its identifier.
‫Using this identifier,
‫a client application can append it to the movies URI
‫and get a particular movie resource.
‫A single movie resource object
‫would contain all the information
‫about that particular movie,
‫including links that can help us play the movie
‫on the user's device,
‫as well as performing additional operations
‫such as getting the movie reviews and the movie's actors.
‫Those links allow our API to be driven
‫by the hypermedia as the engine of the application state.
‫The last step in creating a REST API
‫is assigning HTTP methods to actions
‫that we can perform on our resources.
‫For example, we can define the POST operation
‫on the user's collection resource
‫to register a new user in our movie streaming service.
‫The response to that request
‫would contain a newly created user ID.
‫Then we can define a GET method on a particular user
‫to get all the information stored for that particular user
‫including the list of favorite movies
‫or the ones that they want to watch in the future.
‫Similarly, we can define a PUT operation
‫on a particular user resource
‫to update the current user's profile,
‫or if we want to make any changes
‫to the user's information or preferences.
‫And finally, we can define a DELETE operation
‫on a particular user to remove that user
‫entirely from our system.
‫Now to finish designing our API,
‫we need to repeat this process
‫on all the resources we have in our system.
‫In this lecture, we'll learn about a new style of API,
‫which is called Representational State Transfer
‫or REST in short.
‫We compared the REST API to the general RPC approach
‫by emphasizing that the REST API is more resource-oriented
‫and limits the number of operations
‫we can perform on those named resources
‫to just a few methods.
‫We later talked about how the REST API requirements
‫allow us to provide high performance,
‫high availability, and scalability.
‫After that, we talked in detail
‫about what those resources are, how they're organized,
‫and what operations we can perform on those resources.
‫And finally, we concluded by providing
‫a step-by-step process on defining the REST API
‫by following a practical real life example.
‫I hope you're having fun
‫and I will see you soon in the next lecture.