Types of API functions in Node.js

Node.js, known for its asynchronous and event-driven architecture, is a popular choice for building scalable server-side applications. One of its primary uses is to create and manage APIs (Application Programming Interfaces). APIs allow different software systems to communicate and share data with each other. In Node.js, API functions can be categorized based on their nature, usage, and the type of data they handle. This article explores various types of API functions in Node.js, providing insights into their functionalities and use cases.

HTTP API Functions

GET

• Purpose: Retrieve data from the server.
• Usage: Fetch resources like HTML pages, JSON data, images, etc.
• Example Use Case: A client requests user data from a server, and the server responds with the user information in JSON format.

POST

• Purpose: Send data to the server to create a new resource.
• Usage: Submit form data, upload files, etc.
• Example Use Case: A client submits a registration form with user details, and the server creates a new user in the database.

PUT

• Purpose: Update existing resources on the server.
• Usage: Update a user profile, modify product details, etc.
• Example Use Case: A client sends updated user information, and the server updates the corresponding user record in the database.

DELETE

• Purpose: Remove resources from the server.
• Usage: Delete a user account, remove a blog post, etc.
• Example Use Case: A client sends a request to delete a user, and the server removes the user from the database.

PATCH

• Purpose: Partially update a resource on the server.
• Usage: Modify specific fields in a record.
• Example Use Case: A client updates only the email address of a user, and the server modifies the email field of the corresponding user record.

WebSocket API Functions

Connect

• Purpose: Establish a persistent connection between client and server.
• Usage: Initiate a WebSocket connection for real-time communication.
• Example Use Case: A client connects to a chat server to receive real-time messages.

Send

• Purpose: Send data over an established WebSocket connection.
• Usage: Transmit messages, updates, or commands.
• Example Use Case: A chat application sends a message from one user to another.

Receive

• Purpose: Listen for incoming data over a WebSocket connection.
• Usage: Handle real-time data received from the server or another client.
• Example Use Case: A client receives notifications about new chat messages.

File System API Functions

Read

• Purpose: Read data from a file.
• Usage: Access file content for processing or serving.
• Example Use Case: Read a configuration file to load application settings.

Write

• Purpose: Write data to a file.
• Usage: Create or modify files with data.
• Example Use Case: Save user-generated content to a file.

Delete

• Purpose: Remove files from the file system.
• Usage: Delete temporary files, logs, etc.
• Example Use Case: Clean up old log files to free up disk space.

Watch

• Purpose: Monitor files for changes.
• Usage: Track modifications to files for live updates.
• Example Use Case: A live-reload development server detects changes in source files and reloads the application.

Database API Functions

Query

• Purpose: Retrieve data from a database.
• Usage: Execute SQL or NoSQL queries to fetch data.
• Example Use Case: Retrieve all users from a database table.

Insert

• Purpose: Add new data to a database.
• Usage: Insert new records into tables or collections.
• Example Use Case: Save a new user registration into the database.

Update

• Purpose: Modify existing data in a database.
• Usage: Update records based on specific criteria.
• Example Use Case: Change a user's email address in the database.

Delete

• Purpose: Remove data from a database.
• Usage: Delete records based on conditions.
• Example Use Case: Remove a user's record when they delete their account.

Stream API Functions

Read Stream

• Purpose: Read data from a source as a continuous flow.
• Usage: Process large files or data in chunks.
• Example Use Case: Stream a video file to a client without loading the entire file into memory.

Write Stream

• Purpose: Write data to a destination as a continuous flow.
• Usage: Save large data outputs efficiently.
• Example Use Case: Write a large log file incrementally as events occur.

Pipe

• Purpose: Connect a readable stream to a writable stream.
• Usage: Transfer data from one stream to another.
• Example Use Case: Pipe data from a file read stream directly to an HTTP response for efficient file serving.

Error Handling API Functions

Catch

• Purpose: Capture errors that occur during API operations.
• Usage: Handle exceptions and send appropriate responses.
• Example Use Case: Catch a database error and send a 500 Internal Server Error response to the client.

Throw

• Purpose: Trigger an error intentionally.
• Usage: Signal exceptional conditions in the API flow.
• Example Use Case: Throw an error when user input validation fails.

Middleware Error Handling

• Purpose: Intercept errors during request processing.
• Usage: Create middleware functions to handle errors.
• Example Use Case: Middleware catches errors and sends a generic error response to the client.

Types of API functions in NodeJS

• Asynchronous, Non-blocking functions
• Synchronous, Blocking functions

Asynchronous, Non-blocking functions:

As the name suggests, these functions operate asynchronously. What it means is that when Node.js will make a request for data to the API, it will not get blocked till the data is received. Instead, it will continue to move to the next API after calling it, and a notification mechanism from a Node.js event will respond to the server for the previous API call. To put it in layman's terms, these functions allow working further while the request is being handled. Example: Emails, online forums

Synchronous, Blocking functions:

Contrary to asynchronous functions, synchronous functions act as blocking functions. What it means is that these functions will make the calling system wait for a response. Thus, when a system uses synchronous APIs, it expects to get immediate data when requests are made. These types of APIs are used where availability and connectivity are high and low latency is expected. To put it in layman's terms, the application will request and wait for a response until the value is returned. Example: Instant messaging, video meetings

Example: Suppose we have a JSON file named data.json which contains certain data as below:

{
    "name": "John",
    "age": 50,
    "gender": "male"
}

Now, we will use asynchronous and synchronous functions to read this data. Node.js has an in-built module named fs which stands for File System which can be used to interact with files in a modeled way. To use it, we need to require it as follows:

const fs = require('fs');

We have used the following two functions in our application:

• To read the file asynchronously, we have used readFile() method supported by the fs module.
• To read the file synchronously, we have used readFileSync() method supported by the fs module.

Example: Implementation to show synchronous and asynchronous example.

// index.js

// Requiring inbuilt module
const fs = require('fs');

// Asynchronous function
fs.readFile('data.json', 'utf8', function (err,data) {
  if (err) {
    return console.log(err);
  }
  console.log("Below is the Data from Asynchronous function call")
  console.log(data);
});

// Synchronous function
var data = fs.readFileSync('data.json','utf8');
console.log("Below is the Data from Synchronous function call")
console.log(data);

Step to Run Application: Run the application using the following command from the root directory of the project

node index.js

Output: We will see the following output on your terminal screen:

Below is the Data from Synchronous function call
{
    "name": "John",
    "age": 50,
    "gender": "male"
}
Below is the Data from Asynchronous function call
{
    "name": "John",
    "age": 50,
    "gender": "male"
}

When the above code is executed, it will produce the same output as asynchronous, and in the same time frame. The reason behind this is that when we are reading one or two files, the difference between both methods won't be significant. But when we are operating with a database and handling multiple requests, the difference will be quite clear as it will directly affect the performance.