Skip to content

Instantly share code, notes, and snippets.

@chas-e

chas-e/restful-routing.md

Forked from jim-clark/restful-routing.md
Created August 24, 2021 15:27
Show Gist options
  • Save chas-e/59729fa69f4a30e70d2506865fe788bb to your computer and use it in GitHub Desktop.
Save chas-e/59729fa69f4a30e70d2506865fe788bb to your computer and use it in GitHub Desktop.
Download ZIP
Raw
restful-routing.md

Click to View Presentation

Intro to

Learning Objectives


  • Explain what REST is

  • Map a RESTful HTTP Request to CRUD operations

  • List the 5 RESTful Routes for a Data Resource

Roadmap


  • What is REST?

  • Anatomy of a RESTful HTTP Request

  • RESTful APIs

  • RESTful Routing in Web Apps

What is REST?

What is REST?


  • REST is a whacky acronym that stands for:
        REpresentational State Transfer

  • REST was conceived by computer scientist, Roy Fielding.

  • Roy was born in Laguna Beach and attended UC Irvine, where he finished his doctorate within the Software Research Group.

What is REST? (cont)


  • According to Roy, the meaning of Representational State Transfer is:

Representational State Transfer is intended to evoke an image of how a well-designed web application behaves: a network of web pages (a virtual state-machine), where the user progresses through an application by selecting links (state transitions), resulting in the next page (representing the next state of the application) being transferred to the user and rendered for their use.

If you dissect the above, it makes sense, but is very vague in describing the way REST is typically used...

What is REST? (cont)


  • Defined in 2000.

  • If asked in an interview, "What is REST", a decent answer would be REST is a style of Software Architecture for distributed computing

  • REST defines a convention on how developers should "design" a web application's routes.

What is REST? (cont)


  • In today's lesson, we'll look at two common scenarios of RESTful client/server interaction:

    • RESTful APIs

    • RESTful Routing in Web Apps

Anatomy of a RESTful HTTP Request

Anatomy of a RESTful HTTP Request


  • When we saw HTTP earlier, we saw that when a browser makes a request to a web server, the request is composed of the following:

    • The HTTP Method (aka HTTP Verb)
    • A URL identifying the resource requested
    • Optional HTTP Headers (including Cookies)
    • Optional body data (often referred to as the payload)

Anatomy of a RESTful HTTP Request (cont)


  • REST is all about how routes are defined and used.

  • Because REST is focused on how routes are designed, we can forget about headers & body when talking about REST.

  • That leaves us with only two key parts in a RESTful request that matter:
        The HTTP Method, and the URI (path)

Anatomy of a RESTful HTTP Request (cont)


  • When we type in a location in our browser's address bar and press [return], it will make a request using the GET HTTP method.

  • Since we can issue a GET request with our browser, let's make a GET request to an online RESTful API. Type this in the address bar:
    http://jsonplaceholder.typicode.com/users

  • FYI, developers often refer to URLs as endpoints.

Anatomy of a RESTful HTTP Request

The Resource


  • The '/users' part of http://jsonplaceholder.typicode.com/users represents the name of the resource - in this case users.

  • A resource is the data entity the request is interested in accessing or modifying on the server.

  • Resource names should be pluralized - just like the table it probably maps to in the database.

Anatomy of a RESTful HTTP Request

The Collection URI


  • Let's breakdown the RESTful URI we just used:
    http://jsonplaceholder.typicode.com/users

    • http://jsonplaceholder.typicode.com: The scheme and host segments.

    • /users: The resource segment.

  • In REST, this URI is referred to as the collection URI, and is used to read or add to the resource collection.

Anatomy of a RESTful HTTP Request

The Item URI

  • Now let's try this endpoint:
    http://jsonplaceholder.typicode.com/users/5

  • We have appended an extra segment to the URI that identifies a specific resource, in this case, the user with an id of 5.

  • This URI is referred to as the item URI, and is used to read, update, or delete a single existing resource.

  • Notice that although we are accessing a single entity, the resource name in the URI, users, remains unchanged. It should not changed to user.

REST Checkpoint Questions


Take a minute to review these questions before the picker does its thing:

  • In your own words, what is REST?

  • Another word for an HTTP Method is an HTTP _______.

  • A _______ sends a RESTful request, and a _______ responds to that request.

  • The server uses the request's _______ & _______ to determine what code will run.

RESTful APIs

RESTful APIs


  • Now that we know that every RESTful request consists of an HTTP Method and a URI Endpoint, it's time to look at a specific use case: RESTful APIs.

  • RESTful APIs allow client software to Read, Create, Update and/or Delete data resources on a server.

  • The above might be referred to as performing CRUD data operations.

