Understanding REST Conventions - ldco2016/microurb_web_framework GitHub Wiki

Use of the JSON-Server has had an impact on the design of the User class.

JSON-Server follows a lot of conventions for working with individual records, so in the future I can very easily swap out the JSON-Server for another implementation for example, Ruby on Rails or some Express server and as long these servers work with the correct convention, it will work with the User class just fine.

To get a better idea of how these conventions work, I wrote out some code to interact directly with the server, but first let's take a look at the diagram below.

So in the diagram above is what we call RESTful conventions. These are conventions for making network requests for some outside server and based upon the type of request or method of request and the path that we make the request to, its going to affect exactly what that backend server will do for us.

So these are the conventions that JSON-Server follows and with these conventions in mind, there will be no additional setup of the JSON-Server required.

So imagine working with a resource called /posts. So we have this backend server that manages our posts for us and if we want to retrieve all the different posts being served by that server we make a GET request to our server /posts. So when talking about RESTful conventions, we are only concerned with the path on the very end.

If we want a particular resource or post we make a GET request to /posts/:id. I think you get the idea.

Below I have some sample code:

import axios from 'axios';

axios.post('http://localhost:3000/users', {
  name: 'myname',
  age: 20
});

So at this point, JSON-Server has already created an endpoint to handle users because of this piece of code:

{
  "users": []
}

inside of the db.json file.

So in the axios code snippet, we have the url we are reaching out to and as a second argument we have an object that represents the properties that the user is supposed to have. This will send a request to the browser and the browser will make that request to the JSON-Server and the JSON-Server should create a new user with that name and age.

In my Chrome console above, I sorted by XHR request and I see the request appearing. We first see a request that is of method OPTIONS and thats there because I made a request to a URL endpoint with a different port on it, this is related to CORS or Cross-Origin Resource Sharing.

The second request is the actual POST request I made:

So we see the response I got back from the server, it has created a new record with an age of 20 and a name of myname. The user created was assigned an id of 1, so with JSON-Server anytime a new record is created it will automatically be assigned a unique id.

Now, with an editor that supports live reload, you can go back to db.json and see the new user stored there:

{
  "users": [
    {
      "name":"myname",
      "age": 20,
      "id": 1
    }
  ]
}

So now we can retrieve information about the user by using that id. If we continue to follow RESTful conventions as we are trying to retrieve this information, that means we need to make a GET request to /nameOfResource/:id like so:

axios.post('http://localhost:3000/users/1');

So over in my browser I see the network request that was made. They found the user with age of 20, with an id of 1 and name of myname.

The id property is super important. If a user class has an id there is a ramification of that, it means the user has been saved to the backend server.

A user with an id has a server side representation, otherwise the user is brand new and has never been saved to the server.

We also ensure the data property on all users has a potential to have an id, before modifying to do so this is what the interface looked like:

interface UserProps {
  name?: string;
  age?: number;
}

So this was updated to also have an id as well. This id is necessary to retrieve a user, save the user or whatever else.