Node.js with Express for API Development

• This lecture covers Node.js with Express for API development.

Introduction to Express

• Express is described as a minimal and flexible Node.js web application framework.
• It offers a robust set of features for building single-page, multi-page, and hybrid web applications.
• Being "minimal" is one of Express's most appealing aspects.
• Express provides a very minimal framework, giving flexibility to add or replace different parts of its functionality as needed.
• It provides functionality to other web applications, acting as a web application framework.

Express Web Framework (Node.js/JavaScript)

• Express highlights key benefits in development environment installation and web development/deployment task execution.
• It offers mechanisms to:
• Write request handlers with different HTTP verbs at different URL paths (routes).
• Integrate with view rendering engines to generate responses by inserting data into templates.
• Set common web application settings like the port for connecting and the location of templates for rendering.
• Add request processing "middleware" at any point within the request handling pipeline.

Express's Unopinionated Nature

• Web frameworks are often referred to as "opinionated" or "unopinionated."
• Opinionated frameworks have strong opinions about the "right way" to handle tasks.
• These are less flexible for solving problems outside their main domain.
• These tend to offer fewer choices for components and approaches
• Unopinionated frameworks have far fewer restrictions on how components should be used.
• They make it easier for developers to use the suitable tools, but the components must be found independently.

Express Code Overview

• In traditional data-driven websites, web applications await HTTP requests from web browsers (or other clients).
• Upon receiving a request, the application determines the necessary action based on the URL pattern and data in POST/GET requests.
• Information may be read or written from a database to satisfy the request.
• The application returns a response, often dynamically creating an HTML page by inserting data into an HTML template.
• Express allows specification of functions for HTTP verbs and URL patterns ("Route"), and also setup of used template ("view") engine.
• Express middleware allows adding support for cookies, sessions, users, and handling POST/GET parameters.

Application Settings in Express

• Sub-apps do not inherit settings with default values, but apply their own.
• Sub-apps inherit settings with no default value.
• Sub-apps inherit the value of trust proxy despite it having a default value, for backward compatibility.
• Sub-apps do not inherit the value of view cache in production environments (when NODE_ENV is "production").

Importing and Creating Modules

• Modules are JavaScript libraries/files imported into other code using Node's require() function.
• Example:
• const express = require('express');
• const app = express();

Square.js Module Example

• To make objects available outside a module, they need to be exposed as additional properties on the exports object.
• square.js exports area() and perimeter() methods.
• Example:
• exports.area = function(width) { return width * width; };
• exports.perimeter = function (width) { return 4 * width; };
• A complete object can be exported in one assignment by assigning it to module.exports.
• module.exports = { area: function(width) { return width * width; }, perimeter: function(width) { return 4 * width; } };

Asynchronous APIs

• JavaScript code uses asynchronous APIs more frequently than synchronous.
• Asynchronous APIs start an operation and return immediately before completion is achieved.
• Once the operation finishes, the API uses some mechanism to perform additional operations.
• The order of execution might differ between synchronous and asynchronous logs.
• Example of logging to Javascript Console:
• console.log('First')
• console.log('Second')
• Example of asynchronous API code:
• setTimeout(function() { console.log('First'); }, 3000);
• console.log('Second');

Route Handlers

• An Express application object provides methods to define route handlers for HTTP verbs.
• Route handlers can be created for:
  • checkout(), copy(), delete(), get(), head(), lock(), merge(), mkactivity(), mkcol(), move(), msearch(), notify(), options(), patch(), post(), purge(), put(), report(), search(), subscribe(), trace(), unlock(), unsubscribe().
• A handler can be created to execute requests to /secret irrespective of the HTTP verb used.
• This is provided it’s supported by the http module.
• Code Example

app.all('/secret', function(req, res, next) {
  console.log('Accessing the secret section ...');
  next(); // pass control to the next handler
});

Grouping route handlers with Express Router

• Route handlers can be grouped for a specific part of the site with a common route-prefix.
• An example of how this might be useful where a site with a Wiki has all wiki-related routes in one file accessed with /wiki/ prefix.
• Achieved in Express using an express.Router object.

// wiki.js - Wiki route module
const express = require('express');
const router = express.Router();