RESTful APIs (cont)


  • A RESTful Request (HTTP Method + URI) made from a client, is also known as REST Method Call.

  • This is an interesting way of thinking about it because sending a RESTful request is like calling a function that lives on a server somewhere...

RESTful APIs (cont)


On the server side, the server:

  1. Receives the request from the client.

  2. The routing system matches the HTTP Method and URI to the appropriate code to run (method).

  3. The code performs the actual CRUD operation.

  4. Finally, a response is sent to the client consisting of a HTTP Status Code and the appropriate resource (usually as JSON).

    Here's a link to valid HTTP Status Codes, with those used in REST identified.

RESTful APIs (cont)

  • As a reminder, there are only two URI patterns necessary to retrieve or modify a particular resource.
    The ________ URI and the ________ URI.

  • But if there are only two URIs, how does the server know which CRUD operation we want to perform?
    That's where the HTTP Method comes in!

  • Indeed, the same URI performs a different action when used with different HTTP Methods!

  • Up to this point, we've only seen the GET method, now let's checkout the rest!

REST Method & CRUD Mapping

  • Here are the RESTful routes for a resource named posts:

  • The :id in the URI is called a URL parameter - it serves the same role for HTTP requests as parameters do in functions.

RESTful APIs

REST Method & CRUD Mapping


Committing the REST methods & CRUD Mapping to memory is pretty much necessary, so let's get started...

RESTful APIs

RESTFUL API / CRUD Mapping


  • Quick Review
    Again, what are the two URI patterns,
    collection & item, used for?

  • Cool, let's move on.

RESTful APIs

RESTFUL API / CRUD Mapping

  • This would be a good time to mention that you will come across "longer" URIs with extra segment(s) between the host and resource segments. For example:
    https://www.toysrus.com/api/v2/toys

  • These extra segments are called namespacing and don't change anything in regards to REST. When designing your URIs, it's fine to just refer to the resource segment, for example:
    /toys   and   /toys/:id

RESTful APIs

RESTFUL API / CRUD Mapping


  • GET sounds just like what it does: it gets, which you can easily associate with the Read in CRUD.

  • GET is the only HTTP Method used with both URI patterns:

    • GET /todos   returns a JSON array of todo objects.
    • GET /todos/:id   returns a single JSON todo object.

  • Slam dunk!

RESTful APIs

RESTFUL API / CRUD Mapping


  • We all love slam dunks, so here's another...

  • The DELETE method - you got it, maps to Delete in CRUD.

  • Although we could write an API to accept DELETE with the collection URI, doing so would mean that you want to wipe out the entire resource collection, which would be rare.

  • So, when designing your RESTful APIs in WDI, use the DELETE method with just the item URI, i.e.,  DELETE /frogs/249

RESTful APIs

RESTFUL API / CRUD Mapping


  • Hey, that's 3 of the 5 RESTful routes, but the last 2 require a little more effort to memorize :)

  • We need to map a HTTP method to Create - POST is our answer.

  • POST is the HTTP method HTML forms use by default, so just remember that on web pages, we POST new data to the server.

  • If POST creates a resource that doesn't exist yet, guess which URI path we must POST to?

RESTful APIs

RESTFUL API / CRUD Mapping


  • The last two, PUT and PATCH, are very similar, so similar in fact that most APIs only implement PUT.

  • We've already mapped to CRUD's Read, Delete and Create, so if you reasoned that PUT and PATCH maps to CRUD's Update, you'd be correct!

  • I bet you can guess which URI pattern to pair with - what is it?

  • So, what's the difference between PUT and PATCH?...

RESTful APIs

RESTFUL API / CRUD Mapping


The difference between PUT and PATCH is subtle:

  • PUT is intended to replace the entire resource with the data sent in the data payload; and...

  • PATCH is intended to update just the properties included in the data payload.

  • But we, like most APIs will just combine them and associate them with update.

RESTful API Questions


  • What does a RESTful resource represent?

  • What is CRUD?

  • Name the five HTTP methods used in REST

  • The RESTful request, GET /tacos, does what?

  • The RESTful request, POST /tacos, does what?

  • What is wrong with this request, PUT /tacos?

RESTful API Practice Exercise

  • Create a file named rest_api.md.

  • Create a heading, "RESTful API to CRUD Mapping".

  • Create a table with the following headings:

  • Design a RESTful API for a resource: accounts.

  • Include all five RESTful Routes (HTTP Method + URI pairs).

Resources


Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment