Writing RESTful API for Web Development

Miguel Sy

January 14, 2021

What is an API?
  • Application Programming Interface
  • A software intermediary that allows two applications to communicate and interact
  • For our use case in web development, it allows different devices to communicate over a network (the internet)
  • Restaurant Analogy: Restaurant Menu and Waiter is the API


What is REST?
  • Representational State Transfer
  • A software architectural style that defines a set of constraints and characteristics
  • Relatively simpler when compared to other protocols
  • Requires DECOUPLING between the server and client
  • Client only needs to understand how to navigate information provided by the server (via knowledge of API endpoints)


Main Characteristics of a RESTful API in Web Development
  • Uses HTTP as its transport layer
  • All HTTP methods should follow standard use-case
  • Body of a request or response should represent a resource or a collection of resource
  • Supports the JSON format


Best Practices on Implementing RESTful APIs
  • API endpoints (URLs) are in lowercase and in the form of a noun that represents the resource it provides access to

<div class="mb-3 ml-4"> <img class="img-fluid" src="https://strapi-saperium.s3.ap-southeast-1.amazonaws.com/rest_image12_460274eb03.png"> </div>

  • Make Proper Use of URL Parameters, Queries, and Request Body

    • URL Parameter – Resource Identification
      • Example: /users/:userId
    • URL Query – Additional Options
      • Example: /users?page=1
    • Request Body – Contains Data for Modifying Resource
  • Resources that belong to a collection should be prefixed by the collection’s URL

    • Example: /users -> collection, /users/:userId/settings -> resource
  • Strictly follow HTTP Method Spec (CRUD)

    • Post – Create a Resource
      • Respond with Request Parameters
    • Get – Read a Resource
      • Respond with Resource
    • Put – Update a Resource (Full Update)
      • Respond with Request Parameters
    • Patch – Update a Resource (Partial Update)
      • Respond with Request Parameters
    • Delete – Delete a Resource
      • Respond with Request Parameters

    *Don't Update or Delete Using the HTTP POST Method

  • Follow Correct HTTP Status Codes on Server Response

    • 200 – OK
    • 400 – Bad Request
    • 401 – Unauthorized
    • 404 – Resource Not Found
    • 500 – Internal Server Error
    • 503 – Service Unavailable


Node.js Express RESTful API Exercise
  • Goal: Create a Simple User CRUD
    • Create a User (User ID, Username, Email, Password)
    • Get the Users Collection
    • Get the User
    • Update the User
    • Delete the User


Prerequisites (Follow these steps if you don’t have a current app yet)

1. Create a New Express App <div> <img class="img-fluid img-width-50" src="https://strapi-saperium.s3.ap-southeast-1.amazonaws.com/rest_image3_9f289cbae7.png"> </div>

2. NPM Install <div> <img class="img-fluid img-width-50" src="https://strapi-saperium.s3.ap-southeast-1.amazonaws.com/rest_image7_2420ea1c1d.png"> </div>

3.Install nodemon and shortid <div> <img class="img-fluid img-width-50" src="https://strapi-saperium.s3.ap-southeast-1.amazonaws.com/rest_image13_4bb68ed501.png"> <img class="img-fluid img-width-50" src="https://strapi-saperium.s3.ap-southeast-1.amazonaws.com/rest_image16_13570ff6a0.png"> </div>

4. Replace NPM Start with Nodemon and Run ‘npm start’ <div> <img class="img-fluid img-width-50" src="https://strapi-saperium.s3.ap-southeast-1.amazonaws.com/rest_image8_2840f2bd9c.png"> </div>


Exercise Steps (Put User as an Example)

1. Set Index Router for Home Route

<div> <img class="img-fluid img-width-50" src="https://strapi-saperium.s3.ap-southeast-1.amazonaws.com/rest_image14_f043d16a19.png"> </div>

2. Add a Route

<div> <img class="img-fluid img-width-50" src="https://strapi-saperium.s3.ap-southeast-1.amazonaws.com/rest_image9_0df853ac84.png"> </div>

3. Add a Controller

<div> <img class="img-fluid img-width-50" src="https://strapi-saperium.s3.ap-southeast-1.amazonaws.com/rest_image6_f704e3fd82.png"> </div>

4. Test API Route via Postman

  • Set HTTP Method and Request URL

<div> <img class="img-fluid img-width-50" src="https://strapi-saperium.s3.ap-southeast-1.amazonaws.com/rest_image11_74d096f455.png"> </div>

  • Set Request Headers

<div> <img class="img-fluid img-width-50" src="https://strapi-saperium.s3.ap-southeast-1.amazonaws.com/rest_image10_78af8e53b7.png"> </div>

  • Set Request Body

<div> <img class="img-fluid img-width-50" src="https://strapi-saperium.s3.ap-southeast-1.amazonaws.com/rest_image4_6e8061c5af.png"> </div>

  • Check Server Response

<div> <img class="img-fluid img-width-50" src="https://strapi-saperium.s3.ap-southeast-1.amazonaws.com/rest_image17_041a130335.png"> </div>

  • Verify Resource State

<div> <img class="img-fluid img-width-50" src="https://strapi-saperium.s3.ap-southeast-1.amazonaws.com/rest_image18_1e8bc24af9.png"> </div>