// Home page route
router.get('/', function(req, res) {
  res.send('Wiki home page');
});

// About page route
router.get('/about', function(req, res) {
  res.send('About this wiki');
});

module.exports = router;

• In the main app file, the router module can then be added with require():

const wiki = require('./wiki.js');
app.use('/wiki', wiki);

• The two routes become accessible from /wiki/ and /wiki/about/.

Express Development Environment

• Express environment setup includes Node.js, NPM package manager, and optionally Express Application Generator.
• Node and NPM are installed together from prepared binary packages, installers, operating system package managers, or from source.
• Express is installed by NPM as a dependency of Express web applications along with other libraries.
• NPM installs template engines, database drivers, authentication middleware, and middleware to serve static files.
• NPM also used globally to install the Express Application Generator, which is for creating skeleton Express web apps with MVC pattern.
• Application generator is optional, as apps can be created with Express or to construct apps with architectural layout or dependencies.

Using NPM

• NPM is used to fetch JavaScript libraries for application development, testing, and/or production.
• NPM is also used to run tests and tools used in the development process.
• Dependencies are managed using a package.json file.
• This file lists all dependencies for a JavaScript "package".
• The package.json file includes:
  • Package's name
  • Version
  • Description
  • Initial file to execute
  • Production dependencies
  • Development dependencies
  • Node versions it can work with etc.

Adding Dependencies

• Steps to download a package using NPM, save it into the project dependencies, and then require it in a Node application:
  • Create a directory for the new application and navigate into it:
    • mkdir myapp
    • cd myapp
  • Use the npm init command to create a package.json file: npm init
  • Install Express and save it in the dependencies of your package.json file: npm install express
  • Use the Express library by calling the require() function in your index.js file.

const express = require('express')
const app = express()
const port = 3000

app.get('/', (req, res) => {
 res.send('Hello World!')
})

app.listen(port, () => {
 console.log(`Example app listening on port ${port}`)
})

• Start the server by calling node with the script in the command prompt: >node index.js
• Navigate to the URL http://127.0.0.1:3000/ in the browser.

Views and Layouts

npm install --save express3-handlebars

var app = express(); // set up handlebars view engine
var handlebars = require('express3-handlebars')
.create({ defaultLayout:'main' });
app.engine('handlebars', handlebars.engine);
app.set('view engine', 'handlebars');

Creating Views and Layouts

• Creating file called views/layouts/main.handlebars.
• The usual HTML structure with {{{body}}} is used.
• This expression will be replaced with the HTML for each view.
• An example set of routes:

app.get('/', function(req, res) {
  res.render('home');
});
app.get('/about', function(req, res) {
  res.render('about');
});

// 404 catch-all handler (middleware)
app.use(function(req, res, next){
  res.status(404);
  res.render('404');
});

// 500 error handler (middleware)
app.use(function(err, req, res, next){
  console.error(err.stack);
  res.status(500);
  res.render('500');
});

• The view engine returns a content type of text/html and a status code of 200 by default.
• The catchall handler, which provides the custom 404 page, and the 500 handler, the status code must be set explicitly.

Creating a Basic Website

• The Express Application Generator allows configuration of a number of popular view/templating engines.

• Things to consider when choosing a templating engine:

  • Time to productivity: If a team is experienced with a templating language, they'll be productive faster with that.
  • Popularity and activity: Review engine popularity and active community for support purposes.
  • Style: Some use markup to indicate inserted content ("ordinary" HTML), others construct content using a different syntax.
  • Performance/rendering time. Following features should be available:

• Layout inheritance: Define a base template and "inherit" parts of specific pages.

• Considered better than building a template or include required components from scratch each time.

• "Include" support: Build templates by including other templates.

• Concise variable and loop control syntax.

• Ability to filter variable values at template level (e.g. uppercase conversion or date formatting).

• Ability to generate output formats other than HTML (e.g., JSON or XML).

• Support for asynchronous operations and streaming.

• Client-side features to use a templating engine on the client-side.

Parts of a URL

• The parts of a URL include:
  • Protocol (http://, https://)
  • Hostname (localhost, www.bing.com, google.com)
  • Port (:3000)
  • Path (/about, /search, /)
  • Querystring (?test=1#history, ?q=grunt&first=9, #q=express)
  • Fragment (#history, #q=express)

HTTP Request Methods

• The HTTP protocol defines request methods clients use to communicate with a server.
• The most common methods are GET and POST.
• Typing a URL into a browser issues an HTTP GET request to the server.
• The important information passed to the server is the URL path and query string.
• These details are combined with the HTTP method to determine app response.
• Most website pages respond to GET requests.
• POST requests are reserved for sending information back to the server.

Node.js Express Back-End API Examples

• GET api/authors gets all Authors.
• GET api/authors/:id gets Authors by id.
• POST api/authors adds a new Author.
• PUT api/authors/:id updates an Author by id.
• DELETE api/authors/:id removes Author by id.
• DELETE api/authors removes all Authors.
• GET api/authors?title=[kw] finds Authors whose title contains 'kw'.

Request Headers

• The URL isn't the only information passed to the server upon a page visit.
• The browser sends "invisible" information that includes language preferences.
• Information about the "user agent" (browser, OS, hardware) and other data is also transmitted.
• All data is sent as a request header available through the request object's headers property.
• The Express route can display browser information.

app.get('/headers', function(req,res){
  res.set('Content-Type','text/plain');
  var s = '';
  for(var name in req.headers) s += name + ': ' + req.headers[name] + '\n';
  res.send(s);
});

Response Headers

• The server responds with information not rendered or displayed in the browser.
• Response headers typically include metadata and server information.
• Headers can indicate whether the response is compressed and the encoding type.
• Response headers often contain information about the server type and operating system details.

The Request Object

• Useful request object properties and methods:
  • req.params
  • req.param(name)
  • req.query
  • req.body
  • req.route
  • req.cookies/req.signedCookies
  • req.headers
  • req.accepts([types])
  • req.ip
  • req.path
  • req.host
  • req.xhr
  • req.protocol
  • req.secure
  • req.url/req.originalUrl
  • req.url
  • req.originalUrl
  • req.acceptedLanguages

The Response Object

• The response object is normally passed to a callback.
• It's common to name it res, resp, or response.
• Its life starts as an instance of http.ServerResponse, a core Node object.
• Response object methods:
  • res.status(code)
  • res.set(name, value)
  • res.cookie(name, value, [options])
  • res.clearCookie(name, [options])
  • res.redirect([status], url)
  • res.send(body)
  • res.send(status, body)
  • res.json(json)
  • res.json(status, json)
  • res.type(type)
  • res.format(object)
  • res.attachment([filename])
  • res.download(path, [filename], [callback])
  • res.sendFile(path, [options], [callback])
  • res.links(links)
  • res.locals
  • res.render(view, [locals], callback) res.locals

API (Application Programming Interface)

• An API is a set of protocols and definitions facilitating the interaction between different applications.
• It is a computational interface used to determine the interaction between various software intermediaries.
• APIs provide:
  • Automation
  • Easier setup
  • Flexible information delivery
  • Easier integration
• Three common API protocols:
  • SOAP
  • REST
  • GraphQL

SOAP (Simple Object Access Protocol)

• SOAP is a "simple object access protocol".
• SOAP’s purpose is neutrality, extensibility, independence, and verbosity.
• This protocol relies mainly on XML, which is strongly typed.
• Each operation is explicitly defined, with an XML-based request and response structure.
• Each input parameter is bound and defined for a type such as string, integer, or complex object.
• SOAP uses web protocols such as HTTP, which work on almost all OS.

REST (Representational State Transfer) API

• REST API is a style for distributed hypermedia systems.
• This architectural style also has its own limitations.
• Six main limitations about the REST API:
• There are separate user interface and data storage issues to improve the portability of the user interface across multiple platforms.
• It also increases scalability by simplifying server components.
• Each server for a client request contains all the information to facilitate request understanding.
• The session state will be fully stored on the client.
• The data in the request-response must be marked as cached or non-cached.
• A single interface simplifies the overall architecture of the system.
• Interface constraints include resource identification, hypermedia representation via application statistics mechanism, and self-descriptive messages.
• A multi-level system allows the architecture to consist of hierarchical levels with component behavior restrictions.
• Each component can see in the layer with which it interacts.
• The REST API can extend client functionality by downloading and executing code in the form of applets and scripts.

GraphQL

• GraphQL is a query language that provides clear and complete descriptions of data in an API.
• You can send GraphQL queries to the API to get exactly what is necessary.
• These queries always return predictable results.
• GraphQL-based apps are faster and more stable because they have control over the data they receive.
• Requests access resource properties and smoothly follow links between them.
• GraphQL queries can deliver all needed data in one query.
• APIs are organized by fields and types, not by endpoints.

API vs Web Service

• A web service is designed to facilitate communication between two devices or machines over a network.
• APIs act as interfaces to facilitate communication between applications so they interact efficiently
• All web services can be used as APIs, but not every API can be used as a web service.
• Web services cannot perform all operations possible with an API.
• APIs can use any communication style.
• Web services require a network connection, while APIs do not.
• APIs contain interfaces and classes, similar to a software application.
• APIs can help programmers establish communication between different software applications.

REST API Explained

• REST (Representational State Transfer) is a standard architecture for building and communicating with web services.
• Resources on the web are represented in text format (JSON, HTML, or XML).
• It is typically accessed with HTTP protocols that correspond to HTTP methods like GET, POST, or PUT
• Web APIs define what requests can be made to a component and their expected responses.
• This includes the method of making the requests as well e.g. using a GET Request to obtain an endpoint.

HTTP Methods and CRUD Tasks

• These HTTP methods commonly correspond to CRUD tasks:
  • POST
  • GET
  • PUT
  • DELETE

REST as CRUD

• HTTP command GET is for Read operations.
  • The URL /dogs is to List all dogs and /dogs/3 is Get dog details.
• HTTP command POST is for Create operations.
  • The URL /dogs is to Create new dog.
• HTTP command PUT is for Update operations.
  • The URL /dogs/3 is to Update detail/s.
• HTTP command DELETE is for Delete operations.
  • The URLs /dogs is to Delete all dogs and /dogs/3 is Delete this dog.

REST API Project Structure

• An example project structure includes:
  • node_modules
  • Routes
    • programmingLanguages.js
  • Services
    • db.js
    • programmingLanguages.js
  • .gitignore
  • config.js
  • helper.js
  • index.js
  • package-lock.json
  • package.json
  • README.md

Creating the App

• The applications can be created by naming the app file either app.js or index.js or any name.

var express = require("express");
var app = express();app.listen(3000,
() => {
console.log("Server running on port
3000");
});

Setting Request Handlers

• This will allow the server to receive requests, processes them, and returns a response.
• Routes will handle the requests and include:
  • GET request that gets data
  • POST request that sends data securely
  • PUT request that updates data
  • DELETE request that deletes data.
• In a Web API, a server receives a request through a URL endpoint and sends a response, which is often in JSON format.
• Sample Code:

app.get("/url", (req, res, next) => {
  res.json(["Tony","Lisa","Michael","Ginger","Food"
]);
});

Running the app

• The node app is run using the command: node app.js
• For data to be viewable , open a bowser with the address: http://localhost:3000/url

Examples of REST GET

• An example of requesting all data on dogs to http://dog-db.com/api/dogs:

[
    {
     id:1, 
     name:"Fido" 
    },
    { 
     id:2,
     name:"Rover" 
    },
    {
     id:3, 
     name:"Spot" 
    },
    {
     id:4,
     name:"Fluffy"
    }
]

• An example request for GET an individual dog, use http://dog-db.com/api/dogs/3:

{
    id:3,
    name:"Spot",
    dob:"2009-05-21",
    type:"spaniel",
    photo:"http://dog-db/images/..."
}

Expressing Relationships

{
    id:3,
    name:"Spot",
    dob:"2009-05-21",
    owner:{
         id:16,
         name:"Sam",
         url:"http://dog-db.com/api/owners/16"
    }
}

HTTP response codes

• 200 - OK
• 4xx - Bad request (client's fault)
• 5xx - Failed request (server's fault)
• 401 - Unauthorized request
• 404 - Resource not found
• 500 - Internal error (bug)
• 503 - Server overloaded