But once you move beyond basic apps, CRUD starts to fall apart.

Real-world systems don’t just “update” or “delete” things. In a loan application system, for example, borrowers “submit” applications, loan officers “approve” or “reject” them, and applications are eventually “archived”. These aren’t generic CRUD operations—they’re domain-specific actions that carry meaning.

And that’s the problem: CRUD hides the meaning of our systems behind vague verbs. REST APIs inherit the same issue, mapping HTTP verbs onto CRUD but still failing to express real workflows clearly.

In this article, we’ll explore:

• Why CRUD works fine for simple apps but becomes an anti-pattern at scale

• How concepts like upsert, archive, and bulk operations reveal its cracks

• Why REST doesn’t solve these issues

• How to design APIs around domain actions and workflows instead.

By the end, you’ll see CRUD for what it really is—a teaching tool, not a design philosophy.

Table of Contents

• What is CRUD?

• Stretching CRUD: Upsert, Archive, Bulk

• Breaking CRUD: Domain Actions

• Breaking CRUD: Domain Authorization

• CRUD Alternative: Align to Workflows

• Conclusion

What is CRUD?

Create, Read, Update, Delete—these are the four basic operations we perform on data in a database.

• Create – adds a new record.

• Read – fetches an existing record (or list of records).

• Update – changes one or more fields in a record.

• Delete – removes a record.

For example, in a typical Node.js + Express app managing users:

// Create a user
app.post('/users', createUser);

// Read a user
app.get('/users/:id', getUser);

// Update a user
app.put('/users/:id', updateUser);

// Delete a user
app.delete('/users/:id', deleteUser);

This maps directly to the underlying SQL:

INSERT INTO users (...);
SELECT * FROM users WHERE id = ...;
UPDATE users SET ... WHERE id = ...;
DELETE FROM users WHERE id = ...;

And that’s CRUD in its purest form—four operations that can describe almost any database interaction.

Stretching CRUD: Upsert, Archive, Bulk

Developers quickly realize CRUD isn’t enough, so they invent extensions:

• Upsert: a mix of “update” and “insert.” If the record exists, update it; if not, create it.

• Archive: instead of deleting a record, we “soft delete” or mark it as inactive so the history stays intact.

• Bulk operations: run create, update, or delete on many records at once for efficiency.

These solve real problems, but they stretch CRUD’s simple model. We now need to distinguish between single and bulk resource actions. And we also need to factor in the technical concerns of upsertions and soft deletions.

Breaking CRUD: Domain Actions

The technical domain itself stretches CRUD substantially, but business domain concerns break it entirely. Take a loan application system:

• A borrower doesn’t “create” and “update” an application—they start, submit, or withdraw it.

• A loan officer doesn’t “update” an application—they review, approve, or reject it.

• Applications don’t get “deleted”—they’re usually archived so there’s a record for compliance.

If we try to model these as plain CRUD, the meaning gets lost:

PATCH /applications/123 { "status": "approved" }

Technically, it works. But what does “update” really mean here? Was the application submitted, rejected, or archived? You can’t tell from the API call.

The core problem: CRUD hides intent behind generic, technical language. Real business processes are expressed as domain-specific actions, not generic updates or deletes.

Breaking CRUD: Domain Authorization

CRUD not only obscures intent—it also creates authorization gaps. Using the same loan application example:

• Only loan officers should approve applications.

• Borrowers should only edit their own information or withdraw their applications.

If “approve” is just modeled as a generic update, the system can’t distinguish between roles without additional checks. A naive authorization rule like “can this user update?” suddenly lets borrowers perform actions reserved for officers.

This mismatch between technical verbs and business rules can lead to:

• Security issues—unauthorized actions performed by the wrong user.

• Audit problems—it’s unclear who did what, and when.

• Workflow confusion—state transitions get lost in generic updates.

The solution: treat each domain action as its own API call with explicit authorization rules:

POST /applications/123/approve   # Only accessible to loan officers
POST /applications/123/withdraw  # Only accessible to the borrower

By modeling actions instead of CRUD operations, intent and permissions are clear, reducing both bugs and security risks.

CRUD Alternative: Align to Workflows

Real-world applications follow workflows—sequences of states that a resource moves through. Take our loan application example:

Here’s what the corresponding API endpoints might look like:

# Borrower actions
POST /applications/123/submit       # Draft → Submitted
POST /applications/123/withdraw     # Draft/Submitted → Closed

# Loan officer actions
POST /applications/123/approve      # Submitted → Approved
POST /applications/123/reject       # Submitted → Rejected

# System/Admin actions
POST /applications/123/close        # Approved/Rejected → Closed

# Side effect: spawning a Loan (after Approved)
POST /loans
{
  "applicationId": "123",
  "amount": 50000,
  "borrowerId": "456",
  "terms": { ... }
}

At this point, our API calls are almost entirely outside the CRUD pattern—the only one that resembles a CRUD action is the spawning of a loan, which looks like a “create”. Behind the scenes, we’ll still use INSERT, SELECT, and UPDATE statements in SQL, but at the API level we’re aligning to the actual business workflow. Because of it, we’re able to easily support the following:

1. Actions reflect business intent — each API call maps to a real-world task like submit, approve, or withdraw.

2. Built-in authorization — endpoints clearly separate borrower, loan officer, and admin responsibilities.

3. Auditability and workflow enforcement — state transitions are explicit and invalid transitions are prevented.

4. Controlled side effects — spawning loans, notifications, and downstream processes are handled deliberately.

Conclusion

By moving away from CRUD and modeling domain actions instead, our API aligns with real business workflows, clearly communicates intent, and enforces rules and authorization naturally. State transitions, side effects, and auditing become explicit, reducing errors and security risks. While CRUD still powers the underlying database operations, thinking in terms of actions and workflows ensures that the system behaves the way the business expects.

In this tutorial, you’ll learn how to build a CRUD application using React and Convex. We’ll cover these operations by building a project called Book Collections. In this project, users will be able to add books and update their status once they complete a book.

Table of Contents

• What is Convex?

• How to Set Up Your Project

• How to Create the Schema

• How to Create the UI

• How to Create CRUD Functions

• Styling

• Summary

What is Convex?

Convex is the Baas Platform that simplifies backend development. Convex comes with a real-time database, and you do not need to worry about writing server-side logic separately because it provides methods for querying and mutating the database.

Prerequisites

In order to follow this tutorial, you must know the fundamentals of React. I will be using TypeScript in this project, but it is optional, so you can also follow along with JavaScript.

How to Set Up Your Project

Create a separate folder for the project and name it as you wish – I will name mine Books. We’ll set up Convex and React in that folder.

You can create a React app using this command:

npm create vite@latest my-app -- --template react-ts

If you want to work with JavaScript, then remove the ts at the end. That is:

npm create vite@latest my-app -- --template react

How to Setup Convex

We have to install Convex in the same folder. You can do that using this command:

npm install convex

Next, run npx convex dev. If you’re doing this for the first time, it should ask you for authentication. Otherwise, it should ask for the project name.

You can visit the Convex dashboard to see the project that you have created.

Now that we have the Convex and React App set up, we need to connect the Convex backend to the React app.

In the src/main.tsx, wrap your App component with the ConvexReactClient:

import { createRoot } from "react-dom/client";
import App from "./App.tsx";
import { ConvexProvider, ConvexReactClient } from "convex/react";
import "./index.css"

const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);

createRoot(document.getElementById("root")!).render(
  <ConvexProvider client={convex}>
    <App />
  </ConvexProvider>
);

When you set up Convex, a .env.local was created. You can see your backend URL in that file.

In the line below, we instantiated the React Convex Client with the URL.

const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string);

How to Create the Schema

In your main project directory, you should see the convex directory. We’ll handle the database queries and mutations here.

Create a schema.ts file in the convex folder:

import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  books: defineTable({
    title: v.string(),
    author: v.string(),
    isCompleted: v.boolean(),
  }),
});

You can define a Schema for your document with defineSchema and create a table with defineTable. Convex provides these functions for defining a schema and creating a table.

v is the type validator, it is used to provide types for each data we add to the table.

For this project, as it is a book collection application, the structure will have title, author, and isCompleted. You can add more fields.

Now that you have defined your schema, let’s set up the basic UI in React.

How to Create the UI

In the src folder, create a folder called component and a file Home.tsx. Here, you can define the UI.

import { useState } from "react";
import "../styles/home.css";

const Home = () => {
  const [title, setTitle] = useState("");
  const [author, setAuthor] = useState("");
  return (
    <div className="main-container">
      <h1>Book Collections</h1>
      <form onSubmit={handleSubmit}>
        <input
          type="text"
          name="title"
          value={title}
          onChange={(e) => setTitle(e.target.value)}
          placeholder="book title"
        />
        <br />
        <input
          type="text"
          name="author"
          value={author}
          onChange={(e) => setAuthor(e.target.value)}
          placeholder="book author"
        />
        <br />
        <input type="submit" />
      </form>
      {books ? <Books books={books} /> : "Loading..."}
    </div>
  );
};

export default Home;

You can create your component as you wish. I added two input fields title, author, and submit button. This is the basic structure. Now we can create CRUD methods in the backend.

How to Create CRUD Functions

In the convex folder, you can create a separate queries.ts file for the CRUD functions.

Create Function

In convex/queries.ts:

You can define a function createBooks. You can use the mutation function from Convex to create, update, and delete data. Reading the data will come under query.

The mutation function expects these arguments:

• agrs: the data we need to store in the database.

• handler: handles the logic to store date in the database. The handler is an async function, and it has two arguments: ctx and args. Here, ctx is the context object that we’ll use to handle the database operations.

You’ll use the insert method to insert new data. The first parameter in the insert is the table name and the second is the data that needs to be inserted.

Lastly, you can return the data from the database.

Here’s the code:

import { mutation} from "./_generated/server";
import { v } from "convex/values";

export const createBooks = mutation({
  args: { title: v.string(), author: v.string() },
  handler: async (ctx, args) => {
    const newBookId = await ctx.db.insert("books", {
      title: args.title,
      author: args.author,
      isCompleted: false,
    });
    return newBookId;
  },
});

Read Function

In convex/queries.ts:

import { query } from "./_generated/server";
import { v } from "convex/values";

//read
export const getBooks = query({
  args: {},
  handler: async (ctx) => {
    return await ctx.db.query("books").collect();
  },
});

In this read operation, we used the built-in query function from Convex. Here, args will be empty since we are not getting any data from the user. Similarly, the handler function is async and uses the ctx object to query the database and return the data.

Update Function

In convex/queries.ts:

Create a updateStatus function. We are only going to update the isCompleted status.

Here, you need to get the document ID and the status from the user. In the args, we’ll define id and the isCompleted, which will come from the user.

In the handler, we’ll use the patch method to update the data. The patch method expects two arguments: the first argument is the id of the document and the second is the updated data.

import { mutation } from "./_generated/server";
import { v } from "convex/values";

//update
export const updateStatus = mutation({
  args: { id: v.id("books"), isCompleted: v.boolean() },
  handler: async (ctx, args) => {
    const { id } = args;
    await ctx.db.patch(id, { isCompleted: args.isCompleted });
    return "updated"
  },
});

Delete Function

In convex/queries.ts:

Create a deleteBooks function and use the mutation function. We’ll need the ID of the document to be deleted. In the args, define an ID. In the handler, use the ctx object delete method, and pass the ID. This will delete the document.

import { mutation } from "./_generated/server";
import { v } from "convex/values";

//delete
export const deleteBooks = mutation({
  args: { id: v.id("books") },
  handler: async (ctx, args) => {
    await ctx.db.delete(args.id);
    return "deleted";
  },
});

As of now, you have completed the CRUD functions in the backend. Now we need to make it work in the UI. Let’s jump back to React.

Update the UI

You’ve already created some basic UI in the React app, along with some input fields. Let’s update it.

In src/component/Home.tsx:

import { useQuery, useMutation } from "convex/react";
import { api } from "../../convex/_generated/api";
import { Books } from "./Books";
import { useState } from "react";
import "../styles/home.css";

const Home = () => {
  const [title, setTitle] = useState("");
  const [author, setAuthor] = useState("");
  const books = useQuery(api.queries.getBooks);
  const createBooks = useMutation(api.queries.createBooks);

  const handleSubmit = (e: React.FormEvent<HTMLFormElement>): void => {
    e.preventDefault();
    createBooks({ title, author })
      .then(() => {
        console.log("created");
        setTitle("");
        setAuthor("");
      })
      .catch((err) => console.log(err));
  };
  return (
    <div className="main-container">
      <h1>Book Collections</h1>
      <form onSubmit={handleSubmit}>
        <input
          type="text"
          name="title"
          value={title}
          onChange={(e) => setTitle(e.target.value)}
          placeholder="book title"
        />
        <br />
        <input
          type="text"
          name="author"
          value={author}
          onChange={(e) => setAuthor(e.target.value)}
          placeholder="book author"
        />
        <br />
        <input type="submit" />
      </form>
      {books ? <Books books={books} /> : "Loading..."}
    </div>
  );
};

export default Home;

We can now use the backend API functions by using api from Convex. As you can see, we called two API functions: you can use useQuery if you’re going to read data and useMutation if you want to change data. Now in this file, we are doing, two operations that are create and read.

We got all the data by using this method:

 const books = useQuery(api.queries.getBooks);

The array of objects will be stored in the books variable.

We got the create function from the backend with this line of code:

const createBooks = useMutation(api.queries.createBooks);

How to Use the Create Function in the UI

Let’s use the create function in the UI.

Since input fields are in the form tag, we’ll use the onSubmit attribute to handle the form submission.

//In the Home.tsx

const handleSubmit = (e: React.FormEvent<HTMLFormElement>): void => {
    e.preventDefault();
    createBooks({ title, author })
      .then(() => {
        console.log("created");
        setTitle("");
        setAuthor("");
      })
      .catch((err) => console.log(err));
  };

When you click submit, it triggers the handleSubmit function.

We used the createBooks to pass the title and author from the state. The endpoint function is async, so we can use the handleSubmit as async or use .then. I used the .then method to handle the asynchronous data.

You can create a separate component to display the data fetched from the database. The returned data is in the Home.tsx, so we will pass the data to the Books.tsx component as props.

In Books.tsx:

import { useState } from "react";
import { book } from "../types/book.type";
import { useMutation } from "convex/react";
import { api } from "../../convex/_generated/api";
import { Id } from "../../convex/_generated/dataModel";
import "../styles/book.css";

export const Books = ({ books }: { books: book[] }) => {
  const [update, setUpdate] = useState(false);
  const [id, setId] = useState("");

  const deleteBooks = useMutation(api.queries.deleteBooks);
  const updateStatus = useMutation(api.queries.updateStatus);

  const handleClick = (id: string) => {
    setId(id);
    setUpdate(!update);
  };

  const handleDelete = (id: string) => {
    deleteBooks({ id: id as Id<"books"> })
      .then((mess) => console.log(mess))
      .catch((err) => console.log(err));
  };

  const handleUpdate = (e: React.FormEvent<HTMLFormElement>, id: string) => {
    e.preventDefault();
    const formdata = new FormData(e.currentTarget);
    const isCompleted: boolean =
      (formdata.get("completed") as string) === "true";
    updateStatus({ id: id as Id<"books">, isCompleted })
      .then((mess) => console.log(mess))
      .catch((err) => console.log(err));
    setUpdate(false);
  };

  return (
    <div>
      {books.map((data: book, index: number) => {
        return (
          <div
            key={data._id}
            className={`book-container ${data.isCompleted ? "completed" : "not-completed"}`}
          >
            <h3>Book no: {index + 1}</h3>
            <p>Book title: {data.title}</p>
            <p>Book Author: {data.author}</p>
            <p>
              Completed Status:{" "}
              {data.isCompleted ? "Completed" : "Not Completed"}
            </p>
            <button onClick={() => handleClick(data._id)}>Update</button>
            {id === data._id && update && (
              <>
                <form onSubmit={(e) => handleUpdate(e, data._id)}>
                  <select name="completed">
                    <option value="true">Completed</option>
                    <option value="false">Not Completed</option>
                  </select>
                  <input type="submit" />
                </form>
              </>
            )}
            <button onClick={() => handleDelete(data._id)}>delete</button>
          </div>
        );
      })}
    </div>
  );
};

In the Books.jsx component, you can display data from the database and handle the functionality for updating and deleting records.

Let’s walk through each of these features step by step.

How to Display the Data

You can get the data passed as a prop in the Home.tsx component. If you are using TypeScript, I have defined a type for the object that is returned from the query. You can ignore this if you are using JavaScript.

Create `books.types.ts:

export type book = {
    _id: string,
    title: string,
    author: string,
    isCompleted: boolean
}

You can use the map function to display the data.

import { useState } from "react";
import { book } from "../types/book.type";
import { useMutation } from "convex/react";
import { api } from "../../convex/_generated/api";
import { Id } from "../../convex/_generated/dataModel";
import "../styles/book.css";

export const Books = ({ books }: { books: book[] }) => {
  const [update, setUpdate] = useState(false);

  return (
    <div>
      {books.map((data: book, index: number) => {
        return (
          <div
            key={data._id}
            className={`book-container ${data.isCompleted ? "completed" : "not-completed"}`}
          >
            <h3>Book no: {index + 1}</h3>
            <p>Book title: {data.title}</p>
            <p>Book Author: {data.author}</p>
            <p>
              Completed Status:{" "}
              {data.isCompleted ? "Completed" : "Not Completed"}
            </p>
            <button onClick={() => handleClick(data._id)}>Update</button>
            {id === data._id && update && (
              <>
                <form onSubmit={(e) => handleUpdate(e, data._id)}>
                  <select name="completed">
                    <option value="true">Completed</option>
                    <option value="false">Not Completed</option>
                  </select>
                  <input type="submit" />
                </form>
              </>
            )}
            <button onClick={() => handleDelete(data._id)}>delete</button>
          </div>
        );
      })}
    </div>
  );
};

This is the basic structure. We displayed the title, author, and status, along with an update and delete button.

Now, let’s add the functionalities.

import { useState } from "react";
import { book } from "../types/book.type";
import { useMutation } from "convex/react";
import { api } from "../../convex/_generated/api";
import { Id } from "../../convex/_generated/dataModel";
import "../styles/book.css";

export const Books = ({ books }: { books: book[] }) => {
  const [update, setUpdate] = useState(false);
  const [id, setId] = useState("");

  const deleteBooks = useMutation(api.queries.deleteBooks);
  const updateStatus = useMutation(api.queries.updateStatus);

  const handleClick = (id: string) => {
    setId(id);
    setUpdate(!update);
  };

  const handleDelete = (id: string) => {
    deleteBooks({ id: id as Id<"books"> })
      .then((mess) => console.log(mess))
      .catch((err) => console.log(err));
  };

  const handleUpdate = (e: React.FormEvent<HTMLFormElement>, id: string) => {
    e.preventDefault();
    const formdata = new FormData(e.currentTarget);
    const isCompleted: boolean =
      (formdata.get("completed") as string) === "true";
    updateStatus({ id: id as Id<"books">, isCompleted })
      .then((mess) => console.log(mess))
      .catch((err) => console.log(err));
    setUpdate(false);
  };

  return (
    <div>
      {books.map((data: book, index: number) => {
        return (
          <div
            key={data._id}
            className={`book-container ${data.isCompleted ? "completed" : "not-completed"}`}
          >
            <h3>Book no: {index + 1}</h3>
            <p>Book title: {data.title}</p>
            <p>Book Author: {data.author}</p>
            <p>
              Completed Status:{" "}
              {data.isCompleted ? "Completed" : "Not Completed"}
            </p>
            <button onClick={() => handleClick(data._id)}>Update</button>
            {id === data._id && update && (
              <>
                <form onSubmit={(e) => handleUpdate(e, data._id)}>
                  <select name="completed">
                    <option value="true">Completed</option>
                    <option value="false">Not Completed</option>
                  </select>
                  <input type="submit" />
                </form>
              </>
            )}
            <button onClick={() => handleDelete(data._id)}>delete</button>
          </div>
        );
      })}
    </div>
  );
};

This is the entire component code. Let me explain what we did.

First, we need to toggle the update, so we defined the handleClick function, and passed a document ID to it.

//handleClick
 const handleClick = (id: string) => {
    setId(id);
    setUpdate(!update);
  };

In the handleClick you can update the ID state and toggle the update state so that it will toggle the update input when clicked, and on another click, it will close.

Next, we have handleUpdate. We need the document ID to update the data, so we passed the event object as well as the document ID. To get the input, we can use FormData.

const updateStatus = useMutation(api.queries.updateStatus);

const handleUpdate = (e: React.FormEvent<HTMLFormElement>, id: string) => {
    e.preventDefault();
    const formdata = new FormData(e.currentTarget);
    const isCompleted: boolean =
      (formdata.get("completed") as string) === "true";
    updateStatus({ id: id as Id<"books">, isCompleted })
      .then((mess) => console.log(mess))
      .catch((err) => console.log(err));
    setUpdate(false);
  };

We need to use the useMutation to get the updateStatus function. Pass the ID and the completed status to the function, and handle the asynchronous part using .then

For the delete function, the document ID is enough. Just like the previous one, call the delete function using the useMutation and pass the ID to it.

Then pass the document ID and handle the promise.

const deleteBooks = useMutation(api.queries.deleteBooks);

const handleDelete = (id: string) => {
    deleteBooks({ id: id as Id<"books"> })
      .then((mess) => console.log(mess))
      .catch((err) => console.log(err));
 };

Styling

Finally, what’s left is to add some styling. I added some basic styling. If the book has not been completed, it will be in red, and if the book has been completed, it will be in green.

Here’s the screenshot:

This is it guys!!

You can check my repository for the full code: convex-curd

Summary

In this article, we implemented the CRUD (Create, Read, Update, and Delete) operations by building a book collections app. We begin by setting up Convex and React, and writing CRUD logic.

This tutorial covered both the frontend and the backend, demonstrating how to build a serverless application.

You can find the full code here: convex-curd

If there are any mistakes or any doubt contact me on LinkedIn, Instagram.

Thank you for reading!

We'll also deploy the application on Azure App Service and make it production-ready by setting up features like autoscaling and multiple environments.

You'll learn how Neon Postgres can make your development and deployment processes easier along the way.

Here's what we'll cover:

• Setting up a Neon Postgres database and exploring its features
• Building a CRUD application using Spring Boot and deploying the application on Azure App Service
• Why Neon is a good fit for infrastructure that auto-scales
• Database branching in Neon Postgres and how it can ease the development workflow

Prerequisites

• Working knowledge of Java, Maven, and Spring Boot
• Basics of SQL databases
• Understanding of serverless and cloud services
• Familiarity with testing and deployment processes

Table of Contents

• What is Neon Postgres?
• How to Set Up the Database
  • Create the Database
• How to Build the Spring Boot CRUD App
  • Create an Entity Class
  • Create a Repository
  • Create a REST Controller
  • Configure the Database
• How to Deploy on Azure App Service
  • Create a New Web App
  • Deploy the Application
  • Access the Application
• How to Set Up Autoscaling
  • Autoscaling in Azure
  • Autoscaling in Neon
• How to Configure Database Branches in Neon
• Summary

What is Neon Postgres?

Neon is a fully managed serverless Postgres database platform. It offers features such as high availability, automatic backups, and scaling options to handle varying traffic levels.

Neon is designed to be cost-efficient and developer-friendly, and it focuses on providing a seamless experience for developers.

In addition to the standard Postgres features, it provides capabilities like database branching, allowing you to create Git-like branches of the database for different purposes.

How to Set Up the Database

To begin with, let's explore how you can set up a Neon database for your application.

Firstly, you'll need to create an account on the Neon website. It doesn't require a credit card to sign up, and you're automatically set up with the free tier to get started.

Here's a pricing and features comparison of Neon plans:

Neon pricing plans

In the free tier, we get 0.5 GB of storage with basic computing which is enough for playing around with the database and building small applications.

Create the Database

Once you've signed up, you can access the dashboard and create a new project.

Star by filling in the project name, region, and Postgres version options. In addition to this, we can choose two additional options:

• compute size – You can choose a min and max compute size for the database. This is useful for autoscaling the database based on the load.
• suspend time – You can set a time after which the database will be suspended if not being used. This is useful for saving costs when the database is not being used.

Creating a database project in Neon

Once you submit the form, Neon will create the database and provide the connection details.

Neon Dashboard

As you can see, the database was set up in 3.3 seconds (compared to hours of installing and setting up your own infrastructure). You can choose multiple ways to connect to the database. For this tutorial, select Java as your programming language and get the JDBC connection string.

How to Build the Spring Boot CRUD App

Next, let's set up our CRUD application. We'll use Spring Boot, as it provides easy bootstrapping and configuration for building web applications.

We can use the Spring Initializr to generate a new Spring Boot project with the necessary dependencies:

• Spring Web – for building web applications
• Spring Data JPA – for working with databases using JPA
• PostGres Driver – for connecting to the Postgres database

Creating a Spring Boot project using Spring Initializer

You can generate, download, and import the project into your favorite IDE.

Create an Entity Class

Let's create an entity class to represent the data in the application. First, create a User class:

@Entity(name = "users")
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String name;
    private String email;

    // Constructors, Getters and Setters
}

The entity name users is the name of the table you want to use in your database.

Create a Repository

Next, create a repository interface to interact with the database. You'll extend the JpaRepository interface provided by Spring Data JPA:

@Repository
public interface UserRepository extends JpaRepository<User, Long> {
}

You need to annotate the interface with @Repository to mark it as a Spring bean. The JpaRepository interface provides methods for CRUD operations like save, findAll, findById, delete, and so on, so you don't need to write the queries manually.

You'll provide your entity class User and the type of the primary key Long as type arguments to the JpaRepository interface.

Create a REST Controller

Finally, create a REST controller to handle the CRUD operations. You'll inject the UserRepository into the controller and implement the necessary endpoints:

@RestController
@RequestMapping("/users")
public class UserController {
    private final UserRepository userRepository;

    public UserController(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    @GetMapping
    public List<User> getUsers() {
        return userRepository.findAll();
    }

    @PostMapping
    public User createUser(@RequestBody User user) {
        return userRepository.save(user);
    }

    @PutMapping("/{id}")
    public User updateUser(@PathVariable Long id, @RequestBody User user) {
        user.setId(id);
        return userRepository.save(user);
    }

    @DeleteMapping("/{id}")
    public void deleteUser(@PathVariable Long id) {
        userRepository.deleteById(id);
    }
}

Here are a few things to note:

• You're using the @RestController annotation to mark the class as a controller that handles REST requests.
• The @RequestMapping annotation specifies the base URL for the endpoints.
• You're injecting the UserRepository into the controller using constructor injection.
• Finally, you're implementing your API endpoints for CRUD operations using the @GetMapping, @PostMapping, @PutMapping, and @DeleteMapping annotations.

Configure the Database

To connect your Spring Boot application to the Neon Postgres database, you need to configure the database URL, username, and password in the application.properties file:

spring.datasource.url=jdbc:postgresql://<db-url>/<db-name>?sslmode=require
spring.datasource.username=<username>
spring.datasource.password=<password>
spring.jpa.hibernate.ddl-auto=update

Here, you configured the database URL, username, and password provided by Neon when you created the database. The spring.jpa.hibernate.ddl-auto=update property tells Spring Boot to automatically create the necessary tables or columns based on the entity classes when the application starts.

How to Deploy on Azure App Service

Now that your Spring Boot application is ready, it's time to deploy it on Azure App Service.

Create a New Web App

To deploy your Spring Boot application on Azure App Service, you'll first create a new Web App. You can do this through the Azure portal by following these steps:

• Log in to the Azure portal.
• Click on the Create a resource button.
• Search for Web App and select the Create option.
• Fill in the necessary details like resource group, app name, runtime stack, and region.
• Click the Review + create button.

Creating a Web App in Azure

Deploy the Application

The Web App takes a couple of minutes to create. Once done, you can deploy your Spring Boot application to Azure App Service.

One of the easiest ways to deploy is to package your Spring Boot application as a JAR file and deploy it to Azure App Service using the Azure CLI.

To do this, run the below commands:

mvn package
az webapp deploy --src-path neon-demo-0.0.1-SNAPSHOT.jar --resource-group learn-ba1a439c-71ca-4cab-9bb1-f5b1331bab04 --name neon-app

Here, you're packaging your Spring Boot application using Maven and deploying the JAR file to Azure App Service using the Azure CLI. You've provided the path to the JAR file, the resource group, and the app name you previously configured.

Access the Application

Once the deployment is complete, you can access your Spring Boot application on Azure App Service by navigating to the URL of the Web App. Your app is available at neon-app.azurewebsites.net

Let's use _curl _to test the endpoints.

Create a User

curl -X POST -d '{"name":"John Doe","email":"john@gmail.com"}' https://neon-app.azurewebsites.net/users

Here you provide user data in JSON format to create a new user.

Get Users

You can also can test that the user was created by fetching all users:

curl -X GET https://neon-app.azurewebsites.net/users

How to Set Up Autoscaling

A production application may experience varying levels of traffic, and it's important to scale the application dynamically based on the load.

Let's explore how you can autoscale your application when needed.

Autoscaling in Azure

Azure App Service provides autoscaling options that let you automatically adjust the number of instances as needed.

You can configure autoscaling rules in the Azure portal by following these steps:

• Navigate to the Web App in the Azure portal.
• Click the Scale out (App Service Plan) option from the left menu.
• Configure the autoscaling rules – you can choose predefined rules like traffic or create custom rules based on metrics like CPU usage, memory usage, or custom metrics.
• Save.

Azure will automatically scale the application based on the configured rules.

Autoscaling in Neon

Since your application is automatically scaled based on the load, you'll want to ensure that the database can handle the increased traffic.

Neon provides autoscaling options to scale the database dynamically based on the load. You can configure autoscaling rules in the Neon dashboard to ensure the database can handle the increased load.

Follow the below steps to configure autoscaling in Neon:

1. Navigate to the Neon dashboard and select the database. Then select the branch to configure autoscaling.

Selecting a branch from Neon project dashboard

2. Click on the Edit button next to the Compute section. Configure the autoscaling rules based on metrics like CPU usage, memory usage, or custom metrics.

Branch details view in Neon

3. Configure the min-max compute size and Save. Neon will automatically scale the database based on the configured rules when needed.

Setting up autoscaling for compute

Ensuring that both the application and the database can scale dynamically based on the load will help you handle varying levels of traffic efficiently.

How to Configure Database Branches in Neon

In a typical development workflow, multiple databases may be used for different purposes like development, testing, and production.

Neon Postgres provides database branching to create multiple branches for different purposes. Each branch is an instance of the database that you can use independently.

This Git-like feature helps set up a copy of the database for different environments like development, staging, and production. It also helps preserve data for different versions of the application.

Let's explore how you can create and manage branches in Neon Postgres:

• Navigate to the Neon dashboard and select the database.
• In the Branches section, click on the View All button.
• You can create a new branch from an existing one by clicking on the Create Branch button. You'll need to provide the branch name and what data to copy from the parent branch.

Create branch option

• You can either copy all the data or copy until a point in time or a specific record. This is useful for multiple purposes like restoring data, creating a new environment, or testing new features.

Creating a new branch

• Neon will create a new branch of the database that can be used independently. You can find the URL, username, and password for the new branch in the dashboard. And this happens in real time without any downtime and delays.

Branch-specific connection details

Now you can use your dev branch for local development and testing, and the main branch for production. This helps in keeping the data separate and ensures that changes in one branch do not affect the other branches.

Summary

In this article, we built a CRUD application using Spring Boot, Neon Postgres, and Azure App Service.

We explored how to set up the Neon Postgres database, build a basic CRUD application using Spring Boot, deploy the application on Azure App Service, and configure autoscaling for the application and the database.

We also learned about how the database branching feature in Neon Postgres helps you create branches of the database for different environments and purposes.

Throughout this tutorial, you'll learn how to create, read, update, and delete Todo items, and how to leverage Entity Framework Core to interact with a database.

Table of Contents

• Prerequisites
• How to Enhance Your Development Experience with Visual Studio Code Extensions
• Learning Outcomes
• What is .NET Core?
• .NET Core vs .NET Framework
• Step 1: Set Up Your Project Directory
• Step 2: Establish Your Project Structure
• Step 3: Create the Todo Model
• Step 4: Set Up the Database Context
• Step 5: Define Data Transfer Objects (DTOs)
• Step 6: Implement Object Mapping for the Todo API
• Step 7: Implement Global Exception Handling Middleware
• Step 8: Implement the Service Layer and Service Interface
• step 9: Implement the CreateTodoAsync Method in the Service Class
• Step 10: Implement the GetAllAsync Method in the Service Class
• step 11: Create the TodoController Class
• Step 12: Implement the CreateTodoAsync Method in the TodoController Class
• Step 13: Implement Migrations and Update the Database
• Step 14: Verify Your API with Postman
• Step 15: Retrieve All Todo Items
• Step 16: Implement the GetByIdAsync Method
• Step 17: Implement the UpdateTodoAsync Method
• Step 18: Implement the DeleteTodoAsync Method
• Step 19: Test Your API Endpoints with Postman
• Conclusion

Before we dive in, let's ensure you're equipped with the necessary prerequisites.

Prerequisites

Before you get started, make sure you have the necessary tools installed on your machine. Here are the download links:

• .NET SDK
• Visual Studio Code
• Visual Studio 2019
• Postman
• SQLServer

After installing the .NET SDK, it's important to verify its installation and check the version. For this tutorial, we'll be using .NET 8.0.

To check the version of the .NET SDK installed on your machine, open the terminal and run the following command:

dotnet --version

If the .NET SDK is installed correctly, the version number will be displayed in the terminal:

8.0

If you see a different version number, ensure you have .NET 8.0 installed on your machine.

How to Enhance Your Development Experience with Visual Studio Code Extensions

Visual Studio Code, a lightweight and open-source code editor, is an excellent tool for building .NET Core applications. And you can further enhance its functionality with extensions that streamline the development process.

Here are two recommended extensions for .NET Core development:

• C# for Visual Studio Code
• C# Namespace Autocompletion

To install these extensions, follow these steps:

1. Open Visual Studio Code.
2. Click on the Extensions icon in the Activity Bar on the side of the window to open the Extensions view.
3. In the search bar, type the name of the extension.
4. In the search results, locate the correct extension and click on the Install button.

Here's how the Extensions view looks in Visual Studio Code:

• C# Devkit Extension for Visual Studio Code

• Namespace Autocompletion Extension for Visual Studio Code

In the images above, the extensions are already installed. If they're not installed on your system, you can do so by clicking on the Install button.

With these essential tools in place, we're now fully equipped to start building our Todo API.

Learning Outcomes

By the end of this tutorial, you'll have learned how to:

• Set up a new .NET Core project using the .NET Core CLI
• Define a model for a Todo item
• Create a database context to interact with the database
• Implement routing and controllers for the Todo API
• Create a service class to handle business logic
• Implement CRUD operations for the Todo API
• Handle exceptions globally using middleware
• Test the API endpoints using Postman

If you're new to C# and .NET, don't worry. I'll explain all the concepts in depth to ensure you understand them. For additional information, you can refer to the C# documentation.

Before we delve into the code, let's clarify what .NET Core is.

What is .NET Core?

.NET Core, also known as ASP.NET, is a cross-platform framework that facilitates the building of web applications, APIs, and services. It's a free, open-source, and high-performance framework, designed for creating modern, cloud-based, internet-connected applications. It's the successor to the .NET Framework.

But what's the difference between .NET Core and .NET Framework?

.NET Core vs .NET Framework

.NET Core and .NET Framework are two distinct frameworks used for application development. .NET Core is a cross-platform framework that operates on Windows, macOS, and Linux. It's a modular, open-source, and free-to-use framework, designed for building modern, cloud-based, internet-connected applications.

On the other hand, .NET Framework is a Windows-only framework used for building Windows desktop applications, web applications, and services. Unlike .NET Core, it's not open-source or free to use. However, it's a mature framework that has been around for a long time.

With a foundational understanding of .NET Core and .NET Framework under your belt, we're ready to dive into building our Todo API.

In this tutorial, we'll leverage .NET Core to construct a Todo API that performs CRUD operations. Our journey will take us through creating a new project, defining the Todo model, setting up the database, and implementing the CRUD operations.

Let's begin with Visual Studio Code. In this tutorial, we'll be using the .NET Core CLI to create our project and build our API. If you prefer Visual Studio 2019, you can follow along using that IDE as well but we will be using Visual Studio Code for this article.

Step 1: Set Up Your Project Directory

First, navigate to the directory where you want to house your project. This could be any folder on your system where you'd like to store your code.

Once you're in the desired directory, open the terminal. You can do this in Visual Studio Code by going to View -> Terminal or by pressing Ctrl + a backtick.

With the terminal open, type the following command:

dotnet new webapi -n TodoAPI

This command instructs the .NET Core CLI to create a new web API project named TodoAPI. The -n option specifies the name of the project.

The image above illustrates how to execute the command in the terminal.

After pressing the 'Enter' key, the .NET Core CLI will start generating the necessary files for your project.

The image above showcases the generated project structure. It includes all the necessary files and directories required for a .NET Core web API project.

With the project files and folders generated by the .NET Core CLI, let's take a moment to understand the purpose of each file.

• appsettings.json: This file houses the application's configuration settings. It's the go-to place for storing connection strings, logging configurations, and other settings.

• Program.cs: Serving as the application's entry point, this file is responsible for setting up the host and configuring the services.

• TodoAPI.csproj: This project file contains metadata about your project, including references to the necessary packages and libraries.

• appsettings.Development.json: This file is designed for configuration settings specific to the development environment. It's ideal for storing environment-specific settings. But for the purpose of this tutorial, we'll be using the appsettings.json file instead.

• TodoAPI.http: This file is typically used to test API endpoints using the REST Client extension in Visual Studio Code, as it contains sample requests for the API endpoints. However, in this tutorial, we'll be using Postman for testing, so we won't need this file and will proceed to delete it.

Step 2: Establish Your Project Structure

Having set up our project directory, it's time to lay out the structure of our project. We'll be creating several folders, each with a specific purpose:

• AppDataContext: This folder will contain the database context, which is responsible for interacting with the database.
• Contracts: This folder will house our Data Transfer Objects (DTOs), which are used to shape the data sent between the client and the server.
• Models: This folder will contain the Todo model, which represents the structure of a Todo item.
• Controllers: This folder will house the TodoController, which handles incoming HTTP requests and sends responses.
• Interfaces: This folder will contain the IService interface, which defines the contract for our service class.
• Services: This folder will house the Service class, which implements the IService interface and contains the business logic of our application.
• Mapping: This folder will contain the mapping profile, which is used to map properties between different objects.
• Middleware: This folder will house the exception middleware, which handles exceptions globally across our application.

Congratulations! You've successfully set up your project directory and established the project structure. In the next section, we'll delve into defining the Todo model.

How to Adjust the Program.cs File for ControllerBase

When creating a new application using the dotnet new webapi command in .NET Core 6 and onwards, the generated project is a minimal web API project. But for this tutorial, we'll be using the traditional way of creating APIs, which requires some adjustments to the Program.cs file.

Before we dive into the changes, let's briefly discuss what a minimal API is.

Understanding Minimal APIs

In .NET 6, Microsoft introduced a new feature known as Minimal APIs. These APIs are simpler and more lightweight than traditional APIs. They allow you to define your API routes and endpoints using a single file, without the need for controllers or startup classes. This approach facilitates the creation of small, focused APIs that are quick to build and easy to maintain.

However, for the purpose of this tutorial, we'll stick to the traditional API structure. Let's proceed with the necessary changes to the Program.cs file.

The image above displays the initial state of the Program.cs file when you create a new web API project. To adapt it for use with ControllerBase, we need to remove some code and add new code.

Start by deleting everything in the Program.cs file and replacing it with the following code:

 // program.cs
var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddControllers();

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Now we can proceed to the next step, where we'll define the Todo model.

Step 3: Create the Todo Model

Before diving into creating our Todo model, it's important to know what a model does in .NET CORE. Think of a model as a blueprint for the kind of data our application will work with. It helps us organize and manage this data efficiently.

For our Todo list app, we need a clear picture of what each Todo item looks like. This means deciding on things like names, descriptions, whether it's done or not, deadlines, priorities, and when it was made or changed. By being clear about these details, we can handle and show our Todo items well.

Meet the Todo Model

Now, let's make our idea real by creating the Todo model. This model is like a template for our Todo items, making sure they have all the right pieces.

Let's create a new file called Todo.cs in the Models folder and fill it with this code:

// Models/Todo.cs
using System.ComponentModel.DataAnnotations;

namespace TodoAPI.Models
{
    public class Todo
    {
        [Key]
        public Guid Id { get; set; }
        public string Title { get; set; }
        public string Description { get; set; }
        public bool IsComplete { get; set; }
        public DateTime DueDate { get; set; }
        public int Priority { get; set; }
        public DateTime CreatedAt { get; set; }
        public DateTime UpdatedAt { get; set; }

        public Todo()
        {
            IsComplete = false;
        }
    }
}

Here's what each part of the Todo model means:

• Id: A special number that makes each Todo item unique.
• Title: The name of the Todo item.
• Description: Extra details about the Todo item.
• IsComplete: Whether the Todo item is finished or not.
• DueDate: The date by which the Todo item needs to be done.
• Priority: How important the Todo item is.
• CreatedAt and UpdatedAt: When the Todo item was first made and last changed.

The [Key] tag tells us that Id is the main way to identify each Todo item in our database.

By having a clear Todo model, we can easily keep track of and display our Todo items in the best way possible.

In ASP.NET Core, models can be used to represent a variety of things. One such use case is error handling. When an error occurs in our application, we can create a model for that error and return it to the client.

Let's create a model specifically for error handling in our application.

// Models/ErrorResponse.cs

namespace TodoAPI.Models
{
       public class ErrorResponse
 {
     public string Title { get; set; }
     public int StatusCode { get; set; }
     public string Message { get; set; }
 }
}

This ErrorResponse model will be used to return error messages to the client when an error occurs in our application. It includes a title for the error, massage, and a status code, providing the client with useful information about what went wrong.

Let's define another model to manage our database connection string.

// Models/DbSettings.cs 

namespace TodoAPI.Models
{
    public class DbSettings
    {
        public string ConnectionString { get; set; }
    }
}

The DbSettings model is designed to encapsulate the connection string for our database. It contains a single property, ConnectionString, which will store the actual connection string value.

With our Todo model in place, we're now ready to proceed with setting up the database context.

Before we begin setting up our database, we need to install the necessary packages for our project.

Package Installation

To set up our project, we need to install several packages. We'll use the dotnet CLI for this task.

Before we begin, ensure you're in the root directory of your project. If you're unsure of your current location in the terminal, you can verify it by running the following command:

ls

This command will list all the files and folders in your current directory. The image below shows the terminal output after running the ls command.

If your terminal output matches the image above, you're in the correct directory to install the packages.

Now, let's install the packages:

dotnet add package Microsoft.EntityFrameworkCore --version 8.0.0 
dotnet add package Microsoft.EntityFrameworkCore.Design --version 8.0.0
dotnet add package Microsoft.EntityFrameworkCore.SqlServer --version 8.0.0
dotnet add package AutoMapper --version 13.0.1

Here's a brief overview of what these packages do:

• Microsoft.EntityFrameworkCore: Provides the core Entity Framework Core functionality, enabling us to interact with our database.
• Microsoft.EntityFrameworkCore.Design: Includes design-time components for Entity Framework Core, such as migrations.
• Microsoft.EntityFrameworkCore.SqlServer: Allows us to use SQL Server as our database provider.
• AutoMapper: Simplifies object-to-object mapping, making it easier to map properties between different objects.

Note: Ensure you install the same versions of the packages as shown above to avoid any compatibility issues.

To confirm that all the packages have been installed successfully, navigate to the TodoAPI.csproj file located in the root directory of your project. The installed packages should be listed under the ItemGroup section.

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <InvariantGlobalization>true</InvariantGlobalization>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="AutoMapper" Version="13.0.1" />
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="8.0.0" />
    <PackageReference Include="Microsoft.EntityFrameworkCore" Version="8.0.0" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="8.0.0">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
    <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="8.0.0" />
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.4.0" />
  </ItemGroup>

</Project>

The above TodoAPI.csproj file shows the installed packages listed under the ItemGroup section. If your TodoAPI.csproj file reflects the same, it confirms that the packages have been installed successfully.

With the necessary packages installed, we're now ready to set up the database context for our Todo API.

Step 4: Set Up the Database Context

In ASP.NET Core, the database context is a crucial component that manages interactions with the database. It's responsible for tasks such as establishing a connection to the database, querying data, and saving changes.

To enable our Todo API to interact with the database, we need to create a database context.

Let's create a new file named TodoDbContext in the AppDataContext folder and populate it with the following code:

// AppDataContext/TodoDbContext.cs

using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Options;
using TodoAPI.Models;

namespace TodoAPI.AppDataContext
{

    // TodoDbContext class inherits from DbContext
     public class TodoDbContext : DbContext
     {

        // DbSettings field to store the connection string
         private readonly DbSettings _dbsettings;

            // Constructor to inject the DbSettings model
         public TodoDbContext(IOptions<DbSettings> dbSettings)
         {
             _dbsettings = dbSettings.Value;
         }


        // DbSet property to represent the Todo table
         public DbSet<Todo> Todos { get; set; }

         // Configuring the database provider and connection string

         protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
         {
             optionsBuilder.UseSqlServer(_dbsettings.ConnectionString);
         }

            // Configuring the model for the Todo entity
         protected override void OnModelCreating(ModelBuilder modelBuilder)
         {
             modelBuilder.Entity<Todo>()
                 .ToTable("TodoAPI")
                 .HasKey(x => x.id);
         }
     }
}

Here's a breakdown of the TodoDbContext class:

• TodoDbContext: This class, which inherits from DbContext (a part of Entity Framework Core), is the primary class that interacts with the database.
• _dbsettings: This private field stores the connection string for our database. We inject the DbSettings model, which we created earlier to manage the connection string, into the TodoDbContext class.
• Todos: This property represents the Todo table in our database. It's a DbSet of Todo objects, which allows us to query and save instances of Todo.
• OnConfiguring: This method configures the database provider and connection string. We're using SQL Server as our database provider, and the connection string is retrieved from the DbSettings model.
• OnModelCreating: This method configures the model for the Todo entity. We specify the table name, primary key, and other configurations for the Todo entity.

To use our TodoDbContext for interacting with the database, we need to register it in the Program.cs file. This registration process is part of setting up the Dependency Injection (DI) container in .NET Core.

Here's how to do it:

// Program.cs


using TodoAPI.AppDataContext;
using TodoAPI.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();



 // Add  This to in the Program.cs file
builder.Services.Configure<DbSettings>(builder.Configuration.GetSection("DbSettings")); // Add this line
builder.Services.AddSingleton<TodoDbContext>(); // Add this line




var app = builder.Build();

// Add this line

{
    using var scope = app.Services.CreateScope(); // Add this line
    var context = scope.ServiceProvider; // Add this line
}


if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();
app.UseExceptionHandler();
app.UseAuthorization();

app.MapControllers();

app.Run();

In the code snippet above, we're doing two things:

• Configuring the database settings by binding the DbSettings section from the appsettings.json file to the DbSettings class. This allows us to access the database connection string in our application.
• Registering the TodoDbContext with the DI container as a singleton service. This means that a single instance of TodoDbContext will be created and shared across the entire application.

With the database context registered, we can now use it to perform CRUD operations on our Todo items.

Now let's check if everything is working fine by running the application.

dotnet run

If you see the following output, it means your application is running successfully:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5086
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
Content root path: E:\Todo\TodoAPI

Note: If you encounter any errors, just make sure you've followed all the steps correctly and that the necessary packages have been installed successfully. If you see some warnings, you can ignore them for now.

With the TodoDbContext class now set up, we're ready to define the Contracts for our application.

Step 5: Define Data Transfer Objects (DTOs)

In the context of .NET development, a Data Transfer Object (DTO) is a simple object that carries data between processes. It's often used in conjunction with a service layer to shape the data sent between the client and the server.

For our Todo API, we'll define two DTOs: CreateTodoRequest and UpdateTodoRequest. These DTOs will help us enforce the structure and validation of the data sent to our API.

Navigate to the Contracts folder and create two new files: CreateTodoRequest.cs and UpdateTodoRequest.cs.

The CreateTodoRequest File

The CreateTodoRequest DTO will define the structure and validation rules for creating a new Todo item. Add the following code to the CreateTodoRequest.cs file:

public class CreateTodoRequest
{
    [Required]
    [StringLength(100)]
    public string Title { get; set; }

    [StringLength(500)]
    public string Description { get; set; }

    [Required]
    public DateTime DueDate { get; set; }

    [Range(1, 5)]
    public int Priority { get; set; }
}

In this DTO, we've defined properties for Title, Description, DueDate, and Priority. We've also added validation attributes like [Required], [StringLength], and [Range] to enforce certain rules on these properties.

The UpdateTodoRequest File

The UpdateTodoRequest DTO will define the structure and validation rules for updating an existing Todo item. Add the following code to the UpdateTodoRequest.cs file:

public class UpdateTodoRequest
{
    [StringLength(100)]
    public string Title { get; set; }

    [StringLength(500)]
    public string Description { get; set; }

    public bool? IsComplete { get; set; }

    public DateTime? DueDate { get; set; }

    [Range(1, 5)]
    public int? Priority { get; set; }

    public UpdateTodoRequest()
    {
        IsComplete = false;
    }
}

In this DTO, we've defined properties for Title, Description, IsComplete, DueDate, and Priority. The IsComplete property is nullable, which means it can be set to null if not provided. We've also added validation attributes like [StringLength] and [Range] to enforce certain rules on these properties.

With these DTOs in place, we're now ready to implement the service layer for our Todo API.

Now test the application, and see if there are any errors.

 dotnet  build

If you see the following output, it means your application is running successfully:

MSBuild version 17.8.3+195e7f5a3 for .NET
  Determining projects to restore...
  All projects are up-to-date for restore.
  TodoAPI -> E:\Todo\TodoAPI\bin\Debug\net8.0\TodoAPI.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:00.94

Note: If you encounter any errors, make sure you've followed all the steps correctly and that the necessary packages have been installed successfully. If you see some warnings, you can ignore them for now.

With the DTOs defined, we're now ready to implement the Mapping for the Todo API.

Step 6: Implement Object Mapping for the Todo API

Having defined the DTOs for our Todo API, the next step is to implement object mapping. This process allows us to convert between the DTOs and the Todo model, a critical aspect of data transformation in our application.

To streamline this process, we'll use the AutoMapper library. AutoMapper is a widely-used library that simplifies object-to-object mapping, making it easier to map properties between different objects.

We've already installed the AutoMapper package in our project. Now, in the MappingProfiles folder, create a new file named AutoMapperProfile.cs and add the following code:

using AutoMapper;
using TodoAPI.Contracts;
using TodoAPI.Models;

namespace TodoAPI.MappingProfiles
{
    public class AutoMapperProfile : Profile
    {
        public AutoMapperProfile()
        {
            CreateMap<CreateTodoRequest, Todo>()
                .ForMember(dest => dest.id, opt => opt.Ignore())
                .ForMember(dest => dest.CreatedAt, opt => opt.Ignore())
                .ForMember(dest => dest.UpdatedAt, opt => opt.Ignore());

            CreateMap<UpdateTodoRequest, Todo>()
                .ForMember(dest => dest.id, opt => opt.Ignore())
                .ForMember(dest => dest.CreatedAt, opt => opt.Ignore())
                .ForMember(dest => dest.UpdatedAt, opt => opt.Ignore());
        }
    }
}

Let's break down the AutoMapperProfile class:

• AutoMapperProfile: This class, which inherits from Profile (a class provided by AutoMapper), allows us to define mapping configurations.
• CreateMap: This method creates a mapping between two objects. Here, we're mapping from CreateTodoRequest to Todo and from UpdateTodoRequest to Todo.
• ForMember: This method configures the mapping for a specific property. We're using it to ignore the id, CreatedAt, and UpdatedAt properties when mapping from the DTOs to the Todo model.

Now let's add the automapper to the DI container in the Program.cs file.

// Program.cs

using TodoAPI.AppDataContext;
using TodoAPI.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();



 // Add  This to in the Program.cs file
builder.Services.AddAutoMapper(AppDomain.CurrentDomain.GetAssemblies());  // Add this line


// .....

var app = builder.Build();



// .....
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseExceptionHandler();
app.UseAuthorization();

app.MapControllers();

app.Run();

With the mapping profiles in place, we can now implement the service layer for our Todo API.

Step 7: Implement Global Exception Handling Middleware

As we progress with our Todo API, it's crucial to implement a mechanism for handling exceptions globally. This ensures that any exceptions that occur during the execution of our application are caught and handled appropriately, providing meaningful error messages to the client.

.NET 8 introduces the IExceptionHandler interface, which simplifies the process of creating a custom exception handler. This handler will catch all exceptions that occur in our application and return a consistent error response to the client.

Let's create a global exception handler in the Middleware folder. Create a new file named GlobalExceptionHandler.cs and add the following code:

// Middleware/GlobalExceptionHandler.cs

using System.Net;
using Microsoft.AspNetCore.Diagnostics;
using TodoAPI.Models;

namespace TodoAPI.Middleware
{
    public class GlobalExceptionHandler : IExceptionHandler
    {
        private readonly ILogger<GlobalExceptionHandler> _logger;

        public GlobalExceptionHandler(ILogger<GlobalExceptionHandler> logger)
        {
            _logger = logger;
        }

        public async ValueTask<bool> TryHandleAsync(
            HttpContext httpContext,
            Exception exception,
            CancellationToken cancellationToken)
        {
            _logger.LogError(
                $"An error occurred while processing your request: {exception.Message}");

            var errorResponse = new ErrorResponse
            {
                Message = exception.Message
            };

            switch (exception)
            {
                case BadHttpRequestException:
                    errorResponse.StatusCode = (int)HttpStatusCode.BadRequest;
                    errorResponse.Title = exception.GetType().Name;
                    break;

                default:
                    errorResponse.StatusCode = (int)HttpStatusCode.InternalServerError;
                    errorResponse.Title = "Internal Server Error";
                    break;
            }

            httpContext.Response.StatusCode = errorResponse.StatusCode;

            await httpContext
                .Response
                .WriteAsJsonAsync(errorResponse, cancellationToken);

            return true;
        }
    }
}

Here's a breakdown of the GlobalExceptionHandler class:

• GlobalExceptionHandler: This class implements the IExceptionHandler interface, enabling global exception handling in our application.
• TryHandleAsync: This method is invoked when an exception occurs. It logs the error message, creates an ErrorResponse object, sets the status code and title based on the exception type, and returns a consistent error response to the client.
• ErrorResponse: This class represents the error response returned to the client when an exception occurs. It contains properties for the error message, status code, and title.
• BadHttpRequestException: This case handles exceptions of type BadHttpRequestException and sets the status code and title accordingly.

After setting up the global exception handler, we need to register it in our Program.cs file:

// Program.cs

using TodoAPI.AppDataContext;
using TodoAPI.Interface;
using TodoAPI.Middleware;
using TodoAPI.Models;
using TodoAPI.Services;

var builder = WebApplication.CreateBuilder(args);



builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();



// ....



builder.Services.AddExceptionHandler<GlobalExceptionHandler>(); // Add this line

builder.Services.AddProblemDetails();  // Add this line

// Adding of login 
builder.Services.AddLogging();  //  Add this line



var app = builder.Build();


// ......


if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection(); // Add this line

app.UseExceptionHandler();
app.UseAuthorization();

app.MapControllers();

app.Run();


// ...

Step 8: Implement the Service Layer and Service Interface

In .NET development, the service layer encapsulates the core business logic of an application. It serves as a bridge between the controller and the database, ensuring a clean separation of concerns.

First, let's define an interface for our service layer.

// Interfaces/ITodoServices.cs 

using TodoAPI.Contracts;
using TodoAPI.Models;

namespace TodoAPI.Interface
{
     public interface ITodoServices
     {
         Task<IEnumerable<Todo>> GetAllAsync();
         Task<Todo> GetByIdAsync(Guid id);
         Task CreateTodoAsync(CreateTodoRequest request);
         Task UpdateTodoAsync(Guid id, UpdateTodoRequest request);
         Task DeleteTodoAsync(Guid id);
     }
}

Here's a brief overview of the methods defined in the ITodoServices interface:

• GetAllAsync: Retrieves all Todo items from the database.
• GetByIdAsync: Fetches a specific Todo item by its Id.
• CreateTodoAsync: Adds a new Todo item to the database.
• UpdateTodoAsync: Modifies an existing Todo item in the database.
• DeleteTodoAsync: Removes a Todo item from the database.

Now, let's create a service class that implements these methods. We'll use Dependency Injection to inject the ITodoServices interface into the service class, making our code more modular, testable, and maintainable.

// Services/TodoServices.cs

using TodoAPI.Interface;

namespace TodoAPI.Services
{
    public class TodoServices : ITodoServices
    {

    }
}

At this point, you'll encounter an error because we haven't implemented the methods from the ITodoServices interface in the TodoServices class.

The below image shows the error message that appears when the methods from the ITodoServices interface are not implemented in the TodoServices class.

To resolve this, hover over ITodoServices, click on the light bulb icon that appears, and select 'Implement interface'. This will automatically generate stubs for the methods defined in the ITodoServices interface.

The below image shows the 'Implement interface' option that appears when hovering over ITodoServices in the TodoServices class.

After implementing the interface, the TodoServices class should look like this:

// Services/TodoServices.cs
using TodoAPI.Contracts;
using TodoAPI.Interface;
using TodoAPI.Models;

namespace TodoAPI.Services
{
    public class TodoServices : ITodoServices
    {
        public Task CreateTodoAsync(CreateTodoRequest request)
        {
            throw new NotImplementedException();
        }

        public Task DeleteTodoAsync(Guid id)
        {
            throw new NotImplementedException();
        }

        public Task<IEnumerable<Todo>> GetAllAsync()
        {
            throw new NotImplementedException();
        }

        public Task<Todo> GetByIdAsync(Guid id)
        {
            throw new NotImplementedException();
        }

        public Task UpdateTodoAsync(Guid id, UpdateTodoRequest request)
        {
            throw new NotImplementedException();
        }
    }
}

How to Enhance the TodoServices Class with Dependency Injection

Now, let's enrich our TodoServices class with some essential properties. These properties will provide the necessary tools for interacting with the database, logging, and object mapping.

At the top of the TodoServices class, add the following properties:

// Services/TodoServices.cs

// ...

private readonly TodoDbContext _context;
private readonly ILogger<TodoServices> _logger;
private readonly IMapper _mapper;

// ...

Here's a brief explanation of these properties:

• _context: An instance of the TodoDbContext class, enabling us to interact with the database.
• _logger: An instance of the ILogger class, facilitating logging throughout our application.
• _mapper: An instance of the IMapper class, allowing us to perform object-to-object mapping using AutoMapper.

Next, we'll update the constructor of the TodoServices class to inject these dependencies:

// Services/TodoServices.cs

// ...

public TodoServices(TodoDbContext context, ILogger<TodoServices> logger, IMapper mapper)
{
    _context = context;
    _logger = logger;
    _mapper = mapper;
}

// ...

With these dependencies injected, we're now ready to implement the methods defined in the ITodoServices interface. We'll begin with the GetAllAsync method in the next section.

Step 9: Implement the CreateTodoAsync Method in the TodoServices Class

Now, let's implement the CreateTodoAsync method in the TodoServices class. This method will handle the creation of new Todo items in our database.

Navigate to the TodoServices class and add the following code to the CreateTodoAsync method:

// Services/TodoServices.cs

// ...

public async Task CreateTodoAsync(CreateTodoRequest request)
{
    try
    {
        var todo = _mapper.Map<Todo>(request);
        todo.CreatedAt = DateTime.UtcNow;
        _context.Todos.Add(todo);
        await _context.SaveChangesAsync();
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "An error occurred while creating the Todo item.");
        throw new Exception("An error occurred while creating the Todo item.");
    }
}

// ...

Here's a breakdown of the CreateTodoAsync method:

• Mapping: We use AutoMapper to convert the CreateTodoRequest object into a Todo entity.
• CreatedAt: We set the CreatedAt property of the Todo entity to the current UTC date and time.
• Adding to the Database: We add the Todo entity to the Todos DbSet in our context and save the changes asynchronously.
• Error Handling: We catch any exceptions that might occur during the process, log the error, and throw a new exception with a descriptive error message.

With the CreateTodoAsync method implemented, we can now create new Todo items in our database.

Step 10: Implement the GetAllAsync Method in the Service Class

Next, let's implement the GetAllAsync method in the TodoServices class. This method will retrieve all Todo items from the database.

Navigate to the TodoServices class and add the following code to the GetAllAsync method:

// Services/TodoServices.cs

// ...


 // Get all TODO Items from the database 
 public async Task<IEnumerable<Todo>> GetAllAsync()
 {
     var todo= await _context.Todos.ToListAsync();
     if (todo == null)
     {
         throw new Exception(" No Todo items found");
     }
     return todo;

 }

// ...

Here's a breakdown of the GetAllAsync method:

• Retrieving Todo Items: We use Entity Framework Core's ToListAsync method to fetch all Todo items from the database.

• Error Handling: If no Todo items are found, we throw an exception with a descriptive error message.

Now Your Service class should look like this:

using AutoMapper;
using Microsoft.EntityFrameworkCore;
using TodoAPI.AppDataContext;
using TodoAPI.Contracts;
using TodoAPI.Interface;
using TodoAPI.Models;

namespace TodoAPI.Services
{
    public class TodoServices : ITodoServices
    {
        private readonly TodoDbContext _context;
        private readonly ILogger<TodoServices> _logger;
        private readonly IMapper _mapper;

        public TodoServices(TodoDbContext context, ILogger<TodoServices> logger, IMapper mapper)
        {
            _context = context;
            _logger = logger;
            _mapper = mapper;
        }




        //  Create Todo for it be save in the datbase 

        public async Task CreateTodoAsync(CreateTodoRequest request)
        {
            try
            {
                var todo = _mapper.Map<Todo>(request);
                todo.CreatedAt = DateTime.Now;
                _context.Todos.Add(todo);
                await _context.SaveChangesAsync();
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "An error occurred while creating the todo item.");
                throw new Exception("An error occurred while creating the todo item.");
            }
        }

        public async Task<IEnumerable<Todo>> GetAllAsync()
        {
            var todo = await _context.Todos.ToListAsync();
            if (todo == null)
            {
                throw new Exception(" No Todo items found");
            }
            return todo;

        }
        public Task DeleteTodoAsync(Guid id)
        {
            throw new NotImplementedException();
        }

        // Get all TODO Items from the database 


        public Task<Todo> GetByIdAsync(Guid id)
        {
            throw new NotImplementedException();
        }

        public Task UpdateTodoAsync(Guid id, UpdateTodoRequest request)
        {
            throw new NotImplementedException();
        }
    }
}

Now we have implemented the CreateTodoAsync and GetAllAsync methods in the TodoServices class. Before we proceed to implement the remaining methods, let's create routes for our API in the Controllers folder. So now let's create the TodoController class.

Step 11: Create the TodoController Class

In ASP.NET Core, controllers are responsible for handling incoming HTTP requests and sending responses. They serve as the entry point for our API, defining the routes and actions that clients can interact with.

Let's create a new file named TodoController.cs in the Controllers folder and add the following code:

using Microsoft.AspNetCore.Mvc;
using TodoAPI.Interface;

namespace TodoAPI.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class TodoController : ControllerBase
    {
        private readonly ITodoServices _todoServices;

        public TodoController(ITodoServices todoServices)
        {
            _todoServices = todoServices;
        }

    }
}

The TodoController class inherits from ControllerBase, a base class provided by ASP.NET Core for creating controllers. We've also added a route prefix of api/[controller] to the controller, which will be used as the base route for all actions in the controller.

Step 12: Implement the CreateTodoAsync Method in the TodoController Class

Now that we have our Controller class, let's implement the CreateTodoAsync method in the TodoController class. This method will handle the creation of new Todo items in our database.

Navigate to the TodoController class and add the following code to the CreateTodoAsync method:

// Controllers/TodoController.cs

// ...
  [HttpPost]
  public async Task<IActionResult> CreateTodoAsync(CreateTodoRequest request)
  {
      if (!ModelState.IsValid)
      {
          return BadRequest(ModelState);
      }


      try
      {

          await _todoServices.CreateTodoAsync(request);
          return Ok(new { message = "Blog post successfully created" });

      }
      catch (Exception ex)
      {
          return StatusCode(500, new { message = "An error occurred while creating the  crating Todo Item", error = ex.Message });

      }
  }
  // ...

Here's a breakdown of the CreateTodoAsync method:

• Model Validation: We check if the request model is valid using ModelState.IsValid. If the model is not valid, we return a BadRequest response with the model state errors.

• Creating a Todo Item: We call the CreateTodoAsync method from the ITodoServices interface to create a new Todo item in the database.

• Success Response: If the Todo item is created successfully, we return an Ok response with a success message.

• Error Handling: If an error occurs during the creation process, we return a 500 Internal Server Error response with an error message.

Now let's implement the GetAllAsync method in the TodoController class. This method will retrieve all Todo items from the database.

Navigate to the TodoController class and add the following code to the GetAllAsync method:

// Controllers/TodoController.cs 

// ...

  [HttpGet]
  public async Task<IActionResult> GetAllAsync()
  {
      try
      {
          var todo = await _todoServices.GetAllAsync();
          if (todo == null || !todo.Any())
          {
              return Ok(new { message = "No Todo Items  found" });
          }
          return Ok(new { message = "Successfully retrieved all blog posts", data = todo });

      }
      catch (Exception ex)
      {
          return StatusCode(500, new { message = "An error occurred while retrieving all Tood it posts", error = ex.Message });


      }
  }

// ...

Here's a breakdown of the GetAllAsync method:

• Retrieving Todo Items: We call the GetAllAsync method from the ITodoServices interface to fetch all Todo items from the database.

• Success Response: If Todo items are retrieved successfully, we return an Ok response with a success message and the list of Todo items.

• Error Handling: If an error occurs during the retrieval process, we return a 500 Internal Server Error response with an error message.

Now your TodoController class should look like this:

using Microsoft.AspNetCore.Mvc;
using TodoAPI.Contracts;
using TodoAPI.Interface;

namespace TodoAPI.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class TodoController : ControllerBase
    {
        private readonly ITodoServices _todoServices;

        public TodoController(ITodoServices todoServices)
        {
            _todoServices = todoServices;
        }



// Creating new Todo Item
[HttpPost]
  public async Task<IActionResult> CreateTodoAsync(CreateTodoRequest request)
  {
      if (!ModelState.IsValid)
      {
          return BadRequest(ModelState);
      }


      try
      {

          await _todoServices.CreateTodoAsync(request);
          return Ok(new { message = "Blog post successfully created" });

      }
      catch (Exception ex)
      {
          return StatusCode(500, new { message = "An error occurred while creating the  crating Todo Item", error = ex.Message });

      }
  }

    // Get all Todo Items

      [HttpGet]
  public async Task<IActionResult> GetAllAsync()
  {
      try
      {
          var todo = await _todoServices.GetAllAsync();
          if (todo == null || !todo.Any())
          {
              return Ok(new { message = "No Todo Items  found" });
          }
          return Ok(new { message = "Successfully retrieved all blog posts", data = todo });

      }
      catch (Exception ex)
      {
          return StatusCode(500, new { message = "An error occurred while retrieving all Tood it posts", error = ex.Message });


      }
  }

    }
}

At this point, we've implemented the CreateTodoAsync and GetAllAsync methods in the TodoController class. These methods allow us to create new Todo items and retrieve all Todo items from the database. Let's try to run the application and see if everything is working fine.

Run the application by running the following command:

dotnet run

If you see the following output, it means your application is running successfully:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5086
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
      Content root path: E:\Todo\TodoAPI4

While we'll be using Postman within Visual Studio Code for making API requests, it's worth noting that .NET 8 includes a built-in Swagger UI. This feature allows us to interact with our API endpoints directly from a web browser. To access the Swagger UI, open your browser and navigate to https://localhost:5086/swagger/index.html. You should see a page similar to the one below:

This indicates that we've made significant progress. We've created an API that can create and retrieve Todo items. Let's test this by attempting to create a new Todo item using our API.

Open Postman and create a new POST request with the following URL: https://localhost:5086/api/todo. Set the request body to the following JSON object:

{
    "title": "Learn ASP.NET Core",
    "description": "Learn how to build web applications with ASP.NET Core",
    "dueDate": "2022-12-31T00:00:00",
    "priority": 5
}

Upon executing this request, you may encounter an error. This is because we haven't yet added our connection string to the appsettings.json file. Let's rectify this.

Note: The error above is due to the absence of a connection string in the appsettings.json file. Let's add the connection string to the appsettings.json file.

Before we do that, let's setup or SQL Server Database. First Open your SQL Server Management Studio and you should see the below screen:

To connect to the SQL Server, where is says Server Name you can type localhost or . and click on the Connect button.

After connecting to the SQL Server, you will see the following screen:

Now go to your appsettings.json file and add the following connection string:

//appsettings.json
{
  "DbSettings": {
    "ConnectionString": "Server=localhost;Database=TodoAPIDb;  Integrated Security=true;  TrustServerCertificate=true;"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    },
    "AllowedHosts": "*"
  }
}

Let me explain the connection string above:

• Server: This is the server name where the database is hosted. In this case, we're using localhost to connect to the local SQL Server instance.
• Database: This is the name of the database we want to connect to. We've set it to TodoAPIDb.
• Integrated Security: This parameter specifies that we're using Windows authentication to connect to the database.
• TrustServerCertificate: This parameter specifies that we trust the server certificate when connecting to the database.

Now we need to register our Service and Iservices in the Program.cs file.

Add the service to the Program.cs file:

// Program.cs

// ...

builder.Services.AddScoped<ITodoServices, TodoServices>();

// ...

Step 13: Implement Migrations and Update the Database

Migrations in Entity Framework Core provide a mechanism to keep the database schema in sync with the application's data model. They generate SQL scripts that can be applied to the database to reflect changes in the data model, eliminating the need for manual database schema updates.

To create a migration, ensure you're in the root directory of your project and run the following command in the terminal:

dotnet ef migrations add InitialCreate

Upon successful execution, you'll see an output similar to the following:

dotnet ef migrations add InitialCreate
Build started...
Build succeeded.
Done. To undo this action, use 'ef migrations remove'

This command generates a new migration named InitialCreate, which contains SQL scripts derived from the changes in our data model. A new folder named Migrations will appear in your project directory.

To apply the migration and update the database, execute the following command:

dotnet ef database update

You might encounter an error like this:

  at Microsoft.EntityFrameworkCore.Design.OperationExecutor.UpdateDatabase.<>c__DisplayClass0_0.<.ctor>b__0()
   at Microsoft.EntityFrameworkCore.Design.OperationExecutor.OperationBase.Execute(Action action)
Only the invariant culture is supported in globalization-invariant mode. See https://aka.ms/GlobalizationInvariantMode for more information. (Parameter 'name')
en-us is an invalid culture identifier.

This error indicates that the en-us culture is not supported in globalization-invariant mode. To resolve this, open the TodoAPI.csproj file and change <InvariantGlobalization>true</InvariantGlobalization> to <InvariantGlobalization>false</InvariantGlobalization>.

After making this change, run the dotnet ef database update command again. If the migration is successful, you'll see an output similar to the following:

Build started...
Build succeeded.
Applying migration '20240518180222_InitialCreate'.
Done.

This indicates that the migration has been applied successfully, and the database has been updated with the necessary schema changes.

Congratulations! You've successfully created a migration and updated the database schema. Now, let's test our API by creating a new Todo item using Postman.

Step 14: Verify Your API with Postman

Before we can interact with our API, we need to ensure that our application is up and running. Start the application by executing the following command in the terminal:

dotnet run

With the application running, we can now use Postman to send requests to our API. Let's create a new Todo item:

1. Open Postman and create a new request.
2. Set the request method to POST.
3. Enter the following URL: https://localhost:5086/api/todo.
4. In the Headers tab, set the Content-Type to application/json.
5. In the Body tab, select raw and enter the following JSON object:

{
    "title": "Learn ASP.NET Core",
    "description": "Learn how to build web applications with ASP.NET Core",
    "dueDate": "2022-12-31T00:00:00",
    "priority": 5
}

6. Click on the Send button to execute the request.

If the request is successful, you'll receive a response similar to the one below:

{
    "message": "Todo item successfully created"
}

The image below illustrates the successful creation of a new Todo item using Postman:

Now that we've successfully created a new Todo item, let's retrieve all Todo items from the database using our API.

Step 15: Retrieve All Todo Items

To retrieve all Todo items from the database, follow these steps:

1. Open Postman and create a new request.

2. Set the request method to GET.

3. Enter the following URL: https://localhost:5086/api/todo.

4. Click on the Send button to execute the request.

If the request is successful, you'll receive a response similar to the one below:

   {
    "message": "Successfully retrieved all blog posts",
    "data": [
        {
            "id": "e9898d1b-9ad3-4482-ad65-08dc77664fab",
            "title": "string",
            "description": "string",
            "isComplete": false,
            "dueDate": "2024-05-18T16:52:22.054Z",
            "priority": 5,
            "createdAt": "2024-05-18T18:14:08.1755565+00:00",
            "updatedAt": "0001-01-01T00:00:00"
        }
    ]
}

The image below illustrates the successful retrieval of all Todo items using Postman:

Congratulations! You've successfully created an API that can create and retrieve Todo items. This marks the completion of our Todo API project. You've learned how to set up a .NET Core project, define models, create a database context, implement a service layer, and create API endpoints. You've also learned how to use Postman to interact with your API and test its functionality.

Now let's move on to create the GetByIdAsync, UpdateTodoAsync, and DeleteTodoAsync methods in the TodoServices class and TodoController class.

Step 16: Implement the GetByIdAsync Method

The GetByIdAsync method retrieves a specific Todo item by its Id. We'll implement this method in both the TodoServices and TodoController classes.

The TodoServices Class

In the TodoServices class, add the following code to the GetByIdAsync method:

// Services/TodoServices.cs

public async Task<Todo> GetByIdAsync(Guid id)
{
    var todo = await _context.Todos.FindAsync(id);
    if (todo == null)
    {
        throw new KeyNotFoundException($"No Todo item with Id {id} found.");
    }
    return todo;
}

This method uses Entity Framework Core's FindAsync method to fetch a Todo item by its Id. If no Todo item is found, it throws a KeyNotFoundException with a descriptive error message.

The TodoController Class

In the TodoController class, add the following code to the GetByIdAsync method:

// Controllers/TodoController.cs

[HttpGet("{id:guid}")]
public async Task<IActionResult> GetByIdAsync(Guid id)
{
    try
    {
        var todo = await _todoServices.GetByIdAsync(id);
        if (todo == null)
        {
            return NotFound(new { message = $"No Todo item with Id {id} found." });
        }
        return Ok(new { message = $"Successfully retrieved Todo item with Id {id}.", data = todo });
    }
    catch (Exception ex)
    {
        return StatusCode(500, new { message = $"An error occurred while retrieving the Todo item with Id {id}.", error = ex.Message });
    }
}

This method calls the GetByIdAsync method from the ITodoServices interface to fetch a Todo item by its Id. If a Todo item is retrieved successfully, it returns an Ok response with a success message and the Todo item. If an error occurs during the retrieval process, it returns a 500 Internal Server Error response with an error message.

Step 17: Implement the UpdateTodoAsync Method

The UpdateTodoAsync method in the TodoServices class modifies an existing Todo item in the database. Let's implement this method now.

Navigate to the TodoServices class and add the following code to the UpdateTodoAsync method:

// Services/TodoServices.cs

// ...

 public async Task UpdateTodoAsync(Guid id, UpdateTodoRequest request)
 {
     try
     {
         var todo = await _context.Todos.FindAsync(id);
         if (todo == null)
         {
             throw new Exception($"Todo item with id {id} not found.");
         }

         if (request.Title != null)
         {
             todo.Title = request.Title;
         }

         if (request.Description != null)
         {
             todo.Description = request.Description;
         }

         if (request.IsComplete != null)
         {
             todo.IsComplete = request.IsComplete.Value;
         }

         if (request.DueDate != null)
         {
             todo.DueDate = request.DueDate.Value;
         }

         if (request.Priority != null)
         {
             todo.Priority = request.Priority.Value;
         }

         todo.UpdatedAt = DateTime.Now;

         await _context.SaveChangesAsync();
     }
     catch (Exception ex)
     {
         _logger.LogError(ex, $"An error occurred while updating the todo item with id {id}.");
         throw;
     }
 }

// ...

Here's a breakdown of the UpdateTodoAsync method:

• Retrieving a Specific Todo Item: We use Entity Framework Core's FindAsync method to fetch a Todo item by its Id.

• Updating the Todo Item: We update the Todo item properties based on the values provided in the UpdateTodoRequest object.

• Error Handling: If no Todo item is found with the specified Id, we throw an exception with a descriptive error message.

Now let's implement the UpdateTodoAsync method in the TodoController class. This method will modify an existing Todo item in the database.

Navigate to the TodoController class and add the following code to the UpdateTodoAsync method:

// Controllers/TodoController.cs

// ... 
   [HttpPut("{id:guid}")]

   public async Task<IActionResult> UpdateTodoAsync(Guid id, UpdateTodoRequest request)
   {

       if (!ModelState.IsValid)
       {
           return BadRequest(ModelState);
       }

       try
       {

           var todo = await _todoServices.GetByIdAsync(id);
           if (todo == null)
           {
               return NotFound(new { message = $"Todo Item  with id {id} not found" });
           }

           await _todoServices.UpdateTodoAsync(id, request);
           return Ok(new { message = $" Todo Item  with id {id} successfully updated" });

       }
       catch (Exception ex)
       {
           return StatusCode(500, new { message = $"An error occurred while updating blog post with id {id}", error = ex.Message });


       }


   }

// ...

Here's a breakdown of the UpdateTodoAsync method:

• Model Validation: We check if the request model is valid using ModelState.IsValid. If the model is not valid, we return a BadRequest response with the model state errors.

• Retrieving a Specific Todo Item: We call the GetByIdAsync method from the ITodoServices interface to fetch a Todo item by its Id.

• Updating the Todo Item: If the Todo item is found, we call the UpdateTodoAsync method from the ITodoServices interface to update the Todo item.

• Success Response: If the Todo item is updated successfully, we return an Ok response with a success message.

• Error Handling: If an error occurs during the update process, we return a 500 Internal Server Error response with an error message.

Step 18: Implement the DeleteTodoAsync Method

The DeleteTodoAsync method in the TodoServices class removes a Todo item from the database. Let's implement this method now.

Navigate to the TodoServices class and add the following code to the DeleteTodoAsync method:

// Services/TodoServices.cs

// ...


 public async Task DeleteTodoAsync(Guid id)
 {

     var todo = await _context.Todos.FindAsync(id);
     if(todo != null)
     {
          _context.Todos.Remove(todo);
         await _context.SaveChangesAsync();

     }
     else
     {
         throw new Exception($"No  item found with the id {id}");
     }


 }

// ...

Here's a breakdown of the DeleteTodoAsync method:

• Retrieving a Specific Todo Item: We use Entity Framework Core's FindAsync method to fetch a Todo item by its Id.

• Removing the Todo Item: If the Todo item is found, we remove it from the Todos DbSet in our context and save the changes asynchronously.

• Error Handling: If no Todo item is found with the specified Id, we throw an exception with a descriptive error message.

Now let's implement the DeleteTodoAsync method in the TodoController class. This method will remove a Todo item from the database.

Navigate to the TodoController class and add the following code to the DeleteTodoAsync method:

// Controllers/TodoController.cs

// ...

 [HttpDelete("{id:guid}")]
 public async Task<IActionResult> DeleteTodoAsync(Guid id)
 {
     try
     {
         await _todoServices.DeleteTodoAsync(id);
         return Ok(new { message = $"Todo  with id {id} successfully deleted" });

     }
     catch (Exception ex)
     {
         return StatusCode(500, new { message = $"An error occurred while deleting Todo Item  with id {id}", error = ex.Message });

     }
 }



// ...

Here's a breakdown of the DeleteTodoAsync method:

• Removing the Todo Item: We call the DeleteTodoAsync method from the ITodoServices interface to remove a Todo item by its Id.

• Success Response: If the Todo item is deleted successfully, we return an Ok response with a success message.

• Error Handling: If an error occurs during the deletion process, we return a 500 Internal Server Error response with an error message.

Now your TodoServices class should look like this:

// Services/TodoServices.cs

using AutoMapper;
using Microsoft.EntityFrameworkCore;
using TodoAPI.AppDataContext;
using TodoAPI.Contracts;
using TodoAPI.Interface;
using TodoAPI.Models;

namespace TodoAPI.Services
{
    public class TodoServices : ITodoServices
    {
        private readonly TodoDbContext _context;
        private readonly ILogger<TodoServices> _logger;
        private readonly IMapper _mapper;

        public TodoServices(TodoDbContext context, ILogger<TodoServices> logger, IMapper mapper)
        {
            _context = context;
            _logger = logger;
            _mapper = mapper;
        }




        //  Create Todo for it to be saved in the datbase 

        public async Task CreateTodoAsync(CreateTodoRequest request)
        {
            try
            {
                var todo = _mapper.Map<Todo>(request);
                todo.CreatedAt = DateTime.Now;
                _context.Todos.Add(todo);
                await _context.SaveChangesAsync();
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, "An error occurred while creating the todo item.");
                throw new Exception("An error occurred while creating the todo item.");
            }
        }


        public async Task<Todo> GetByIdAsync(Guid id)
        {
            var todo = await _context.Todos.FindAsync(id);
            if (todo == null)
            {
                throw new Exception($" No Items with {id} found ");
            }
            return todo;
        }

        public async Task UpdateTodoAsync(Guid id, UpdateTodoRequest request)
        {
            try
            {
                var todo = await _context.Todos.FindAsync(id);
                if (todo == null)
                {
                    throw new Exception($"Todo item with id {id} not found.");
                }

                if (request.Title != null)
                {
                    todo.Title = request.Title;
                }

                if (request.Description != null)
                {
                    todo.Description = request.Description;
                }

                if (request.IsComplete != null)
                {
                    todo.IsComplete = request.IsComplete.Value;
                }

                if (request.DueDate != null)
                {
                    todo.DueDate = request.DueDate.Value;
                }

                if (request.Priority != null)
                {
                    todo.Priority = request.Priority.Value;
                }

                todo.UpdatedAt = DateTime.Now;

                await _context.SaveChangesAsync();
            }
            catch (Exception ex)
            {
                _logger.LogError(ex, $"An error occurred while updating the todo item with id {id}.");
                throw;
            }
        }
        public async Task<IEnumerable<Todo>> GetAllAsync()
        {
            var todo = await _context.Todos.ToListAsync();
            if (todo == null)
            {
                throw new Exception(" No Todo items found");
            }
            return todo;

        }
        public async Task DeleteTodoAsync(Guid id)
        {

            var todo = await _context.Todos.FindAsync(id);
            if (todo != null)
            {
                _context.Todos.Remove(todo);
                await _context.SaveChangesAsync();

            }
            else
            {
                throw new Exception($"No  item found with the id {id}");
            }


        }




    }
}

Now your TodoController class should look like this:

using Microsoft.AspNetCore.Mvc;
using TodoAPI.Contracts;
using TodoAPI.Interface;

namespace TodoAPI.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class TodoController : ControllerBase
    {
        private readonly ITodoServices _todoServices;

        public TodoController(ITodoServices todoServices)
        {
            _todoServices = todoServices;
        }



        // Creating new Todo Item
        [HttpPost]
        public async Task<IActionResult> CreateTodoAsync(CreateTodoRequest request)
        {
            if (!ModelState.IsValid)
            {
                return BadRequest(ModelState);
            }


            try
            {

                await _todoServices.CreateTodoAsync(request);
                return Ok(new { message = "Blog post successfully created" });

            }
            catch (Exception ex)
            {
                return StatusCode(500, new { message = "An error occurred while creating the  crating Todo Item", error = ex.Message });

            }
        }

        // Get all Todo Items

        [HttpGet]
        public async Task<IActionResult> GetAllAsync()
        {
            try
            {
                var todo = await _todoServices.GetAllAsync();
                if (todo == null || !todo.Any())
                {
                    return Ok(new { message = "No Todo Items  found" });
                }
                return Ok(new { message = "Successfully retrieved all blog posts", data = todo });

            }
            catch (Exception ex)
            {
                return StatusCode(500, new { message = "An error occurred while retrieving all Tood it posts", error = ex.Message });


            }
        }

        [HttpGet("{id:guid}")]
        public async Task<IActionResult> GetByIdAsync(Guid id)
        {
            try
            {

                var todo = await _todoServices.GetByIdAsync(id);
                if (todo == null)
                {
                    return NotFound(new { message = $"Now Todo item with id {id} not found" });

                }
                return Ok(new { message = $"Successfully retrieved  todo item with id {id}", data = todo });

            }
            catch (Exception ex)
            {
                return StatusCode(500, new { message = $"An error occurred while retrieving   todo item  with id {id}", error = ex.Message });

            }
        }



        [HttpPut("{id:guid}")]

        public async Task<IActionResult> UpdateTodoAsync(Guid id, UpdateTodoRequest request)
        {

            if (!ModelState.IsValid)
            {
                return BadRequest(ModelState);
            }

            try
            {

                var todo = await _todoServices.GetByIdAsync(id);
                if (todo == null)
                {
                    return NotFound(new { message = $"Todo Item  with id {id} not found" });
                }

                await _todoServices.UpdateTodoAsync(id, request);
                return Ok(new { message = $" Todo Item  with id {id} successfully updated" });

            }
            catch (Exception ex)
            {
                return StatusCode(500, new { message = $"An error occurred while updating blog post with id {id}", error = ex.Message });


            }


        }


        [HttpDelete("{id:guid}")]
        public async Task<IActionResult> DeleteTodoAsync(Guid id)
        {
            try
            {
                await _todoServices.DeleteTodoAsync(id);
                return Ok(new { message = $"Todo  with id {id} successfully deleted" });

            }
            catch (Exception ex)
            {
                return StatusCode(500, new { message = $"An error occurred while deleting Todo Item  with id {id}", error = ex.Message });

            }
        }


    }
}

Now that we've implemented the GetByIdAsync, UpdateTodoAsync, and DeleteTodoAsync methods in the TodoServices and TodoController classes, we can test our API to ensure that everything is working as expected.

Step 19: Test Your API Endpoints with Postman

With our application up and running, we can now test all our API endpoints. We'll create new Todo items, retrieve all Todo items, fetch a specific Todo item by its Id, update a Todo item, and delete a Todo item using Postman. Let's start by creating three new Todo items.

Note that we'll be creating these Todo items one at a time, not all at once. Follow these steps for each Todo item:

1. Open Postman and create a new request.
2. Set the request method to POST.
3. Enter the following URL: http://localhost:5086/api/todo.
4. In the Headers tab, set the Content-Type to application/json.
5. In the Body tab, select raw and enter one of the following JSON objects:

For the first Todo item:

{
    "title": "Learn ASP.NET Core",
    "description": "Learn how to build web applications with ASP.NET Core",
    "dueDate": "2022-12-31T00:00:00",
    "priority": 2
}

For the second Todo item:

{
    "title": "Learn C#",
    "description": "Learn how to build web applications with C#",
    "dueDate": "2022-12-31T00:00:00",
    "priority": 3
}

For the third Todo item:

{
    "title": "Learn SQL",
    "description": "Learn how to build web applications with SQL",
    "dueDate": "2022-12-31T00:00:00",
    "priority": 1
}

6. Click on the Send button to execute the request for each Todo item.

If each request is successful, you'll receive a response similar to the one below:

{
    "message": "Todo item successfully created"
}

This indicates that the Todo item has been successfully created. Repeat the steps for each Todo item.

How to Retrieve All Todo Items

To fetch all Todo items from the database, follow these steps:

1. Launch Postman and initiate a new request.
2. Set the HTTP method to GET.
3. Input the following URL: http://localhost:5086/api/todo.
4. Click the Send button to execute the request.

The image below demonstrates a successful retrieval of all Todo items using Postman:

How to Fetch a Specific Todo Item by Id

To retrieve a specific Todo item using its Id, follow these steps:

1. Launch Postman and initiate a new request.
2. Set the HTTP method to GET.
3. Input the following URL: http://localhost:5086/api/todo/{id}, replacing {id} with the Id of the Todo item you wish to retrieve. For example, http://localhost:5086/api/todo/e9898d1b-9ad3-4482-ad65-08dc77664fab.
4. Click the Send button to execute the request.

Upon successful execution, you'll receive a response similar to the one below:

{
    "message": "Successfully retrieved  todo item with id e9898d1b-9ad3-4482-ad65-08dc77664fab",
    "data": {
        "id": "e9898d1b-9ad3-4482-ad65-08dc77664fab",
        "title": "string",
        "description": "string",
        "isComplete": false,
        "dueDate": "2024-05-18T16:52:22.054",
        "priority": 5,
        "createdAt": "2024-05-18T18:14:08.1755565",
        "updatedAt": "0001-01-01T00:00:00"
    }
}

The image below demonstrates the successful retrieval of a specific Todo item using Postman:

)

How to Update a Todo Item

In our Todo model, we have a property isComplete which is initially set to false when a Todo item is created. This property is used to indicate whether a task has been completed or not. To mark a task as complete, we need to update this property to true. Note that we can only update one Todo item at a time, and we identify the item to update by its Id.

Let's fetch all the Todo items, select one and update it by setting the isComplete property to true.

Follow these steps to update a Todo item:

1. Launch Postman and initiate a new request.
2. Set the HTTP method to PUT.
3. Input the following URL: http://localhost:5086/api/todo/{id}, replacing {id} with the Id of the Todo item you wish to update. For example, http://localhost:5086/api/todo/e9898d1b-9ad3-4482-ad65-08dc77664fab.
4. In the Headers tab, set the Content-Type to application/json.
5. In the Body tab, select raw and enter the following JSON object:

{
    "id": "21ebe2c2-79c0-45d4-4139-08dc789e3eb2",
    "title": "Learn C#",
    "description": "Learn how to build web applications with C#",
    "isComplete": true, // Set the isComplete to true
    "dueDate": "2022-12-31T00:00:00",
    "priority": 3,
    "createdAt": "2024-05-20T07:27:39.3730049+00:00",
    "updatedAt": "0001-01-01T00:00:00"
}

6. Click the Send button to execute the request.

Upon successful execution, you'll receive a response similar to the one below:

{
    "message": "Todo Item with id 21ebe2c2-79c0-45d4-4139-08dc789e3eb2 successfully updated"
}

The image below demonstrates the successful update of a Todo item using Postman:

Note: The isComplete property of the Todo item has been updated to true. Now, when you fetch all Todo items from the database, you will see the isComplete property is true for the updated Todo item.

Now let's see how to delete a Todo item from the database.

How to Delete a Todo Item

To remove a Todo item from the database, follow these steps:

1. Open Postman and create a new request.
2. Set the HTTP method to DELETE.
3. Enter the following URL: http://localhost:5086/api/todo/{id}, replacing {id} with the Id of the Todo item you intend to remove. For instance, http://localhost:5086/api/todo/e9898d1b-9ad3-4482-ad65-08dc77664fab.
4. Click the Send button to execute the request.

If the request is successful, you'll receive a response similar to the one below:

{
    "message": "Todo item with id 21ebe2c2-79c0-45d4-4139-08dc789e3eb2 successfully deleted"
}

The image below illustrates the successful deletion of a Todo item using Postman:

Well done! You've successfully implemented the GetByIdAsync, UpdateTodoAsync, and DeleteTodoAsync methods in the TodoServices and TodoController classes. You've also verified your API endpoints using Postman to ensure they're functioning as expected. You can

Source Code

The entire source code for this project is readily available in the TodoAPI GitHub repository. I encourage you to delve into the codebase, tinker with various functionalities, and bolster your proficiency in crafting APIs using ASP.NET Core 8.

Conclusion

In this guide, we've journeyed through the process of constructing a robust Todo API using the power of ASP.NET Core 8. We initiated our project from scratch, meticulously defining the essential models that form the backbone of our Todo application.

We then created a database context, a crucial step that facilitated our interaction with the database. To further streamline this interaction, we implemented a service layer, effectively abstracting the complexities of direct database operations.

Next, we created our API endpoints. These endpoints serve as the gateways for creating, retrieving, updating, and deleting Todo items, thereby providing comprehensive functionality to our application.

The final stage of our journey involved rigorous testing of our API using Postman. This ensured that our application was not only built as per our design but also functioned as expected, providing a reliable and efficient service.

As we conclude, it's important to remember that the knowledge gained here forms a solid foundation for building more complex and feature-rich APIs. The journey of learning and exploration doesn't end here – it's just the beginning. Happy coding!

As an extra, the application will have dark mode support that respects the users' system preferences.

The application will be able to create, read, update and delete (CRUD) tasks as well as the ability to view a given task.

You'll build this application using Appwrite as a backend, React on the frontend, Typescript for type safety and Tailwind CSS for styling.

Table of Contents

• Prerequisites
• What is Appwrite?
• How to Set Up the Appwrite Backend
• How to Set up the React Frontend
• How to Connect to the Appwrite Project
• How to Build the Task Manager Application
  • How to Set up Routing with React Router V6
  • How to Create the Form Component
  • How to Set up Form to Create Task
  • How to Make the Tasks Editable
  • How to Enable Viewing of Tasks
  • How to Auto Generate Descriptions with Vercel's AI SDK
  • Voice-enable the Application with the React Speech Recognition Package
  • How to Add Search Functionality to the Application
  • How to Add Ability to Sort Tasks via Due Date and Priority
  • Bonus: Add Dark Mode Support
• Notes
• Limitations

Prerequisites

You will need the following to be able to build along with this article:

• Basic programming knowledge
• Basic understanding of React, Typescript and Tailwind
• An Appwrite account
• And a text editor to code along

What is Appwrite?

Appwrite is an open source Backend-as-a-Service (BaaS) platform. A BaaS is a cloud service that packages backend tasks that are typically needed for most applications.

Appwrite offers both a managed database, authentication, functions and storage services and the ability to self-host the entire platform on your own.

Appwrite recently announced a host of new features that makes developers building on their platform lives more straightforward. You can read on that here.

How to Set Up the Appwrite Backend

Before starting to build the application and interacting with Appwrite, you'll need an Appwrite account and to set up the project.

Once you have the account ready, you will need to create an organization, then create a project within that organization. You can name the project "Tasks App" or any other name you see fit.

Note: Appwrite cloud restricts you to one organization per account on the hobby/free plan. If you already had an organization, you can go straight to creating a project within your existing organization.

In your Tasks App project, add a web platform and follow the prompts. For the hostname, add "localhost" for now. This is to allow the frontend to bypass CORS when interacting with the Appwrite backend.

A picture of the Appwrite Console showing the "Add a platform" section

Copy the installation instructions as you complete setting up the web platform for the project. Keep these safe, you will need them when setting up the frontend.

You should now be in the Appwrite cloud console. Click on the "Databases" on the left sidebar. Then click on the pink "Create database" button. Name your database and leave the autogenerated ID as is.

Now, click on the "Create collection" button, name your collection "tasks" and leave the autogenerated ID as is. Now, click on the grey "Create attribute" button as shown below:

A picture of the Appwrite Console showing the "Create attribute" button

Add the following attributes:

• title of type String, give it a size of 49 and make it required
• description of type String, give it a size of 200
• due_date of type Datetime, make it required
• done of type Boolean, give it a default of False
• priority of type String, give it a size of 10

Finally, you need to set permissions in order for your React frontend to interact with Appwrite services. In this case, allow any one to have access. This is not ideal for production and you can read more about Appwrite permissions here.

Go to the console, click on databases, then your task database and then your tasks collection, then click on settings and scroll down to permissions. Add permissions for "Any" role and give them full CRUD access.

You are now ready to start setting up the frontend and to connect it to the Appwrite project you just completed prepping.

How to Set up the React Frontend

Open your text editor to your preferred location. Then open the integrated terminal and run the following command to create a Vite-based application:

//taskwrite is the name of the application
npm create vite@latest taskwrite

Choose React and then plain Typescript when prompted. This will create a React application with Typescript already set up for you.

Change folders into the newly created "taskwrite" one by running cd taskwrite from the terminal. Run the following command in the same terminal window to add Tailwind to the application:

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

Then in your tailwind.config.js file which is in the root of the Taskwrite application, replace the "content" key with content: ["./index.html", "./src/**/*.{js,ts,jsx,tsx}"],. The file should look like this:

/** @type {import('tailwindcss').Config} */
export default {
    content: ["./index.html", "./src/**/*.{js,ts,jsx,tsx}"],
    theme: {
        extend: {},
    },
    plugins: [],
};

This tells Tailwind that it should look for its classes in the index.html file at the root and in files within the src folder that end with either .js, .ts, .jsx or .tsx extensions.

Then open the src folder and delete the "App.css" file. Open the index.css file and replace its contents with the following:

@import url('https://fonts.googleapis.com/css2?family=Inter:wght@100..900&family=Quicksand:wght@300..700&display=swap');
@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
    :root{
        --base-bg: #ffffff;
        --btn-bg-primary: #be185d;
        --btn-bg-primary-hover: #9d174d;
        --btn-icon-main: #1e293b;
        --btn-bg-ok: #4ade80;
        --btn-bg-light-ok: #bbf7d0;
        --btn-bg-light: #e5e7eb;
        --low-priority: #facc15;
        --medium-priority: #fb923c;
        --high-priority: #f87171;
        --text-error: #dc2626;
        --text-ok: #16a34a;
        --text-main: #262626;
        --border-container: #9ca3af;
        --border-input: #1e293b;
        --border-error: #dc2626;
    }

    body{
        background-color: var(--base-bg);
        color: var(--text-main);    
    }

    #date::-webkit-calendar-picker-indicator {
        background-color: var(--btn-bg-light); 
    }
}

This adds some custom css variables to the application. The variables map to Tailwind colors.

Next, paste the following into the tailwind.config.js at the root of the application:

/** @type {import('tailwindcss').Config} */
export default {
    content: ["./index.html", "./src/**/*.{js,ts,jsx,tsx}"],
    theme: {
        extend: {
            textColor: {
                error: "var(--text-error)",
                ok: "var(--text-ok)",
                main: "var(--text-main)",
                iconColor: "var(--btn-icon-main)",
            },
            backgroundColor: {
                base: "var(--base-bg)",
                primary: "var(--btn-bg-primary)",
                primaryHover: "var(--btn-bg-primary-hover)",
                ok: "var(--btn-bg-ok)",
                lightOk: "var(--btn-bg-light-ok)",
                light: "var(--btn-bg-light)",
                lowPriority: "var(--low-priority)",
                mediumPriority: "var(--medium-priority)",
                highPriority: "var(--high-priority)",
            },
            borderColor: {
                container: "var(--border-container)",
                input: "var(--border-input)",
                error: "var(--border-error)",
            },
        },
    },
    plugins: [],
};

This ties the CSS variables to the tailwind config and makes them available to use in our application.

Now Taskwrite is set up with React, Typescript and Tailwind.

How to Connect to the Appwrite Project

Firstly, you need to add the Appwrite dependency to the React application. Run the following command in the terminal window to do that: npm i appwrite.

Next thing is to set up the Appwrite keys we need as environment variables. In the .gitignore file at the root of the application, add *.env at the top of the file then save. This will ensure that the .env file you'll create is not added to version control.

Now, create a .env file at the root of the React application and paste the following variables in it:

//replace the right hand side of the equal sign with the correct values from your Appwrite project.
VITE_APPWRITE_URL=YOUR-APPWRITE-API-ENDPOINT
VITE_APPWRITE_PROJ_ID=YOUR-APPWRITE-PROJECT-ID

You can get the necessary values in your Appwrite console. Click on the settings tab at the bottom of the left sidebar and copy API credentials.

Next, create a utils folder in the src folder of the React application. Add a file called appwrite.ts within it and paste the following config information:

import { Client, Databases } from "appwrite";

export const client = new Client();

client
    .setEndpoint(import.meta.env.VITE_APPWRITE_URL)
    .setProject(import.meta.env.VITE_APPWRITE_PROJ_ID);

export const databases = new Databases(client);

export { ID } from "appwrite";

You are ready to test that the React application is connected to the Appwrite project. Replace everything in the App.tsx file within the src folder with the following code:

import { client } from "./utils/appwrite";

const App = () => {
    console.log("Appwrite", client);
    return <div className="text-purple-500 text-center font-bold text-      5xl">App</div>;
};

export default App;

Then open an integrated terminal window and run the following command: npm run dev. This will run your React application at this URL: http://localhost:5173/. Open the URL in a browser window and open the browser console.

You should see a large purple text "App" in the center of the screen and the Appwrite client logged in the console like so:

The web app running in the browser

Now you need to grab the database ID and the collection ID from the Appwrite console. Click on the databases tab on the left sidebar, hover on the database ID value and click to copy it.

Go back to your .env file and add an entry like so:

//replace the right hand side of the equal sign with the correct values from your Appwrite project.
VITE_APPWRITE_URL=YOUR-APPWRITE-API-ENDPOINT
VITE_APPWRITE_PROJ_ID=YOUR-APPWRITE-PROJECT-ID
//new entry below
VITE_APPWRITE_DB_ID=YOUR-APPWRITE-DB-ID

Lastly, go back to the console and click through the database to get to the collections. Hover and copy collection ID like before, then add it just below the database ID in your env file like so:

VITE_APPWRITE_DB_ID=YOUR-APPWRITE-DB-ID
VITE_APPWRITE_COLLECTION_ID=YOUR-APPWRITE-COLLECTION-ID

With that, the set up part of building Taskwrite is complete.

How to Build the Task Manager Application

To make it easier to work with Typescript, you will need to add interfaces that correspond with the shape of the Appwrite database response.

In your src folder, create a folder called models and in it, create a file called interface.ts. Paste the following in the file:

import { Models } from "appwrite";

export interface IPayload {
    title: string;
    description: string;
    due_date: Date;
    priority?: string;
    done?: boolean;
}

export interface ITask extends Models.Document {
    title: string;
    description: string;
    due_date: Date;
    priority?: string;
    done: boolean;
}

Here, you are defining an interface called "IPayload" with the same attributes as the task we defined in the Appwrite project. Then you are defining another interface called "ITask" that extends the built in base Model from Appwrite.

This means that ITask has both the attributes of the task we defined before and the built in base attributes that Appwrite collections come with.

Next, in your utils folder add a file called db.ts and paste the following in it:

import { ID, databases } from "./appwrite";
import { IPayload } from "../models/interface";

const dbID: string = import.meta.env.VITE_APPWRITE_DB_ID;
const collectionID: string = import.meta.env.VITE_APPWRITE_COLLECTION_ID;

const createDocument = async (payload: IPayload) => {
    const res = await databases.createDocument(dbID, collectionID, ID.unique(), {
        ...payload,
    });

    return res;
};

const readDocuments = async () => {
    const res = await databases.listDocuments(dbID, collectionID);

    return res;
};

const updateDocument = async (payload: IPayload, id: string) => {
    const res = await databases.updateDocument(dbID, collectionID, id, {
        ...payload,
    });

    return res;
};
const deleteDocument = async (id: string) => {
    const res = await databases.deleteDocument(dbID, collectionID, id);

    return res;
};

export { createDocument, readDocuments, updateDocument, deleteDocument };

This file defines four functions corresponding with the CRUD operations. The naming of the functions map to which operation it performs. For all functions, you pass the collection and database IDs so that Appwrite knows which resources to operate on.

To create a task on the Appwrite database, you pass an object with the shape of a task to the function and ask it to create a unique ID for each new task it creates.

To update a task, you pass it a task object similar to create but we also pass it the unique ID of the task to be updated.

To read all tasks from the Appwrite, you call the "listDocuments" function and to delete a task you pass the ID corresponding to the task to be deleted.

How to Set Up Routing with React Router V6

The Taskwrite application will have two routes and a navigation menu to help with that. To add navigation, open an integrated terminal and run the following command to install the React Router library: npm i react-router-dom.

Now, go to the main.tsx file in the src folder and paste the following in it:

import React from "react";
import ReactDOM from "react-dom/client";
import { BrowserRouter } from "react-router-dom";
import App from "./App.tsx";
import "./index.css";

ReactDOM.createRoot(document.getElementById("root")!).render(
    <React.StrictMode>
        <BrowserRouter>
            <App />
        </BrowserRouter>
    </React.StrictMode>
);

Then go to the App.tsx file in src folder and paste the following in it:

import "./index.css";
import { Route, Routes } from "react-router-dom";
import Task from "./routes/Task";
import Index from "./routes/Index";
import Navbar from "./components/Navbar";

function App() {
    return (
        <>
            <Navbar/>
            <Routes>
                <Route path="/" element={<Index />} />
                <Route path="/tasks" element={<Task />} />
            </Routes>
        </>
    );
}

export default App;

You now need to create the referenced component above. In the src folder, create a folder called routes and within it create two files called Index.tsx and Task.tsx.

In Index.tsx, paste the following:

const Index = () => {
    return (
        <main className="container mx-auto">
            <section className="max-w-5xl mx-auto m-12 p-16">
                <h1 className="text-4xl md:text-7xl font-bold text-center py-3 mb-16">
                    AI-enhanced, Voice-enabled, Searchable Task Manager
                </h1>
            </section>
        </main>
    );
};

export default Index;

And in Task.tsx, paste the following:

const Task = () => {
    return (
        <main className="container mx-auto">
            <section className="max-w-5xl mx-auto m-12 p-16">
                <h1 className="text-4xl md:text-7xl font-bold text-center py-3 mb-16">
                    Your Tasks
                </h1>
            </section>
        </main>
    );
};

export default Task;

Now, create a components folder in the src folder and add a file within it called Navbar.tsx. Paste the following in that file:

import { Link, useNavigate } from "react-router-dom";
import { PencilIcon } from "@heroicons/react/24/solid";
import Button from "./Button";

const Navbar = () => {
    const navigate = useNavigate();

    return (
        <nav className="py-4 border-b-2 border-container shadow-md shadow-gray-400 w-full fixed top-0 bg-base">
            <ul className="flex items-center justify-between  w-11/12 mx-auto">
                <Link to="/">
                    <Button
                        content={{
                            text: "Taskwrite",
                            icon: PencilIcon,
                        }}
                        textClasses="font-semibold text-main"
                        iconClasses="text-main"
                    />
                </Link>
                </Link>
                <div className="flex items-center justify-between gap-6">
                    <Link
                        to="/tasks"
                        className="font-semibold hover:scale-105 transition duration-300 ease-in-out"
                    >
                        View Tasks
                    </Link>
                </div>
            </ul>
        </nav>
    );
};

export default Navbar;

This file contains navigation menu that switches between the two pages. You will need to create the Button component referenced above and add the Hero icons package.

In an integrated terminal, run the following to add Hero icons: npm i @heroicons/react . Next, add a new file called Button.tsx in the components folder. Paste the following within that file:

import { ReactNode } from "react";

interface ButtonProps {
    extraBtnClasses?: string;
    textColor?: string;
    handleClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
    title?: string;
    disable?: boolean;
    type?: "button" | "submit" | "reset";
    children: ReactNode;
}

function Button({
    extraBtnClasses,
    textColor,
    handleClick,
    title,
    disable,
    type = "button",
    children,
}: ButtonProps) {
    const handleClickProp = type === "submit" ? undefined : handleClick;

    return (
        <button
            type={type}
            title={title ?? ""}
            onClick={handleClickProp}
            disabled={disable}
            className={`flex gap-2 items-center text-iconColor ${extraBtnClasses} ${
                textColor ?? ""
            } rounded-md px-2 py-1 hover:scale-105 transition duration-300 ease-in-out`}
        >
            {children}
        </button>
    );
}

export default Button;

This file describes a shared button component and defines the props that it will accept.

Go back and fix any import errors and re-run the application by running npm run dev, you should see something like this:

app running with npm run dev command

How to Create the Form Component

Add a new file called AddTask.tsx in the components folder and paste the following into it:

import { useState } from "react";
import Select from "./Select";
import Button from "./Button";

const AddTask = () => {
    const [titleVal, setTitleVal] = useState("");
    const [textAreaVal, setTextAreaVal] = useState("");
    const [dueDate, setDueDate] = useState(new Date());

    const priorityArray = ["low", "medium", "high"];

    const [priority, setPriority] = useState(priorityArray[0]);

    return (
        <form id="form" className="m-8">
            <div className="flex flex-col mb-6">
                <label htmlFor="title">Task Title</label>
                <input
                    type="text"
                    id="title"
                    placeholder="Title of your task"
                    value={titleVal}
                    onChange={(e) => setTitleVal(e.target.value)}
                    className="bg-inherit border rounded-sm p-2 focus:outline-none focus:ring-1 border-input focus:ring-slate-900"
                />
            </div>
            <div className="flex flex-col mb-6">
                <label htmlFor="description" className="mb-1">
                    Task Description
                </label>
                <textarea
                    id="description"
                    placeholder="Describe your task"
                    maxLength={200}
                    value={textAreaVal}
                    onChange={(e) => setTextAreaVal(e.target.value)}
                    className="bg-inherit border rounded-sm p-2 h-32 resize-none focus:outline-none focus:ring-1 border-input focus:ring-slate-900"
                />
            </div>
            <div className="flex flex-col mb-6">
                <label htmlFor="description" className="mb-1">
                    Task Priority
                </label>
                <Select
                    defaultSelectValue={priority}
                    selectOptions={priorityArray}
                    handleSelectChange={(e) => setPriority(e.target.value)}
                />
            </div>
            <div className="flex flex-col mb-6">
                <label htmlFor="description" className="mb-1">
                    Task Due Date
                </label>
                <input
                    type="date"
                    id="date"
                    value={dueDate!.toISOString().split("T")[0]}
                    min={new Date().toISOString().split("T")[0]}
                    onChange={(e) => setDueDate(new Date(e.target.value))}
                    className="bg-inherit border rounded-sm border-input p-2 focus:outline-none focus:ring-1 focus:ring-slate-900 invalid:focus:ring-red-600"
                />
            </div>
            <Button
                type="submit"
                content={{
                    text: "Add Task",
                }}
                extraBtnClasses="bg-pink-700 justify-center text-white font-semibold px-4 py-2 outline-1 hover:bg-pink-800 focus:ring-1 focus:ring-pink-800 w-full"
            />
        </form>
    );
};

export default AddTask;

Now create a new file in components called Select.tsx, paste the following in it:

import { useState } from "react";

interface SelectProps {
    defaultSelectValue: string;
    selectOptions: string[];
    handleSelectChange: (e: React.ChangeEvent<HTMLSelectElement>) => void;
}

const Select = ({
    defaultSelectValue,
    handleSelectChange,
    selectOptions,
}: SelectProps) => {
    const [selectVal, setSelectVal] = useState(defaultSelectValue);
    return (
        <select
            value={selectVal}
            onChange={(e) => {
                setSelectVal(e.target.value);
                handleSelectChange(e);
            }}
            className="bg-inherit border rounded-sm border-input p-2 focus:outline-none focus:ring-1 focus:ring-slate-900 cursor-pointer"
        >
            {selectOptions.map((option) => (
                <option key={option} value={option}>
                    {option.charAt(0).toUpperCase() + option.slice(1)}
                </option>
            ))}
        </select>
    );
};

export default Select;

This defines a Select component and its props. The Select component props are a function for handling change, an array of options and the default value it should display.

Now, import the AddTask component in the Index.tsx file between the h1 tags like so:

import AddTask from "../components/AddTask";

const Index = () => {
    return (
        <main className="container mx-auto">
            <section className="max-w-5xl mx-auto m-12 p-16">
                <h1 className="text-4xl md:text-7xl font-bold text-center py-3 mb-16">
                    AI-enhanced, Voice-enabled, Searchable Task Manager
                </h1>
                <AddTask />
            </section>
        </main>
    );
};

export default Index;

Your application should now display the form:

task app form

How to Set Up Form to Create Task

To make the form functional, you need to hook it up to a submit function that will call the create function defined in the db.ts file.

Additionally, you will need to validate the form to avoid sending bad data and having Appwrite send errors back to the React application.

In the AddTask component file, paste the following code above the return statement and below the setPriority useState:

const [priority, setPriority] = useState(priorityArray[0]);

//paste here
const navigate = useNavigate();

const [isSubmitting, setIsSubmitting] = useState(false);
const [titleValidationError, setTitleValidationError] = useState("");

    const handleTitleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
        setTitleVal(e.target.value);

        if (e.target.value.trim() !== "") {
            setTitleValidationError("");
        }
    };

    const handleSubmitTask = async (e: React.FormEvent<HTMLFormElement>) => {
        e.preventDefault();
        setIsSubmitting(true);

        try {
            if (!titleVal) {
                setTitleValidationError("Please provide at least a title for the task");
                setTimeout(() => setTitleValidationError(""), 2000);
                setIsSubmitting(false);
                return;
            }

            if (titleVal.length > 49) {
                setTitleValidationError(
                    "Title too long. It can only be 49 characters long"
                );
                setTimeout(() => setTitleValidationError(""), 2000);
                setIsSubmitting(false);
                return;
            }

            const payload: IPayload = {
                title: titleVal,
                description: textAreaVal,
                due_date: dueDate,
                priority: priority,
            };

            await createDocument(payload);

            // reset form
            setTitleVal("");
            setTextAreaVal("");
            setDueDate(new Date());
            setPriority(priorityArray[0]);
            setTitleValidationError("");
            setIsSubmitting(false);
            navigate("/tasks");
        } catch (error) {
            console.error("Error in handleSubmitTask:", error);
            setIsSubmitting(false);
        }
    };

    return (
    //rest of the code unchanged below

Then replace the return statement with the following code:

return (
<form id="form" onSubmit={handleSubmitTask} className="m-8">
    <div className="flex flex-col mb-6">
        <label htmlFor="title">Task Title</label>
        <input
            type="text"
            id="title"
            placeholder="Title of your task"
            value={titleVal}
            onChange={handleTitleChange}
            className={`bg-inherit border rounded-sm p-2 focus:outline-none                         focus:ring-1 ${
                    titleValidationError
                    ? "border-error focus:ring-red-500 invalid:focus:ring-red-                         600"
                    : "border-input focus:ring-slate-900"
            }`}
        />
        {titleValidationError && (
        <span className="text-error mt-1">{titleValidationError}</span>
        )}
    </div>
    <div className="flex flex-col mb-6">
        <label htmlFor="description" className="mb-1">
            Task Description
        </label>
        <textarea
            id="description"
            placeholder="Describe your task"
            maxLength={200}
            value={textAreaVal}
            onChange={(e) => setTextAreaVal(e.target.value)}
            className={`bg-inherit border rounded-sm p-2 h-32 resize-none                             focus:outline-none focus:ring-1 ${
                        textAreaVal.length > 197
                        ? "border-error focus:ring-red-500 invalid:focus:ring-                             red-600"
                        : "border-input focus:ring-slate-900"
                }`}
        />
        {textAreaVal.length > 197 && (
        <span className="text-error mt-1">
            Warning description getting too long. Can only be 200 characters
        </span>
        )}
    </div>
    <div className="flex flex-col mb-6">
        <label htmlFor="description" className="mb-1">
            Task Priority
        </label>
        <Select
            defaultSelectValue={priority}
            selectOptions={priorityArray}
            handleSelectChange={(e) => setPriority(e.target.value)}
        />
    </div>
    <div className="flex flex-col mb-6">
        <label htmlFor="description" className="mb-1">
            Task Due Date
        </label>
        <input
            type="date"
            id="date"
            value={dueDate!.toISOString().split("T")[0]}
            min={new Date().toISOString().split("T")[0]}
            onChange={(e) => setDueDate(new Date(e.target.value))}
                className="bg-inherit border rounded-sm border-input p-2                                      focus:outline-none focus:ring-1 focus:ring-slate-                               900 invalid:focus:ring-red-600"
        />
    </div>
    <Button
        type="submit"
        disable={isSubmitting}
        extraBtnClasses="bg-primary justify-center text-white font-semibold px-4 py-2 outline-1 hover:bg-primaryHover focus:ring-1 focus:ring-pink-800 w-full"
    >
        <span>
            Add Task
        </span>
    </Button>
</form>
);

Fix import errors and your application should now be validating title and description as well as creating the task then sending you to the "/tasks" route. You can check the Appwrite console to confirm that the task has been created.

How Set Up Read and Delete Tasks

Open the Task.jsx file in the routes folder within src folder, and add the following code above the return like so:

const [tasks, setTasks] = useState<ITask[]>([]);
const [tasksError, setTasksError] = useState("");

useEffect(() => {
        getTasks()
        .then((res) => {
        setTasks(res.reverse());
        })
        .catch((err) => {
        console.error(err);
        setTasksError("Error fetching tasks, please try again");
        });
    }, []);

return (
//rest of code

Here, the file is setting some local state using useState to hold the tasks and set any potential task related errors.

Now replace the code in the return with the following code:

<main className="container mx-auto">
    <section className="max-w-5xl mx-auto m-12 p-16">
        <h1 className="text-4xl md:text-7xl font-bold text-center py-3 mb-16">
        Your Tasks
        </h1>
        {tasksError ? (
            <span className="m-8 text-error">{tasksError}</span>
        ) : (
            <div className="flex flex-col md:flex-row justify-between">
                <div className="flex-1">
                    <h3 className="text-2xl font-bold m-8">Pending Tasks</h3>
                    <div>
                         {tasks
                             .filter((task) => !task.done)
                             .map((task) => (
                                <TaskItem key={task.$id} task={task} />
                         ))}
                    </div>
                </div>
                <div className="flex-1">
                    <h3 className="text-2xl font-bold m-8">Completed Tasks</h3>
                    <div>
                        {tasks
                            .filter((task) => task.done)
                            .map((task) => (
                                <TaskItem key={task.$id} task={task} />
                        ))}
                    </div>
                </div>
            </div>
        )}
    </section>
</main>

You now need to create the getTasks() function and the TaskItem component. In the components folder, create a file called TaskItem.tsx and paste the following code in it:

interface TaskItemProps {
    task: ITask;
}
function TaskItem({ task }: TaskItemProps) {
    return (
    <>
        <div className="m-8 cursor-pointer border border-container rounded-md p-4 hover:shadow-lg transition duration-300 ease-in-out max-h-96">
            <section
            key={task.$id}
            className="flex flex-col justify-between gap-2 my-4 h-full"
            >
            <section className="flex gap-4 items-center justify-between flex-wrap">
                {task.priority && (
                <span>
                    <span className="font-medium">Priority: </span>
                        <span
                            className={`${
                            task.priority === "low"
                            ? "bg-lowPriority text-iconColor"
                            : task.priority === "medium"
                            ? "bg-mediumPriority text-iconColor"
                            : "bg-highPriority text-iconColor"
                            } py-1 px-2 rounded-md`}
                        >
                            {task.priority}
                        </span>
                </span>
                )}
                <div className="flex gap-2 py-1 ml-auto">
                    <Button
                        handleClick={() => handleEdit(task)}
                        extraBtnClasses="bg-ok"
                    >
                        <span className="font-medium">Edit</span>
                        <PencilSquareIcon height={25} className="hidden lg:flex" />
                    </Button>
                    <Button
                        handleClick={(e) => handleDelete(e, task.$id)}
                        extraBtnClasses="bg-highPriority"
                    >
                        <span className="font-medium">Delete</span>
                        <TrashIcon height={25} className="hidden lg:flex" />
                    </Button>
                </div>
            </section>
            <section className="">
                <h2 className="text-xl font-medium py-2 break-words">
                    {task.title}
                </h2>
                <p className="py-1 mb-4 min-h-16 break-words">
                    {task.description.length > 70
                        ? task.description.substring(0, 70) + "..."
                        : task.description}
                </p>
                <span className="font-extralight mt-2">
                    <span className="font-medium">Due on: </span>
                        <span className="underline">{`${new Date(
                            task.due_date
                        ).toLocaleDateString()}`}
                    </span>
                </span>
                </section>
                <section className="flex justify-between">
                    {task.done ? (
                        <span className="items-center text-ok font-bol ml-auto">
                            Completed
                        </span>
                    ) : (
                    <div className="flex items-center ml-auto hover:scale-105 transition duration-300 ease-in-out">
                        <label htmlFor="done" className="mr-2 font-light">
                            Mark as complete
                        </label>
                        <input
                            type="checkbox"
                            checked={isDone}
                            onClick={(e) => e.stopPropagation()}
                            onChange={(e) => {
                            setIsDone(e.target.checked);
                            handleCheckbox(task, task.$id, e);
                        }}
                            className="size-5 accent-pink-600 rounded-sm"
                    />
                </div>
                )}
                </section>
            </section>
        </div>
    </>
    );
}
export default TaskItem;

This gives the file some markup to display. It divides the page into two columns, one for the pending tasks and one for the completed tasks, and it handles responsiveness of the page.

In order to get rid of the errors, paste the following code just before the return statement like so:

function TaskItem({ task }: TaskItemProps) {

//paste here
const [isDone, setIsDone] = useState(false);

const handleDelete = async (
        currentTaskId: string
    ) => {
        try {
            await deleteDocument(currentTaskId);
        } catch (error) {
            console.error(error);
        }
};

const handleCheckbox = async (
        currentTask: IPayload,
        id: string,
        checkedVal: boolean
    ) => {
        if (!checkedVal) return;

        const payload: IPayload = {
        title: currentTask.title,
        description: currentTask.description,
        due_date: currentTask.due_date,
        priority: currentTask.priority,
        done: checkedVal,
        };

        try {
            await updateDocument(payload, id);
        } catch (error) {
            console.error(error);
        }
};

//rest of code below untouched
return (
......

This adds the ability to delete a task item and the ability to mark it as complete.

Create a new file in the utils folder and call it shared.ts. This file will house any function that will be called in more than two places in the application.

The getTasks function is one such repetitive function, so it will be placed in the shared.ts file. Paste the following code into it:

import { readDocuments } from "./db";
import { ITask } from "../models/interface";

export const getTasks = async () => {
    const { documents } = await readDocuments();

    return documents as ITask[];
};

This defines the function and returns an array of ITasks. Go back to the Task.tsx file and fix any import errors.

Run the application and you should see something like this:

your pending and completed tasks displayed in the browser

The task can be deleted or marked as complete but you won't see an update on the UI until the page is refreshed. To fix that, go back to the TaskItem file and paste the following code below the isDone useState and above the handleDelete function:

const [isDone, setIsDone] = useState(false);

//paste here
const updateTasks = async () => {
    try {
        const allTasks = await getTasks();
        if (setTasks) setTasks(allTasks.reverse());
    } catch (error) {
        console.error(error);
    }
};

//rest of code below remains as is
const handleDelete = async (

Update TaskItem props interface and the TaskItem function like so:

interface TaskItemProps {
    task: ITask;
    setTasks?: (tasks: ITask[]) => void;
}

function TaskItem({ task, setTasks }: TaskItemProps) {
//rest of code below
    const [isDone, setIsDone] = useState(false);

This gives a setter function that resets the tasks array as a prop to the TaskItem component.

Adjust the handleDelete and handleCheckbox functions in the TaskItem component to include the updateTasks function you added above. it should read like this:

const handleDelete = async (
    e: React.MouseEvent<HTMLButtonElement>,
    currentTaskId: string
) => {
    try {
        await deleteDocument(currentTaskId);
        updateTasks();
    } catch (error) {
        console.error(error);
    }
};

const handleCheckbox = async (
    currentTask: IPayload,
    id: string,
    e: React.ChangeEvent<HTMLInputElement>
    ) => {

    const payload: IPayload = {
        title: currentTask.title,
        description: currentTask.description,
        due_date: currentTask.due_date,
        priority: currentTask.priority,
        done: e.target.checked,
    };

    try {
        await updateDocument(payload, id);
        updateTasks();
    } catch (error) {
        console.error(error);
    }
};

Go back to the Task.tsx file and pass setTasks to the TaskItem component like so: <TaskItem key={task.$id} task={task} setTasks={setTasks} />. Now, the UI updates without needing to manually refresh the page.

How to Make the Tasks Editable

In order to edit a task, you will need to pass a function to the edit button in the TaskItem component.

Paste the following code in the TaskItem.tsx file between the updateTasks and handleDelete functions like so:

//paste below updateTasks
const handleEdit = async (
    currentTask: ITask
) => {
    navigate("/", { state: { task: currentTask } });
};

//rest of code untouched below

Add this line right above the isDone useState: const navigate = useNavigate();.

In the same file, find the edit button and pass the handleEdit function to it. Also, wrap it in a condition that checks if the task is done such that the button is only displayed in the case that the task is not marked as complete. Like so:

{!task.done && (
    <Button
        handleClick={() => handleEdit(task)}
        extraBtnClasses="bg-ok"
    >
        <span className="font-medium">Edit</span>
        <PencilSquareIcon height={25} className="hidden lg:flex" />
    </Button>
)

The AddTask component has to be adjusted to handle editing a task and the Index.tsx file needs to be updated to handle the task to be edited being passed to it via the navigate handleEdit function.

First, go to the AddTask file and add some prop definitions directly below the import statements, then pass the new props to the component like so:

import....

// pass a task and an isEdit boolean
// if isEdit is true, then the form will be populated with the task's data
interface ITaskFormProps {
    task: ITask | null;
    isEdit?: boolean;
    setTasks?: (tasks: ITask[]) => void;
}

//pass component props
const AddTask = ({ task, isEdit, setTasks }: ITaskFormProps) => {
//code untouched below

Adjust the due date and priority useStates to read like below:

const [dueDate, setDueDate] = useState(
    isEdit && task?.due_date ? new Date(task.due_date) : new Date()
);

const [priority, setPriority] = useState(
    isEdit && task?.priority ? task?.priority : priorityArray[0]
);

Add a useEffect below the useStates like so:

const [titleValidationError, setTitleValidationError] = useState("");

//paste below useState statements
useEffect(() => {
    if (isEdit && task) {
        setTitleVal(task.title);
        setTextAreaVal(task.description);
    } else {
        setTitleVal("");
    }
}, [isEdit, task]);

In the handleSubmit function within the same AddTask file, delete this line: await createDocument(payload); and replace with the below:

if (isEdit && task) {
    await updateDocument(payload, task!.$id);
    const allTasks = await getTasks();
    if (setTasks) return setTasks(allTasks.reverse());
} else {
    await createDocument(payload);
}

Now replace the Button component at the bottom of the file just above the form closing tag with this:

<Button
    type="submit"
    disable={isSubmitting}
    extraBtnClasses="bg-primary justify-center text-white font-semibold px-4 py-2 outline-1 hover:bg-primaryHover focus:ring-1 focus:ring-pink-800 w-full"
>
    <span>
        {isSubmitting ? "Submitting..." : task ? "Edit Task" : "Add Task"}
    </span>
</Button>
//unchanged code below
</form>
    );
};

export default AddTask;

This sets the text on the button depending on whether the form is submitting, creating a new task or updating an exisiting task.

Go to the Index.tsx file in the routes folder and paste the following above the return statement:

const Index = () => {
    //paste here
    const location = useLocation();
    const navigate = useNavigate();

    const taskFromState: ITask = location.state?.task;

    const [taskToEdit] = useState<ITask | null>(taskFromState ?? null);

    useEffect(() => {
        if (taskFromState) {
            navigate(location.pathname, {});
        }
    }, [taskFromState, location.pathname, navigate]);

    //below code remains unchanged
    return (....

Here, the file gets the task passed to it from the "/tasks" route and sets it to local state. Then the useEffect nullies the passed task so that the form is reset on refresh.

In the Index.tsx file replace the AddTask component with this line: <AddTask task={taskToEdit} isEdit={taskToEdit ? true : false} />.

Run your application and you should be able to click on the edit button, be navigated back to the "/" route, have the form pre-filled with the task details, be able to edit some of the fields and be redirected back to "/tasks" once you click on the "Edit Task" button.

How to Enable Viewing of Tasks

The application now creates, reads, updates and deletes tasks. All that is left on that is the ability to view a particular task.

Go to the TaskItem file, add the following to the interface TaskItemProps: isViewTask: boolean; handleViewTask?: (e: React.MouseEvent<HTMLDivElement>) => void;.

Add them as props to the TaskItem component and set isViewTask to a default of false like so:

function TaskItem({
    task,
    setTasks,
    isViewTask = false,
    handleViewTask,
}: TaskItemProps) {    
    //rest of code below unchanged
    const navigate = useNavigate();

Replace the paragraph tag that displays the task description within the return of the component with this markup:

<p className="py-1 mb-4 min-h-16 break-words">
    {task.description.length > 70 && !isViewTask
        ? task.description.substring(0, 70) + "..."
        : task.description
    }
</p>

The change introduced will ensure that the full description is visible if isViewTask is set to true.

On the div tag just below the return in the same component, add an onClick handler like so:

return (
<>
    <div
        className="m-8 cursor-pointer border border-container rounded-md p-4                        hover:shadow-lg transition duration-300 ease-in-out max-h-                       96"
        onClick={handleViewTask}
    >
//rest unchanged code
...

Back in the Task.tsx file, paste the following just above the useEffect:

const handleViewTask = (
    e: React.MouseEvent<HTMLDivElement>,
    activeTask: ITask
) => {
    setIsViewTask(true);
    setSelectedTask(activeTask);
};

//unchanged code below
useEffect(...

Add the following useState functions above the handleViewTask function, below the other useStates:

const [tasksError, setTasksError] = useState("");
//paste here
const [isViewTask, setIsViewTask] = useState(false);
const [selectedTask, setSelectedTask] = useState<ITask>();

//code below unchanged
const handleViewTask = (...

Now paste the following code within the return statement in the same file, just above the h1 tag displaying "Your Tasks" text:

return (
<main className="container mx-auto">
    <section className="max-w-5xl mx-auto m-12 p-16">
        //paste here
        {isViewTask && selectedTask && (
            <Dialog key={selectedTask.$id} setIsViewTask={setIsViewTask}>
                <TaskItem
                    task={selectedTask}
                    handleViewTask={() => handleViewTask(selectedTask!)}
                    isViewTask={isViewTask}
                />
            </Dialog>
        )}
        <h1 className="text-4xl md:text-7xl font-bold text-center py-3 mb-16">
        Your Tasks
        </h1>
        //rest of code below remains unchanged

You will need to create the Dialog component. Create a new file in the components folder and call it Dialog.tsx, then paste the following in it:

import { XMarkIcon } from "@heroicons/react/24/solid";
import { ReactNode, useState } from "react";
import { ITask } from "../models/interface";
import Button from "./Button";

interface DialogProps {
    setIsViewTask?: (isViewTask: boolean) => void;
    children: ReactNode;
}

function Dialog({ setIsViewTask, children }: DialogProps) {
    const [isOpen, setIsOpen] = useState(true);

    const closeModal = () => {
        if (setIsViewTask) setIsViewTask(false);
        setIsOpen(false);
    };
    return (
        <dialog
            open={isOpen}
            id="modal"
            style={{
            backgroundColor: "var(--base-bg)",
            color: "var(--text-main)",
            }}
            className={`${
                isOpen ? "opacity-100" : "opacity-0 pointer-events-none"
                } transition-opacity duration-300 ease-in-out fixed inset-0                      backdrop-filter backdrop-blur-md backdrop-brightness-50 w-4/6                      border border-container rounded-md max-h-[80vh] overflow-y-auto                 text-main`}
        >
        <Button
            handleClick={closeModal}
            content={{ text: "Close", icon: XMarkIcon }}
            extraBtnClasses="ml-auto text-main font-medium hover:text-error"
        />
        <div className="max-h-[80vh] overflow-y-auto">{children}</div>
        </dialog>
    );
    }

export default Dialog;

Here, the file defined a Dialog component that takes in some props, displays a button and the children it receives from props.

Finally, replace the two TaskItem components in the tasks.filter... function within the return statement of the Task.tsx file with the following:

{tasks
    .filter((task) => !task.done)
    .map((task) => (
        <TaskItem
            key={task.$id}
            task={task}
            setTasks={setTasks}
            handleViewTask={() => handleViewTask(task)}
            isViewTask={isViewTask}
        />
))}

You should be able to click on the task items and have the dialog pop up with the details of the task.

However, if you try to delete the item you will notice that it opens the dialog while deleting it. To fix that, adjust the handleDelete function in the TaskItem.tsx file to read like this:

const handleDelete = async (
    e: React.MouseEvent<HTMLButtonElement>,
    currentTaskId: string
) => {
    e.stopPropagation();
    try {
        await deleteDocument(currentTaskId);
        if (isViewTask) {
            navigate(0);
        } else {
            updateTasks();
        }
    } catch (error) {
        console.error(error);
    }
};

You've added e.stopPropagation() to stop the event from bubbling up to the parent and potentially interfering with the click to open the dialog.

You've also added a check after deleting the task to see if the task is being viewed, in which case we refresh the page via the navigate(0) to force the UI to update to the proper state. If not, it proceeds to call updateTasks() to refresh the state.

You will notice the same issue when you try to mark the task as complete in which the dialog pops up. To fix this, adjust the checkbox input to include this line: onClick={(e) => e.stopPropagation()}.

The new line stops the event from bubbling up to the parent div. It is added to the onClick instead of the onChange because the event it is trying to intercept is of type onClick. The input should read like this:

<label htmlFor="done" className="mr-2 font-light">
    Mark as complete
</label>
<input
    type="checkbox"
    checked={isDone}
    onClick={(e) => e.stopPropagation()}
    onChange={(e) => {
    setIsDone(e.target.checked);
    handleCheckbox(task, task.$id, e);
    }}
    className="size-5 accent-pink-600 rounded-sm"
/>

At this point, the React application is responsive, can CRUD the Appwrite database and the user can view individual tasks.

How to Auto Generate Descriptions with Vercel's AI SDK

To enhance the application and its' user experience, you can add the ability to auto generate descriptions for the tasks using AI.

To get started, open an integrated terminal and run the following command: npm i ai. This adds the Vercel AI SDK to the React application.

Next, run this command in the terminal: npm i @huggingface/inference to add Hugging Face support. The application will use Hugging Face because you need to pay to get programmatic access to OpenAI.

Create a new file in the utils folder, call it ai.ts and paste the following in it:

import { HfInference } from "@huggingface/inference";
import { HuggingFaceStream, StreamingTextResponse } from "ai";

// Create a new HuggingFace Inference instance
const Hf = new HfInference(import.meta.env.VITE_HUGGINGFACE_KEY);

// IMPORTANT! Set the runtime to edge
export const runtime = "edge";

export const callAI = async (prompt: string) => {
    const response = Hf.textGenerationStream({
        model: "OpenAssistant/oasst-sft-4-pythia-12b-epoch-3.5",
        inputs: `<|prompter|>${prompt}<|endoftext|><|assistant|>`,
        parameters: {
            max_new_tokens: 150,
            // @ts-ignore
            typical_p: 0.2,
            repetition_penalty: 1,
            truncate: 1000,
            return_full_text: false,
        },
    });

    // Convert the response into a friendly text-stream
    const stream = HuggingFaceStream(response);

    // Respond with the stream
    return new StreamingTextResponse(stream);
};

This boilerplate creates an instance of Hugging Face, creates a function that takes in a prompt, passes that prompt to the textGenerationStream function. Then it converts the response to a stream and to a text stream.

You will need to add a Hugging Face access token. You can genrate one at this address. You will need an account before you can access it.

Once you have token, open the env file and add to it the following line

//replace with your actual token
VITE_HUGGINGFACE_KEY=YOUR-HF-ACCESS-TOKEN

Open the AddTask.tsx file and paste the following button just above the closing div tag of the div containing the textarea input:

{textAreaVal.length > 197 && (
    <span className="text-error mt-1">
        Warning description getting too long. Can only be 200 characters
    </span>
)}
//paste here
<Button
    handleClick={generateDesc}
    disable={isGenerating}
    extraBtnClasses="bg-light mt-2 w-fit ml-auto"
>
    <span>Generate description</span>
    <SparklesIcon height={20} />
</Button>
//rest of below code unchanged
</div>

Define generateDesc function just above the return statement in the AddTask file like so:

const generateDesc = async () => {
    setTextAreaVal("");

    if (!titleVal) {
    alert("Please provide a title for the task");
    return;
    }

    setIsGenerating(true);

    const prompt = `Provide a description for this task: ${titleVal}. Keep the description to a maximum of 30 words`;

    try {
        const res = await callAI(prompt);
        const responseText = await res.text();

        setIsGenerating(false);

        //create a typing effect
        responseText.split("").forEach((char, index) => {
        setTimeout(() => {
        setTextAreaVal((prevText) => prevText + char);
        }, index * 32);
        });
    } catch (error) {
        console.log("ERROR HUGGING FACE API: " + error);
    }
};

The function checks that the title is not empty and uses the title to create a prompt to pass on the Hugging Face helper. The response from the call is saved to local state. A simple typing effect is created as the textarea is populated with the response.

Next, add this useState: const [isGenerating, setIsGenerating] = useState(false); to the other useStates in the AddTask component.

Replace the textarea input in the same component with the following:

<textarea
    id="description"
    placeholder="Describe your task"
    maxLength={200}
    value={isGenerating ? "generating..." : textAreaVal}
    onChange={(e) => setTextAreaVal(e.target.value)}
    className={`bg-inherit border rounded-sm p-2 h-32 resize-none          focus:outline-none focus:ring-1 ${
    textAreaVal.length > 197
    ? "border-error focus:ring-red-500 invalid:focus:ring-red-600"
    : "border-input focus:ring-slate-900"
    }`}
/>

On checking the application, you should see the button and be able to generate a description for the title of a task as below:

ai-enhanced task description

Voice-enable the Application with the React Speech Recognition Package

First, you need to add the dependency and its Typescript helper by running the following commands in an integrated terminal window: npm i react-speech-recognition and npm i @types/react-speech-recognition.

Additionally, run the following command to get the dependency to work properly: npm i regenerator-runtime.

Create a hooks folder within the src folder. Create a file within it called useSpeechToTextHelper.ts and paste the following in it:

import "regenerator-runtime/runtime";
import { useState } from "react";
import { useSpeechRecognition } from "react-speech-recognition";

export function useSpeechToTextHelper() {
    const [error, setError] = useState("");

    const {
        transcript,
        listening,
        resetTranscript,
        browserSupportsSpeechRecognition,
    } = useSpeechRecognition();

    if (!browserSupportsSpeechRecognition) {
        setError("Browser doesn't support speech recognition.");
    }

    return {
        error,
        listening,
        transcript,
        resetTranscript,
    };
}

This hook exposes some built in helper functions from React Speech Recognition, handles the case that the browser does not support the relevant web APIs and returns some of that data.

Create a new file in the components folder called Speaker.tsx. Paste the following code into it:

import { useSpeechToTextHelper } from "../hooks/useSpeechToTextHelper";
import { MicrophoneIcon, XCircleIcon } from "@heroicons/react/24/solid";
import Button from "./Button";
import SpeechRecognition from "react-speech-recognition";

interface SpeakerProps {
handleClear: (e: React.MouseEvent<HTMLButtonElement>) => void;
}

function Speaker({ handleClear }: SpeakerProps) {
    const { listening, error } = useSpeechToTextHelper();

    const handleSpeech = () => {
        SpeechRecognition.startListening();
    };

    return (
    <div>
        {error && <div>{error}</div>}
        <div className="flex gap-2 py-1 items-center text-center justify-center">
            <span className="font-medium">{listening ? "Mic on" : "Mic off"}</span>
            <Button
                handleClick={handleSpeech}
                extraBtnClasses="bg-lightOk"
                title="Start"
            >
                <MicrophoneIcon height={25} />
            </Button>
            <Button
                handleClick={handleClear}
                extraBtnClasses="bg-light"
                type="reset"
                title="Reset"
            >
                <XCircleIcon height={25} />
            </Button>
        </div>
    </div>
    );
}

export default Speaker;

This components accepts a function to clear the voice input as a prop, uses the helper hook, defines a function to handle the actual speech, handles potential error state and displays a button for handling the speech and another for clearing the voice transcript.

In the AddTask file, delete the label for title and replace it with the following markup:

<div className="flex flex-row justify-between items-center">
    <label htmlFor="title">Task Title</label>
    <Speaker handleClear={clearTranscript} />
</div>

This adds the Speaker component and wraps both the label and the Speaker component in a representational div in order to maintain the form layout.

Add the clearTranscript function just above the handleSubmit function like so:

const handleTitleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    setTitleVal(e.target.value);

    if (e.target.value.trim() !== "") {
        setTitleValidationError("");
    }
};

//paste here
const clearTranscript = () => {
    resetTranscript();
};
//below code is unchanged
const handleSubmitTask = asyc....

Next in the same AddTask component, add the following:

const AddTask = ({ task, isEdit, setTasks }: ITaskFormProps) => {
    const navigate = useNavigate();
    //paste here
    const { transcript, resetTranscript } = useSpeechToTextHelper();
    //rest remains unchanged

Replace the useEffect in the file with this new one:

useEffect(() => {
    if (isEdit && task && !transcript) {
        setTitleVal(task.title);
        setTextAreaVal(task.description);
    } else {
        setTitleVal(transcript || "");
    }
}, [isEdit, task, transcript]);

Your application should now support creating titles for the tasks via voice inputs. And should look something like this:

voice input functionality added to the form

How to Add Search Functionality to the Application

To increase ease of use, it is useful to have some search functionality in the application.

To start, open up the Appwrite console. Click into your collections, click on Indexes tab then click on the "Create index" button.

Leave the index key as is, select FullText in the index type dropdown. Add title attribute and create the index. Repeat the process for the description attribute.

In your application, open db.ts file in utils folder and paste the following function just above the export keyword, then add it to the list of exports:

const searchTasks = async (searchTerm: string) => {
    const resTitle = await databases.listDocuments(dbID, collectionID, [
                        Query.search("title", searchTerm),
                    ]);
    const resDesc = await databases.listDocuments(dbID, collectionID, [
                        Query.search("description", searchTerm),
                     ]);
    const res = [...resTitle.documents, ...resDesc.documents];

    return res;
};

export {
    createDocument,
    readDocuments,
    updateDocument,
    deleteDocument,
    searchTasks,
};

Create a new file in the components folder, calll it Search.tsx. Paste the following into it:

import { FormEvent, useState } from "react";
import { ITask } from "../models/interface";
import Dialog from "./Dialog";
import TaskItem from "./TaskItem";
import Button from "./Button";
import { searchTasks } from "../utils/db";

const Search = () => {
const [searchTerm, setSearchTerm] = useState("");
const [isSearching, setIsSearching] = useState(false);
const [searchedTasks, setSearchedTasks] = useState<ITask[]>([]);
const [error, setError] = useState("");

    return (
        <div className="flex flex-col w-full md:w-1/2">
            <form
                className="flex flex-col md:flex-row items-start md:items-center gap-2"
                onSubmit={handleSubmit}
            >
                {searchedTasks.length > 0 && (
                    <Dialog setSearchedTasks={setSearchedTasks}>
                        {searchedTasks.map((task: ITask) => (
                            <TaskItem key={task.$id} task={task} isViewTask={true} />
                        ))}
                    </Dialog>
                )}
            <input
                aria-roledescription="search"
                type="text"
                id="search"
                placeholder="search your tasks..."
                value={searchTerm}
                onChange={(e) => setSearchTerm(e.target.value)}
                className={`bg-inherit w-5/6 border rounded-md p-2 focus:outline-none focus:ring-1 ${
                error
                ? "border-error focus:ring-red-500 invalid:focus:ring-red-600"
                : "border-input focus:ring-slate-900"
                }`}
            />
            <Button
            type="submit"
            extraBtnClasses="bg-primary text-white hover:bg-primaryHover font-medium text-main py-2"
            >
                <span>{isSearching ? "Searching..." : "Search"}</span>
            </Button>
            </form>
            <span className="text-error font-medium mt-1">{error}</span>
        </div>
    );
};

export default Search;

The new Search component creates some local state and returns a form with an input and search button. It also opens the dialog when it has search results.

Add this handleSubmit function above the return statement like so:

const handleSubmit = async (e: FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    if (!searchTerm) {
        setError("No search term entered");
        setTimeout(() => {
        setError("");
        }, 3000);
        return;
    }

    setIsSearching(true);

    const res = await searchTasks(searchTerm);
    console.log("res search: ", res);
    if (res.length === 0) {
        setIsSearching(false);
        setError("No task found");
        setTimeout(() => {
        setSearchTerm("");
        setError("");
        }, 3000);
        return;
    }
    setIsSearching(false);
    setSearchedTasks(res as ITask[]);
};

This function sets an error if no search term is received, then it attempts to call the database search function passing it the search term. If successful it sets the tasks to local state and if not, it catches the error.

Click into the dialog component and replace its props with the following, then pass the setSearchedTasks to it like so:

interface DialogProps {
    setIsViewTask?: (isViewTask: boolean) => void;
    setSearchedTasks?: (tasks: ITask[]) => void;
    children: ReactNode;
}

function Dialog({ setIsViewTask, setSearchedTasks, children }: DialogProps) {...

Replace the closeModal function in the dialog component with this snippet:

const closeModal = () => {
    if (setIsViewTask) setIsViewTask(false);
    //this is the new line
    if (setSearchedTasks) setSearchedTasks([]);
    setIsOpen(false);
};

Go back into the Task.tsx file and paste this below the h1 tag that displays the "Your Tasks" text:

<h1 className="text-4xl md:text-7xl font-bold text-center py-3 mb-16">
Your Tasks
</h1>
//paste here
<div className="m-8 flex flex-col-reverse md:flex-row gap-8 items-start                     md:items-center md:justify-between">
    <Search />
    <Button
        handleClick={() => navigate("/")}
        extraBtnClasses="bg-primary text-white font-medium py-2 hover:bg-    primaryHover ml-auto"
    >
        <span>Add Task</span>
        <PlusIcon height={25} className="hidden md:flex" />
    </Button>
</div>
//rest of code stays unchanged

This adds the search component and a button that takes you back to the Index page when clicked.

Add the following within the Task component just below the useStates:

const [selectedTask, setSelectedTask] = useState<ITask>();
//paste here
const navigate = useNavigate();
//all below remain unchanged
const handleSelectChange = (e: React.ChangeEvent<HTMLSelectElement>)

You can now test your search functionality. It works but has one bug: if the search term is present in the both the title and the description we get back two search results.

To fix that, modify the searchTasks function in db.ts to filter out duplicate tasks by IDs like so:

const searchTasks = async (searchTerm: string) => {
    const resTitle = await databases.listDocuments(dbID, collectionID, [
        Query.search("title", searchTerm),
    ]);
    const resDesc = await databases.listDocuments(dbID, collectionID, [
        Query.search("description", searchTerm),
    ]);

    const res = [...resTitle.documents, ...resDesc.documents];

    // remove duplicate tasks
    const uniqueRes = res.filter(
        (task, index, self) => index === self.findIndex((t) => t.$id ===                  task.$id)
    );

    return uniqueRes;
};

Now your search should work as expected and should look like this:

your pending and completed tasks displayed in the browser

How to Add Ability to Sort Tasks via Due Date and Priority

The application will only sort the pending tasks as it makes the most sense. It will sort by due date from the earliest date to the latest and vice versa. It will also sort by priority from lowest to highest and vice versa.

To get started, paste the following in the Tasks.tsx file right below the h3 tag with the "Pending Tasks" text like so:

<h3 className="text-2xl font-bold m-8">Pending Tasks</h3>
//paste here
<div className="m-8 flex items-start lg:items-center gap-1 justify-between flex-col lg:flex-row">
    <span className="font-medium">Sort Tasks by: </span>
    <Select
        defaultSelectValue={selectArray[0]}
        handleSelectChange={handleSelectChange}
        selectOptions={selectArray}
    />
</div>

Then paste the following array that will contain the options for select component above. Paste it right above handleViewTask function like so:

const navigate = useNavigate();
//paste here
const selectArray = [
    "priority - (low - high)",
    "priority - (high - low)",
    "due date - (earliest - latest)",
    "due date - (latest - earliest)",
];
//rest remains unchanged
const handleViewTask = (...

Add the handleSelectChange and the sort functions above the selectArray, like so:

const sortByPriority = (tasksList: ITask[], isAsc: boolean): ITask[] => {
    const priorityOrder: { [key: string]: number } = {
    low: 1,
    medium: 2,
    high: 3,
    };

    return [...tasksList].sort((a, b) => {
    const priorityA = priorityOrder[a.priority!.toLowerCase()];
    const priorityB = priorityOrder[b.priority!.toLowerCase()];
    return isAsc ? priorityA - priorityB : priorityB - priorityA;
    });
};

const handleSelectChange = async (
    e: React.ChangeEvent<HTMLSelectElement>
) => {
    const selectedOption = e.target.value;
    const doneTasks = tasks.filter((task) => task.done);

    switch (selectedOption) {
        case "priority - (low - high)":
        case "priority - (high - low)": {
            const isAsc = selectedOption === "priority - (low - high)";
            const sortedTasks = sortByPriority(tasks, isAsc);
            setTasks([...doneTasks, ...sortedTasks.filter((task) =>                           !task.done)]);
            break;
        }
        case "due date - (earliest - latest)":
        case "due date - (latest - earliest)": {
            const isEarliestToLatest =
            selectedOption === "due date - (earliest - latest)";
            const dueDateResult = await sortByDueDate(isEarliestToLatest);
            const sortedTasks = dueDateResult.documents as ITask[];
            setTasks([...doneTasks, ...sortedTasks.filter((task) =>                            !task.done)]);
            break;
        }
        default:
            break;
        }
};

//below remains unchanged
const selectArray = .....

The sortByPriority function creates an object whose keys map to the priority array and gives them numerical values. This makes it easier to sort as it is hard to tell which string is higher priority without that.

The handleSelectChange function picks out the selected option and filters the tasks to get the completed ones. It does matching logic in the switch statements, calling sortByPriority for the cases where the user is trying to do that and it calls sortByDueDate for the rest of the cases.

sortByDueDate is defined in the db.ts file. Open it and paste the following at the bottom of the file above the exports. Then add it to the exports list like so:

const sortByDueDate = async (isEarliestToLatest: boolean) => {
    const orderQuery = isEarliestToLatest
        ? Query.orderAsc("due_date")
        : Query.orderDesc("due_date");
    const res = await databases.listDocuments(dbID, collectionID,              [orderQuery]);
    return res;
};

export {
    createDocument,
    readDocuments,
    updateDocument,
    deleteDocument,
    searchTasks,
    sortByDueDate,
};

This function leverages Appwrites' Query methods to sort the date string according to the Boolean that is passed to it.

Going back to your application, run it to test the sorting functionality. The application should be sorted and the sorting should only apply to the pending tasks.

Bonus: How to Add Dark Mode Support

The last thing left is to add Dark Mode support that respects the users' systems setting.

For this, open the tailwind.config.ts file and replace its contents with the following:

/** @type {import('tailwindcss').Config} */
export default {
    content: ["./index.html", "./src/**/*.{js,ts,jsx,tsx}"],
    darkMode: "selector",
    theme: {
        extend: {
            textColor: {
                error: "var(--text-error)",
                ok: "var(--text-ok)",
                main: "var(--text-main)",
                iconColor: "var(--btn-icon-main)",
            },
            backgroundColor: {
                base: "var(--base-bg)",
                primary: "var(--btn-bg-primary)",
                primaryHover: "var(--btn-bg-primary-hover)",
                ok: "var(--btn-bg-ok)",
                lightOk: "var(--btn-bg-light-ok)",
                light: "var(--btn-bg-light)",
                lowPriority: "var(--low-priority)",
                mediumPriority: "var(--medium-priority)",
                highPriority: "var(--high-priority)",
            },
            borderColor: {
                container: "var(--border-container)",
                input: "var(--border-input)",
                error: "var(--border-error)",
            },
        },
    },
    plugins: [],
};

This extends the tailwind preset colors and ties the CSS variables that were set in the index.css file to the Tailwind config.

In the index.css file, add this dark class below the date class like so:

#date::-webkit-calendar-picker-indicator {
    background-color: var(--btn-bg-light); 
}
//paste here
.dark{
    --base-bg: #262626;
    --text-main: #ffffff;
    --text-error: #fca5a5;
    --text-ok: #86efac;
    --border-input: #e2e8f0;
    --border-error: #fca5a5;
}

This changes some of the CSS variables values when the dark class is applied.

Now, open the navbar file in the components folder and replace its contents with the following:

const Navbar = () => {
    const navigate = useNavigate();

    const themeArray = ["light", "dark", "system"];
    const [theme, setTheme] = useState(() => {
        return localStorage.getItem("theme") || themeArray[2];
    });

    const applyTheme = (selectedTheme: string) => {
        const isDarkModePreferred = window.matchMedia(
            "(prefers-color-scheme: dark)"
            ).matches;

        document.documentElement.classList.remove("light", "dark");
        document.documentElement.classList.add(selectedTheme);

        if (selectedTheme === "system") {
        document.documentElement.classList.toggle("dark", isDarkModePreferred);
        document.documentElement.classList.toggle("light",                  !isDarkModePreferred);
        }
    };

    const handleSelectTheme = (e: React.ChangeEvent<HTMLSelectElement>) => {
        const selectedTheme = e.target.value;
        setTheme(selectedTheme);

        // Store the selected theme in localStorage
        localStorage.setItem("theme", selectedTheme);
    };

    useEffect(() => {
        applyTheme(theme);
    }, [theme]);

    return (
        <nav className="py-4 border-b-2 border-container shadow-md shadow-gray-400 w-full fixed top-0 bg-base">
            <ul className="flex items-center justify-between  w-11/12 mx-auto">
                <Link to="/">
                    <Button>
                        <span className="font-semibold text-main">Taskwrite</span>
                        <PencilIcon height={20} className="text-main" />
                    </Button>
                </Link>
                <div className="flex items-center justify-between gap-6">
                <Link
                    to="/tasks"
                    className="font-semibold hover:scale-105 transition duration-300 ease-in-out"
                >
                    View Tasks
                </Link>
                <div className="flex gap-2 items-center">
                    <span className="font-semibold"> Theme: </span>
                    <Select
                        defaultSelectValue={theme}
                        selectOptions={themeArray}
                        handleSelectChange={handleSelectTheme}
                    />
                </div>
                </div>
            </ul>
        </nav>
    );
};

export default Navbar;

Your application should now have a select in the navigation menu that successfully toggles between dark and light themes while defaulting to the system preferences when set to "System".

It should look like so:

Taskwrite complete interface and functionalities

And Taskwrite is complete! You have successfully built a task manager application that is AI-enhanced, voice-enabled, searchable and sortable using React and Appwrite.

Notes

Appwrite recently announced some new features that would greatly simplify the search functionality above but, at the time of writing, these changes were not rolled out to their cloud offering.

The application could be further simplified by using state management solutions and this will be added to it in subsequent articles.

The application is live here.

Limitations

The following are some known limitations and issues with this application:

• The navigation menu is not responsive
• The application has no tests written
• The permissions set for Appwrite are permissive and not recommended for production environments
• The application could leverage Appwrites' Realtime capabilites for a smoother experience
• The application could do with push notifications to remind the user when the task due date is coming up

That said, the application is going to continue being improved and worked on. You can follow along with that on GitHub. All contributions and improvements on the codebase are welcome. Please star the repository while you are at it.

Imagine having two different programs: program A and program B. For these two programs to communicate together, an API is needed, and a set of rules ensure that they know what to expect when they interact with each other.

As a backend developer, your responsibilities involve building server-side applications, handling data storage, and providing the necessary functionalities to do all these through APIs.

There are different types of APIs like REST, GraphQL, gRPC, SOAP, and WebSockets. However, when it comes to web development, one is more popular, and that is the REST API.

In this article, you will learn how to create a CRUD API with Node.js and Express using the REST architecture, and by the end of this article, you should have a fully functional API that is able to perform CRUD operations.

So, let's dive into the world of backend development with Node.js and Express and get started on our journey to building a CRUD API.

Table of Contents

• What is a CRUD API?
• What is Node.js?
• Why Node?
• How to Install Node.js
• What is Express?
• Why do You Need Express?
• Prerequisites
• How to Set Up Your Development Environment
• How to Set up a server for Your CRUD Restful API with Node.js and Express
• CRUD API Example
• How to Create API Routes
• How to Create Your own CRUD API
• How to Create the GET /users Endpoint
• How to Test Your API GET Request
• How to Create the POST /users Endpoint
• How to Test the POST Request
• How to Create the GET /users/:id Endpoint
• How to Test the GET Request
• How to Create the DELETE /users/:id
• How to Test the DELETE Request
• How to Create the PATCH /users/:id Endpoint
• How to Test the PATCH Request
• Wrapping UP

What is a CRUD API?

In web development, CRUD operations are the bread and butter of backend systems. This is because they allow you to "Create", "Read", "Update", and "Delete" data through your API.

Here's a quick overview of the four primary HTTP methods associated with CRUD operations:

• GET: Used for reading or retrieving data from the server.
• POST: Used for creating new data on the server.
• PUT: Used for updating existing data on the server.
• DELETE: Used for removing data from the server.

Virtually every web application interacts with a database to perform these four core operations. Whether it's a social media platform, an e-commerce website, or a weather app, they all rely on creating, reading, updating, and deleting data.

For example, WhatsApp recently added an edit feature to the application, allowing users to make corrections to an already-sent message. That's one part of the CRUD operation in action (updating).

In the context of building a web API, these operations become the backbone of how your application interacts with data. Your API provides endpoints that allow client applications (like web or mobile apps) to perform these operations on the server.

This communication between the client and the server is the essence of web development, and understanding how to create a CRUD API is a crucial skill for a web developer.

What is Node.js?

Node.js is an open-source and cross-platform runtime environment for executing JavaScript code outside of a browser. Quite often, we use it to build back-end services, also called APIs. Node is ideal for building highly scalable, data-intensive and real-time back-end services that power our client applications

Why Node?

• It is one of the most popular choices for building the backend.
• You get to write JavaScript across your entire stack, making it easier to transition from either a frontend developer to a backend developer and vice versa.
• It allows for easy scaling of applications, making it a good choice for large-scale professional projects.
• It is fast and non-blocking. This is because of the asynchronous event-driven nature of Node.js.
• Node.js has a vibrant community and a rich ecosystem of packages and libraries.

How to Install Node.js

Installation steps:

1. Download the Mac/Windows installer from the Node.js website.
2. Choose the Long-Term Support (LTS) version that’s shown on the left
3. After downloading, install/run the installer, and then follow the prompts. (You will have to click the NEXT button a bunch of times and accept the default installation settings
4. To confirm that Node has been successfully installed, open your terminal and run the command. (For Windows, you might need to restart your command before running it.)

node –version

What is Express?

Express is a fast, unopinionated, and minimalist web backend or server-side web framework for Node.js. Basically, it gives you the ability to build your APIs how you want them, with less code.

It is a framework built on top of Node.js that allows you to create your Backend with ease. You can use Express in combination with frontend frameworks like React, Angular, or Vue to build full-stack applications.

Why do You Need Express?

• It makes building web applications with Node.js much easier.
• It is extremely light, fast and free.
• It is used for both server-rendered apps as well as API/Microservices.
• It is the most popular Node.
• It gives you full control over requests and responses.

Prerequisites

To follow along, you'll need to have the following:

• Basic knowledge of JavaScript
• Download and install Node.js and Postman on your computer

See the complete code for this tutorial on Github.

How to Set Up Your Development Environment

Before diving into creating your API, let's go through the process of creating a basic server on your local computer.

Here are the steps to follow:

Step #1 – Create Directory

Create a directory/folder on your computer. Open the folder in a code editor

Step #2 – Create index.js File

Create an index.js file inside the folder using this command:

touch index.js

Step #3 – Initialize NPM

Initialize NPM inside the folder by running this command in your terminal:

npm init -y

The command will create a package.json file with default values.

Step #5 – Install Express

Use the command below to install Express.js

npm install express

After installing Express, go to the package.json file and include “type”: “module”. This declaration will tell Node that this project will be using ES6 module syntax (import/export) instead of common.js, which is the default in Node.

package.json file with type:module

How to Set up a server for Your CRUD Restful API with Node.js and Express

To create a CRUD restful API, you first need to set up your server. You can do this by following these steps:

Step #1 – Write your Server Application Code inside the index.js file

Basically, a server code will look like this:

import express from 'express';
import bodyParser from ‘body-parser

const app = express();
const PORT = 5000

app.use(bodyParser.json());

app.listen(PORT, () => console.log(`Server running on port: http://localhost:${PORT}`));

Here's an explanation for the code above:

• In the first line, we imported express from the Express module that we installed.
• The bodyParser comes with Express, and it allows us to take in the incoming POST request body.
• Next, we created an app using the express object.
• We then specified the port for the application – it was set to 5000 (if you get an error using this port, it might be that the port is currently being used by a different app, so you can either change your port or stop the other app from using the port).
• Next, we specified that JSON data will be used in the application.
• Once that was created, we used the listen method on the app to make our application listen for incoming requests. The method accepts two things: the PORT, which is where we would be listening for requests from our client side, and a callback function that will be triggered when our server is set up.

Step #2 – Start the Server

Now you can start your server by running this command. If you used a different file, replace index.js with the file name where the server is located.

node index.js

Now your server should be running on port 5000. You can verify that your server is running on your terminal

Step #3 – Install Nodemon (Optional)

At the moment, anytime you make changes to your server file, you will need to restart the server before your changes can reflect (you can try it and see). So to take care of this challenge, you can use Nodemon. Run the command to install it:

npm install nodemon

To use Nodemon, head over to your package.json file and set up a script. Replace your start script with this instead:

"start": "nodemon index.js"

Note that index.js is the file where the server code is written.

Now you can start your server by running this command:

npm start

With this code, we've set up a server that listens on port 5000 and prints a message when it starts. But this is just the beginning because our server needs to do much more.

Let's explore how to handle API requests next.

CRUD API Example

Let's start by defining the API routes for each CRUD operation. These routes will serve as the entry points for your API, and they will map to specific actions we want to perform on our data.

In our case, these actions are creating, reading, updating, and deleting data.

How to Create API Routes

When the port (http://localhost:5000/) is opened in a browser, you will get an error.

localhost:5000 in the browser without any routes

This is because Node.js and Express are all about routing, and we don't any routes yet.

You can define API routes using the app.get(), app.post(), app.put(), and app.delete() methods in your Express application (in the index.js file).

Here's how to create a route to handle GET requests using the app.get() function:

app.get('/', (req, res)

The app.get() function accepts two parameters. The first is used to specify the path (in this case, it is '/').

The next parameter is a callback function where you define what happens when the GET request is called. The function also has two parameters: the request body (req), which can contain information such as the request query string, parameters, body, and HTTP headers. While the response object (res) contains the information you want to send

Here is the complete code:

import express from 'express';
import bodyParser from 'body-parser'
const app = express();

const PORT = 5000;

app.use(bodyParser.json());

app.get('/', (req, res) => {
    console.log('[GET ROUTE]');
    res.send('HELLO FROM HOMEPAGE');
})

app.listen(PORT, () => console.log(`Server running on port: http://localhost:${PORT}`));

When you head back to http://localhost:5000/ and refresh it, you shouldn’t get an error anymore.

localhost:5000 in the browser with GET route

How to Create Your own CRUD API

For this API, you will be handling a set of users. Handling users in a database is a great example because it is a common use case in most applications.

Here are the API endpoints you will be creating:

1. GET /users - find all users
2. POST /users - creates a user
3. GET /users/:id - finds a specific user
4. DELETE /users/:id - deletes a specific user
5. PATCH /users/:id - updates a specific user.

How to Create the GET /users Endpoint

Reading data is one of the most common operations in an API. In this example, you will be getting the list of all the users in your mock database. This information will be presented in JSON format.

To define a route to retrieve users' data from the database, follow these steps:

• Create a new folder called routes
• Create a new file called users.js inside the routes folder.
• Write the code to set up the GET router.

import express from 'express';
const router = express.Router();

// Mock database
const users = [
  {
    first_name: 'John',
    last_name: 'Doe',
    email: 'johndoe@example.com',
  },
  {
    first_name: 'Alice',
    last_name: 'Smith',
    email: 'alicesmith@example.com',
  },
];

// Getting the list of users from the mock database
router.get('/', (req, res) => {
    res.send(users);
})

export default router

In this code snippet:

• import express from 'express'; imports the Express.js framework
• const router = express.Router(); creates a fresh router instance, stored in the variable router.
• The users variable serves as the mock database containing an array of users.
• The router.get() function sets up a route that responds to HTTP GET requests.
• The second part of the code (req, res) => { ... } is a callback function. It gets executed when a request is made to the GET route.
• Inside the callback function, we used res.send(users) to send a response back to the client. In this example, we're sending the users variable as the response. So when a user hits the GET URL, the server responds by sending the data inside the users variable in JSON format to the client.

Save your changes in the users.js file. Then do the following in the index.js file:

import your user routes from user.js:

import userRoutes from './routes/users.js'

Use the app.use method, and specify the path and router handler:

app.use('/users', userRoutes);

When a user visits http://localhost:5000/users, the router is triggered. It effectively acts as a filter, determining when a specific set of routes should be applied.

Here is the complete code for the index.js file:

import express from 'express';
import bodyParser from 'body-parser'
const app = express();
import userRoutes from './routes/users.js'

const PORT = 5000;

app.use(bodyParser.json());

app.use('/users', userRoutes);

app.get('/', (req, res) => res.send('HELLO FROM HOMEPAGE'))

app.get('/', (req, res));

app.listen(PORT, () => console.log(`Server running on port: http://localhost:${PORT}`));

How to Test Your API GET Request

You can use either a browser (browsers can only be used to perform GET requests) or Postman to test the GET request.

So copy your API URL, http://localhost:5000/users, and paste it either on Postman or in your browser. If you are using Postman, you will first need to make a GET request, then paste your API URL, and then click on send. After that, you will see the list of users in your Postman console.

postman GET route test

How to Create the POST /users Endpoint

You can use the POST request to add data to your database. It accepts input from the client and stores it in the database. To create data in our API, we'll define a route that accepts POST requests and saves the data to the mock database you have set up.

But before that, you'll need the UUID package. Use this command to install it:

npm install uuid

This package will help generate a unique ID for each user you will be creating. This will be useful when you are implementing the GET, DELETE, and PATCH user by ID requests, where you will need a way to identify a specific user.

So in the users.js file, do the following:

Import the uuid package:

import { v4 as uuidv4 } from 'uuid';

Secondly, you'll have to implement the code for the POST request.

Here is what it looks like:

router.post('/', (req, res) => {
    const user = req.body;

    users.push({ ...user, id: uuidv4() });

    res.send(`${user.first_name} has been added to the Database`);
})

In the code snippet:

• The router.post() function sets up a route that responds to HTTP POST requests. This means that when a client sends a POST request to the root URL of your application, this route will be triggered.
• Within the callback function (req, res) => { ... }, we access the req object, which represents the incoming request made by the client. Specifically, we're interested in the req.body property. This property contains the data (first name, last name, and email) that the client will send as part of the POST request's body.
• With const user = req.body we extract this data from req.body and store it in the user variable.
• Next, we added the user data to an array called users. To ensure each user has a unique identifier, we generate a universally unique identifier (UUID) using a function like uuidv4() and include it as id in the user object. This helps in keeping user records distinct and identifiable.
• Finally, we used res.send() to send a response back to the client. In this case, we're sending a simple message notifying the client that the user has been successfully added to the database. The message includes the user's first name for a personalized touch.

Here is the complete code

import express from 'express';
import { v4 as uuidv4 } from 'uuid';

const router = express.Router();

const users = [];

// Adding users to our mock database

router.post('/', (req, res) => {
    const user = req.body;

    users.push({ ...user, id: uuidv4() });

    res.send(`${user.first_name} has been added to the Database`);
})  

export default router

How to Test the POST Request

Here are the steps to follow to make a POST request on Postman:

• Go to Postman
• Open a new request tab
• Select "POST" from the list of available HTTP methods
• In the URL field, enter the full URL where you want to send the POST request (http://localhost:5000/users)
• Click on the "Body" tab in the request window.
• Choose the format in which you want to send your POST data (choose JSON).
• Enter the data you want to send in the request body. This data should match the format expected by the server.
• Finally, click on “Send”

postman POST route test

If it is successful, you will get a response saying, “Daanny has been added to the database."

To confirm if it has been added, make a GET request, and you should see the new user added to your database. (Note: This user information will be lost when your server restarts since it’s not saved to an actual database).

postman GET route test

How to Create the GET /users/:id Endpoint

Fetching specific data based on a unique identifier, such as a user ID, is a common operation. It's often essential for building features like user profiles or retrieving individual records from a database.

In this section, you’ll explore how to use this endpoint (users/:id) to retrieve user information based on a provided user ID.

Let's get started!

router.get('/:id', (req, res) => {
    const { id } = req.params;

    const foundUser = users.find((user) => user.id === id)

    res.send(foundUser)
});

Here's what this code snippet does:

• The router.get() function sets up a route that responds to HTTP GET requests. In this example, we've defined a route with ('/:id'). The :id part is a route parameter, which allows us to capture a dynamic value from the URL. In this case, it represents the user ID we want to retrieve.
• Within the callback function (req, res) => { ... }, we can access the req object, which represents the incoming request made by the client. Specifically, we're interested in req.params, which holds the values of route parameters. In this case, we destructure id from req.params, effectively extracting the user ID from the URL. For example, if a client makes a GET request to /users/123, the id will be '123'.
• We used the .find() method to search through this data based on the user ID (id) captured from the URL. This method attempts to find a user whose ID matches the provided id.
• Once we located the user data (if it exists), we send it as the response using res.send(foundUser). The foundUser variable contains the user object that matches the requested ID.

How to Test the GET Request

In testing the API, follow these steps:

• Go to your POST request tab and make as many requests as you want to add a new user to the database.
• Go to your GET request tab and make a request to see the list of users you have added

postman GET route test

• Copy the id of any of the users on the list
• Create a new GET request tab, copy in the base API URL, and add the id of any of the users to it. It should be in a format like this: http://localhost:5000/users/734a9e75-b3f5-415f-82fb-79b4fdf1a593
• Click on “Send”. If it’s successful, you will see the user information of the user id you used for the request

postman GET route test

How to Create the DELETE /users/:id

Sometimes, it's necessary to remove user accounts or specific records from a database for various reasons, such as account deactivation.

Here, you will explore how to use this endpoint to delete user data based on a provided user ID.

To delete data, we'll define a route that accepts DELETE requests and removes the data from the database.

See the code to delete a user from a database below

router.delete('/:id', (req, res) => {
  const { id } = req.params;

  users = users.filter((user) => user.id !== id)

  res.send(`${id} deleted successfully from database`);
});

Here's what this code does:

• The router.delete() function sets up a route that responds to HTTP DELETE requests. In this example, we've defined a route with ('/:id'), where :id is a route parameter. It captures a dynamic value from the URL, representing the user ID we want to delete.
• In the callback function (req, res) => { ... }, we can access the req object, which represents the incoming request made by the client. Specifically, we're interested in req.params, which holds the values of route parameters. Here, we destructure id from req.params, extracting the user ID from the URL. For instance, if a client sends a DELETE request to /users/123, id will be '123'.
• Assuming that we have an array or database (users) containing user data, we employ the .filter() method to create a new array that excludes the user with the matching ID (id). This effectively removes the user from the data store.
• After successfully deleting the user, we send a response back to the client using res.send(). The response contains a message confirming the deletion, including the user's ID that was deleted from the database.

How to Test the DELETE Request

Here are the steps to delete a user from the database on Postman:

• Go to Postman
• Open a new request tab
• Select "DELETE" from the list of available HTTP methods
• Enter the URL. It should contain the id of the user you want to delete (for example: http://localhost:5000/users/734a9e75-b3f5-415f-82fb-79b4fdf1a593). If you don’t have a user in your database, you will need to create one and copy the id.
• Click on “Send”.

postman DELETE route test

postman DELETE route test

How to Create the PATCH /users/:id Endpoint

There are times when you don't need to update an entire resource or object. Instead, you'd want to make partial modifications or adjustments. This is where the HTTP PATCH request comes into play.

For example, after creating a new user, you can change either the first name, last name, or email of that user using the PATCH request. Let’s see how to do that.

router.patch('/:id', (req, res) => {
  const { id } = req.params;

  const { first_name, last_name, email} = req.body;

  const user = users.find((user) => user.id === id)

  if(first_name) user.first_name = first_name;
  if(last_name) user.last_name = last_name;
  if(email) user.email = email;

  res.send(`User with the ${id} has been updated`)

});

Here's what this code snippet accomplishes:

• The router.patch() function sets up a route that responds to HTTP PATCH requests. In this example, we've defined a route with ('/:id'), where :id is a route parameter. It captures the dynamic value from the URL, representing the user ID we want to update.
• Within the callback function (req, res) => { ... }, we can access the req object, which represents the incoming request made by the client. Specifically, we're interested in req.params, which hold the values of route parameters (id in this case), and req.body, which contains the data to be updated.
• Next, we used .find() to locate the user object with the matching ID (id). Once found, we can proceed to modify the user's data based on the content of req.body. We also checked if first_name, last_name, or email properties exist in req.body. If they do, we can update the corresponding properties of the user object with the new values. This allows us to make selective changes to the user's data without affecting other attributes.
• After successfully applying the requested modifications, we send a response back to the client using res.send(). The response includes a message confirming the successful update of the user data, along with the user's ID.

How to Test the PATCH Request

Follow these steps to make a PATCH request in Postman:

• Go to Postman
• Open a new request tab
• Select "PATCH" from the list of available HTTP methods
• Enter URL; the URL will contain the id of the user you want to delete (for example: http://localhost:5000/users/734a9e75-b3f5-415f-82fb-79b4fdf1a593). If you don’t have a user in your database, you will need to create one and copy the id.
• Click on the "Body" tab in the request window and choose the format in which you want to send your PATCH data (for example: JSON, form-data, x-www-form-urlencoded).
• Enter the data you want to send in the request body. This data should only include the specific changes you want to make to the resource.
• Then click the "Send" button. Postman will send the PATCH request to the specified URL with the provided data.

postman PATCH route test

Wrapping Up

APIs are the linchpin connecting various software components and enabling them to work together seamlessly. They allow them to communicate, share data, and perform tasks. In the context of web development, APIs enable the web to function as we know it today.

In this tutorial, we explored backend development by creating a CRUD API with Node.js and Express. We covered various concepts, like how to set up a development environment, create a server with Express and Node.js, and most importantly, how to handle CRUD operations and test your API using Postman.

While we've covered fundamental aspects of API creation in this tutorial, there is still a vast landscape of knowledge to explore as regards to APIs. These include how to secure your API by adding authentication, how to use middleware, database interaction, API deployment, and a lot more.

We just posted a course on the freeCodeCamp.org YouTube channel that will throw you into the world of backend development by guiding you through building a CRUD API from scratch. You will use Node.js, Express, and MongoDB. The course is led by popular instructor and experienced developer Haris Iftikhar.

Now, what about the technologies? This course will equip you with three powerful tools:

• Node.js: A JavaScript runtime environment that allows you to run JavaScript code outside of the browser, perfect for building server-side applications.
• Express.js: A popular web framework built on top of Node.js, providing structure and tools to simplify web development.
• MongoDB: A NoSQL database, meaning it stores data in a flexible and document-oriented manner, ideal for modern applications.

Together, these technologies form the backbone of the MERN Stack, a widely used combination for building full-stack web applications. In this course, you'll be focusing on the MEN part (minus the React front-end), laying a solid foundation for your backend development journey.

The course is structured into bite-sized sections, taking you through each step of building your CRUD API:

• Setting the Stage: Understand the project outline and get familiar with the tools you'll be using.
• Project Essentials: Dive into package.json, the Express framework, and learn how to run your server efficiently.
• Data Management: Explore API testing tools, utilize Git Bash for version control, and set up your MongoDB database.
• Building the API: Craft your data model, create API endpoints for creating, reading, updating, and deleting data.
• Form Handling: Understand Form URL Encoded data and how to handle it in your API.
• Structuring your Code: Organize your code with routes and controllers, keeping things clean and maintainable.
• Testing and Deployment: Learn how to thoroughly test your API and push your code to GitHub for version control and collaboration.

By the end of this course, you'll have built a functional CRUD API using Node, Express, and MongoDB, gaining valuable hands-on experience in backend development. This knowledge will pave the way for you to explore more complex concepts and build even more sophisticated applications in the future.

Watch the full course on the freeCodeCamp.org YouTube channel (2-hour watch).

In this journey, we'll be creating a delightful recipe management system. We'll explore the power of NestJS, Docker, Swagger, and Prisma, and harness these cutting-edge technologies to implement CRUD (Create, Read, Update, Delete) operations for managing recipes.

But this tutorial isn't just for the culinary enthusiasts or recipe collectors out there. It's for anyone who's passionate about learning and growing their development skills.

So, buckle up and get ready for an exciting coding adventure as we dive in and start building your very own recipe management system together.

This is what we'll build:

A snapshot of the Swagger UI showcasing all the implemented endpoints.

And here's what we'll cover:

Table of Contents

• Technologies
• Prerequisites
• Development Environment
• How to Set Up the NestJS Project
• How to Create a PostgreSQL Instance with Docker
• How to Set Up Prisma
• How to Initialize Prisma
• How to Set Your Environment Variable
• Understanding the Prisma Schema
• How to Model the Data
• How to Migrate the Database
• How to Seed the Database
• How to Create a Prisma Service
• How to Set Up Swagger
• How to Implement CRUD Operations for the Recipe Model
• How to Generate REST Resources with NestJS CLI
• How to Add PrismaClient to the Recipe Module
• How to Define the GET /recipes Endpoint
• How to Define the GET /recipes/:id Endpoint
• How to Define the POST /recipes Endpoint
• How to Define the PATCH /recipes/:id Endpoint
• How to Define the DELETE /recipes/:id Endpoint
• Summary and Final Remarks

Technologies

To build this application, we'll be leveraging the power of the following tools:

• NestJS: A progressive Node.js framework for building efficient, reliable, and scalable server-side applications.
• Prisma: An open-source database toolkit that makes it easy to reason about your data and how you interact with it.
• PostgreSQL: A powerful, open source object-relational database system.
• Docker: An open platform for developing, shipping, and running applications. Docker enables you to separate your applications from your infrastructure so you can deliver software quickly.
• Swagger: A tool for designing, building, and documenting RESTful APIs.
• TypeScript: A statically typed superset of JavaScript that adds optional types, classes, and modules to the language.

Each of these technologies plays a crucial role in creating a robust, scalable, and maintainable application. We'll dive deeper into each one as we proceed.

Prerequisites

Assumed Knowledge

This tutorial is designed to be beginner-friendly, but I do make a few assumptions about what you already know:

• Fundamentals of TypeScript
• Basics of NestJS
• Docker

If you're not familiar with these, don't fret! I've got you covered. This tutorial will guide you through everything you need to know.

But here are some more resources if you'd like to learn more:

• For a deeper dive into NestJS, feel free to explore the official NestJS documentation.
• To learn more about Docker, here's a full handbook for beginners.
• And for more info on TypeScript, here's a helpful crash course.

Development Environment

Tools and Technologies

In this tutorial, we'll use the following tools:

• Node.js – Our runtime environment
• Docker – For containerizing our database
• Visual Studio Code – Our code editor
• PostgreSQL – Our database
• NestJS – Our Node.js framework

Note: Don't forget to install the Prisma extension for Visual Studio Code. It enhances your coding experience by highlighting Prisma-specific syntax and keywords.

How to Set Up the NestJS Project

NestJS is a progressive Node.js framework that comes with a plethora of advantages, including a powerful Command Line Interface (CLI). This CLI simplifies the process of creating a new NestJS application, making it easy to start a new project anytime, anywhere.

One of the key benefits of NestJS is its rich set of built-in functionalities that significantly streamline the development process, making your life as a developer much easier.

Let's begin by installing the NestJS CLI on your system:

npm i -g @nestjs/cli

With the NestJS CLI installed, you're all set to whip up our recipe project. The CLI streamlines the creation of a new NestJS application, making it simple to get started.

To spin up a new project, execute the following command:

nest new recipe

After running this command, you'll encounter a prompt like the one you see below:

The Nest CLI prompting for a package manager selection during project setup.

As illustrated in the image, the Nest CLI will prompt you to select a package manager. For this project, we'll opt for npm. Once you've made your selection, the CLI will proceed with the project setup, and you'll see a series of operations being performed in your terminal.

Now you can open you project in VSCode (or the editor of your choice). You should see the following files:

The folder structure of the project after it has been created using Nest CLI.

Let break down the project structure:

The src directory is the nerve center of our application, hosting the bulk of our codebase. The NestJS CLI has already set the stage for us with several key files:

• src/app.module.ts: This is the root module of our application, serving as the main junction for all other modules.
• src/app.controller.ts: This file houses a basic controller with a single route: /. When accessed, this route will return a simple 'Hello World!' message.
• src/main.ts: This is the gateway to our application. It's tasked with bootstrapping and launching the NestJS application.

To start your project and see the 'Hello World!' message in action, execute the following command:

npm run start:dev

This command triggers a live-reload development server. It vigilantly monitors your files, and if it spots any modifications, it automatically recompile your code and refreshes the server. This ensures that you can see your changes in real-time, eliminating the need for manual restarts.

To verify that your server is operational, head over to http://localhost:3000/ in your web browser or Postman. You should be welcomed by a minimalist page showcasing the message Hello World. This is your application's default landing page, a pristine canvas awaiting your creative touch.

How to Create a PostgreSQL Instance with Docker

To store our recipes REST API, we'll use a PostgreSQL database. Docker will help us containerize this database, ensuring a smooth setup and execution, regardless of the environment.

First, ensure Docker is installed on your system. If not, follow the instructions here.

Next, you'll need to create a docker-compose.yml file.

Open the terminal and run the following command:

touch docker-compose.yml

This command creates a new docker-compose.yml file in your project's root directory.

Open the docker-compose.yml file and add the following code:

# docker-compose.yml

version: '3.8'
services:
  postgres:
    image: postgres:13.5
    restart: always
    environment:
      - POSTGRES_USER=recipe
      - POSTGRES_PASSWORD=RecipePassword
    volumes:
      - postgres:/var/lib/postgresql/data
    ports:
      - '5432:5432'
volumes:
  postgres:

Here's a quick breakdown of this configuration:

• image: postgres:13.5: Specifies the Docker image for the PostgreSQL database.
• restart: always: Ensures the container restarts if it stops.
• environment: Sets the username and password for the database.
• volumes: Mounts a volume to persist database data, even if the container is stopped or removed.
• ports: Exposes port 5432 on both the host machine and the container for database access.

Note: If you wish to use a different port, simply change the host machine port. For example, to use port 5433, modify the ports section as follows:

ports:
  - '5444:5432'

Note: Before proceeding, ensure port 5432 is free on your machine. To fire up the PostgreSQL container, execute the following command in your project's root directory (and also make sure you have open the docker desktop app and it is running):

docker-compose up

This command spins up the PostgreSQL container and makes it accessible on port 5432 of your machine. If all goes according to plan, you should see output similar to this:

...
 | PostgreSQL init process complete; ready for start up.
postgres-1  |
postgres-1  | 2024-01-12 14:59:33.519 UTC [1] LOG:  starting PostgreSQL 13.5 (Debian 13.5-1.pgdg110+1) on x86_64-pc-linux-gnu, compiled by gcc (Debian 10.2.1-6) 10.2.1 20210110, 64-bit
postgres-1  | 2024-01-12 14:59:33.520 UTC [1] LOG:  listening on IPv4 address "0.0.0.0", port 5432
postgres-1  | 2024-01-12 14:59:33.520 UTC [1] LOG:  listening on IPv6 address "::", port 5432
postgres-1  | 2024-01-12 14:59:33.526 UTC [1] LOG:  listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"
postgres-1  | 2024-01-12 14:59:33.533 UTC [62] LOG:  database system was shut down at 2024-01-12 14:59:33 UTC
postgres-1  | 2024-01-12 14:59:33.550 UTC [1] LOG:  database system is ready to accept connections

Remember, if you've changed the port number, the output will reflect your chosen port.

If the port is already in use, you'll encounter an error message like this:

Error starting userland proxy: listen tcp 0.0.0.0:5432: bind: address already in use

In such a case, free up the port or choose a different one in your docker-compose.yml file.

Note: if you close the terminal window, it will also stop the container. To prevent this, you can run the container in detached mode. This mode allows the container to run indefinitely in the background.

To do this, add a -d option at the end of the command, like so:

docker-compose up -d

To stop the container, use the following command:

docker-compose down

Congratulations 🎉. You now have your own PostgreSQL database to play around with.

How to Set Up Prisma

Now that we have our PostgreSQL database up and running, we're ready to set up Prisma. Prisma is an open-source database toolkit that makes it easy to reason about your data and how you interact with it.

Prisma is a powerful tool that offers a wide range of features, including:

• Database Migrations: Prisma makes it easy to evolve your database schema over time, without losing any data.
• Database Seeding: Prisma allows you to seed your database with test data.
• Database Access: Prisma provides a powerful API for accessing your database.
• Database Schema Management: Prisma allows you to define your database schema using the Prisma Schema Language.
• Database Querying: Prisma provides a powerful API for querying your database.
• Database Relationships: Prisma allows you to define relationships between your database tables.

You can learn more about Prisma here.

How to Initialize Prisma

To get started with Prisma, we'll need to install the Prisma CLI. This CLI allows us to interact with our database, making it easy to perform database migrations, seeding, and more.

To install the Prisma CLI, execute the following command:

npm install prisma -D

This command installs the Prisma CLI as a development dependency in your project. The -D flag tells npm to install the package as a development dependency.

Next, initialize Prisma in your project by executing the following command:

npx prisma init

This will create a new prisma directory with a schema.prisma file. This is the main configuration file that contains your database schema. This command also creates a .env file inside your project.

How to Set Your Environment Variable

The .env file contains the environment variables required to connect to your database. Open this file and replace the contents with the following:

DATABASE_URL="postgres://recipe:RecipePassword@localhost:5444/recipe"

Note: If you changed the port number in your docker-compose.yml file, ensure you update the port number in the DATABASE_URL environment variable with the port number you used.

This environment variable contains the connection string for your database. It's used by Prisma to connect to your database in the docker container.

Understanding the Prisma Schema

The schema.prisma file contains the schema for your database. It's written in the Prisma Schema Language, a declarative language for defining your database schema. The prisma/schema.prisma file is the main configuration file for your Prisma setup. It defines your database connection and the Prisma Client generator.

// prisma/schema.prisma

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

This file is written in the Prisma Schema Language, which is a language that Prisma uses to define your database schema. The schema.prisma file has three main components:

• Generator: This section defines the Prisma Client generator. The Prisma Client generator is responsible for generating the Prisma Client, a powerful API for accessing your database.
• Datasource: This section defines the database connection. It specifies the database provider and the connection string. It use DATABASE_URL environment variable to connect to your database.
• Model: This section defines the database schema. It specifies the database tables and their fields.

How to Model the Data

Now that we have set up our Prisma, we're ready to model our data. We'll be building a recipe management system, so we'll need to define a Recipe model. This model will have various fields.

Open the schema.prisma file and add the following code:

 // prisma/schema.prisma
 // ...
model Recipe {
  id           Int      @id @default(autoincrement())
  title        String   @unique
  description  String?
  ingredients  String
  instructions String
  createdAt    DateTime @default(now())
  updatedAt    DateTime @updatedAt
}

Here's a quick breakdown of this model:

• id: This is the primary key of the Recipe model. It's an auto-incrementing integer that uniquely identifies each recipe. It has the @id attribute, which tells Prisma that this field is the primary key. It also has the @default(autoincrement()) attribute, which tells Prisma to auto-increment this field.
• title: This is the title of the recipe. It's a unique string that's used to identify the recipe.
• description: This is the description of the recipe. It's an optional string that describes the recipe.
• ingredients: This is the list of ingredients used in the recipe. It's a string that contains a comma-separated list of ingredients.
• instructions: This is the list of instructions for preparing the recipe. It's a string that contains a comma-separated list of instructions.
• createdAt: This is the date and time the recipe was created. It's set to the current date and time by default. It has the @default(now()) attribute, which tells Prisma to set this field to the current date and time by default.
• updatedAt: This is the date and time the recipe was last updated. It's set to the current date and time by default.

How to Migrate the Database

Now that we've defined our database schema, we're ready to migrate our database. This will create the database tables and fields defined in our schema.prisma file.

To migrate your database, execute the following command:

npx prisma migrate dev --name init

This command will do three things:

Save the migration: Prisma Migrate will take a snapshot of your schema and figure out the SQL commands necessary to carry out the migration. Prisma will save the migration file containing the SQL commands to the newly created prisma/migrations folder.

Execute the migration: Prisma Migrate will execute the SQL commands in the migration file, creating the database tables and fields defined in your schema.prisma file.

Generate Prisma Client: Prisma will generate Prisma Client based on your latest schema. Since you did not have the Client library installed, the CLI will install it for you as well. You should see the @prisma/client package inside dependencies in your package.json file.

Prisma Client is a TypeScript query builder auto-generated from your Prisma schema. It is tailored to your Prisma schema and will be used to send queries to the database.

If all goes according to plan, you should see output similar to this:

The following migration(s) have been created and applied from new schema changes:

migrations/
  └─ 20220528101323_init/
    └─ migration.sql

Your database is now in sync with your schema.
...
✔ Generated Prisma Client (3.14.0 | library) to ./node_modules/@prisma/client in 31ms

Check the generated migration file to get an idea about what Prisma Migrate is doing behind the scenes:

-- prisma/migrations/20220528101323_init/migration.sql

CREATE TABLE "Recipe" (
    "id" SERIAL NOT NULL,
    "title" TEXT NOT NULL,
    "description" TEXT,
    "ingredients" TEXT NOT NULL,
    "instructions" TEXT NOT NULL,
    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
    "updatedAt" TIMESTAMP(3) NOT NULL,

    CONSTRAINT "Recipe_pkey" PRIMARY KEY ("id")
);

-- CreateIndex
CREATE UNIQUE INDEX "Recipe_title_key" ON "Recipe"("title");

This migration file contains the SQL commands necessary to create the Recipe table. It also contains the SQL commands necessary to create the title field, which is a unique field. This ensures that the title field is unique, preventing duplicate recipes from being created.

How to Seed the Database

Now that we've migrated our database, we're ready to seed it with some test data. This will allow us to test our application without having to manually create recipes.

Firstly, create a seed file called prisma/seed.ts. This file will contain the dummy data and queries needed to seed your database.

Open the terminal and run the following command:

touch prisma/seed.ts

This command creates a new prisma/seed.ts file in your project's root directory.

Next, populate this file with the following code:

// prisma/seed.ts
import { PrismaClient } from '@prisma/client';

// initialize Prisma Client
const prisma = new PrismaClient();

async function main() {
  // create two dummy recipes
  const recipe1 = await prisma.recipe.upsert({
    where: { title: 'Spaghetti Bolognese' },
    update: {},
    create: {
      title: 'Spaghetti Bolognese',
      description: 'A classic Italian dish',
      ingredients:
        'Spaghetti, minced beef, 
        tomato sauce, onions, garlic, olive oil, salt, pepper',
      instructions:
        '1. Cook the spaghetti. 2. Fry the minced beef. 3.
        Add the tomato sauce to the beef.
        4. Serve the spaghetti with the sauce.'
    }
  });

  const recipe2 = await prisma.recipe.upsert({
    where: { title: 'Chicken Curry' },
    update: {},
    create: {
      title: 'Chicken Curry',
      description: 'A spicy Indian dish',
      ingredients:
        'Chicken, curry powder, onions, garlic, 
        coconut milk, olive oil, salt, pepper',
      instructions:
        '1. Fry the chicken. 2. Add the curry powder to the
        chicken. 3. Add the coconut milk.
        4. Serve the curry with rice.'
    }
  });

  console.log({ recipe1, recipe2 });
}

// execute the main function
main()
  .catch(e => {
    console.error(e);
    process.exit(1);
  })
  .finally(async () => {
    // close Prisma Client at the end
    await prisma.$disconnect();
  });

This file contains the dummy data and queries needed to seed your database. Let's break it down:

• import { PrismaClient } from '@prisma/client';: This imports the Prisma Client, which is used to send queries to the database.
• const prisma = new PrismaClient();: This initializes the Prisma Client, allowing us to send queries to the database.
• async function main() { ... }: This is the main function that contains the dummy data and queries needed to seed your database.
• const recipe1 = await prisma.recipe.upsert({ ... });: This creates a new recipe. It uses the upsert method, which creates a new recipe if it doesn't exist, or updates the existing recipe if it does.
• const recipe2 = await prisma.recipe.upsert({ ... });: This creates a new recipe. It uses the upsert method, which creates a new recipe if it doesn't exist, or updates the existing recipe if it does.
• console.log({ recipe1, recipe2 });: This logs the newly created recipes to the console.
• main().catch((e) => { ... });: This executes the main function and catches any errors that occur.
• await prisma.$disconnect();: This closes the Prisma Client at the end.

Now before we can seed our database, we need add a script to our package.json file. Open the package.json file and add the following script:

// package.json

// ...
  "scripts": {
    // ...
  },
  "dependencies": {
    // ...
  },
  "devDependencies": {
    // ...
  },
  "jest": {
    // ...
  },
  // pasting the prisma script here
  "prisma": {
    "seed": "ts-node prisma/seed.ts"
  }

The seed command will execute the prisma/seed.ts script that you previously defined. This command should work automatically because ts-node is already installed as a dev dependency in your package.json.

Now that we've defined our seed script, we're ready to seed the database. To seed your database, execute the following command:

npx prisma db seed

This command will seed your database with the dummy data defined in your prisma/seed.ts file. If all goes according to plan, you should see output similar to this:

Running seed command `ts-node prisma/seed.ts` ...
{
  recipe1: {
    id: 1,
    title: 'Spaghetti Bolognese',
    description: 'A classic Italian dish',
    ingredients: 'Spaghetti, minced beef, tomato sauce, onions, garlic, olive oil, salt, pepper',
    instructions: '1. Cook the spaghetti. 2. Fry the minced beef. 3. Add the tomato sauce to the beef. 4. Serve the spaghetti with the sauce.',
    createdAt: 2024-01-12T16:21:09.133Z,
    updatedAt: 2024-01-12T16:21:09.133Z
  },
  recipe2: {
    id: 2,
    title: 'Chicken Curry',
    description: 'A spicy Indian dish',
    ingredients: 'Chicken, curry powder, onions, garlic, coconut milk, olive oil, salt, pepper',
    instructions: '1. Fry the chicken. 2. Add the curry powder to the chicken. 3. Add the coconut milk. 4. Serve the curry with rice.',
    createdAt: 2024-01-12T16:21:09.155Z,
    updatedAt: 2024-01-12T16:21:09.155Z
  }
}

The seed command has been executed.

Congratulations 🎉. You now have a fully functional database with dummy data.

How to Create a Prisma Service

Now that we've set up Prisma, we're ready to create a Prisma service. This service will act as a wrapper around the Prisma Client, making it easy to send queries to the database.

The Nest CLI gives you an easy way to generate modules and services directly from the CLI. Run the following command in your terminal:

npx nest generate module prisma
npx nest generate service prisma

Note that the generate command can be shortened to g. So, you can also run the following command:

npx nest g module prisma
npx nest g service prisma

This command generates a new module called prisma and a new service called prisma. It also imports the PrismaModule into the AppModule.

So you should see something like this:

  src/prisma/prisma.service.spec.ts
  src/prisma/prisma.service.ts
  src/prisma/prisma.module.ts

Note: In some cases, you may need to restart your server for the changes to take effect.

Next, open the prisma.service.ts file and replace the contents with the following:

// src/prisma/prisma.service.ts

import { Injectable } from '@nestjs/common';
import { PrismaClient } from '@prisma/client';

@Injectable()
export class PrismaService extends PrismaClient {}

This service is a wrapper around the Prisma Client, making it easy to send queries to the database. It's also a NestJS provider, which means it can be injected into other modules.

Next, open the prisma.module.ts file and replace the contents with the following:

// src/prisma/prisma.module.ts
import { Module } from '@nestjs/common';
import { PrismaService } from './prisma.service';

@Module({
  providers: [PrismaService],
  exports: [PrismaService]
})
export class PrismaModule {}

Note: The PrismaModule is a NestJS module that imports the PrismaService, making it readily available for use across other modules in your application. This setup allows seamless integration of the Prisma service throughout your project.

Congratulations 🎉! You've successfully set up your Prisma service.

Before we dive into writing our application logic, let's set up Swagger. Swagger is an industry-standard tool for designing, building, and documenting RESTful APIs. It empowers developers to create elegant and comprehensive API documentation effortlessly.

How to Set Up Swagger

To configure Swagger, we'll leverage the @nestjs/swagger package. This package offers a suite of decorators and methods specifically designed to generate Swagger documentation.

To install this package, run the following command:

npm install --save @nestjs/swagger swagger-ui-express

This command adds the @nestjs/swagger package as a dependency in your project. It also installs the swagger-ui-express package, which serves the Swagger UI.

Next, navigate to the main.ts file and append the following code:

// src/main.ts

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

// Define the bootstrap function
async function bootstrap() {
  // Create a NestJS application instance by passing the AppModule to the NestFactory
  const app = await NestFactory.create(AppModule);

  // Use DocumentBuilder to create a new Swagger document configuration
  const config = new DocumentBuilder()
    .setTitle('Recipes API') // Set the title of the API
    .setDescription('Recipes API description') // Set the description of the API
    .setVersion('0.1') // Set the version of the API
    .build(); // Build the document

  // Create a Swagger document using the application instance and the document configuration
  const document = SwaggerModule.createDocument(app, config);

  // Setup Swagger module with the application instance and the Swagger document
  SwaggerModule.setup('api', app, document);

  // Start the application and listen for requests on port 3000
  await app.listen(3000);
}

// Call the bootstrap function to start the application
bootstrap();

This code initializes Swagger and generates the Swagger documentation. Let's break it down:

• const config = new DocumentBuilder() ... .build();: This creates a new Swagger document builder. It sets the title, description, and version of the Swagger document. It also builds the Swagger document.
• const document = SwaggerModule.createDocument(app, config);: This creates a new Swagger document. It uses the Swagger document builder to generate the Swagger document.
• SwaggerModule.setup('api', app, document);: This sets up the Swagger UI. It uses the Swagger document to generate the Swagger UI.

While the application is running, open your browser and navigate to http://localhost:3000/api. You should see the Swagger UI.

The initial view of the Swagger UI after successful setup.

Now that we've set up Swagger, we're ready to start building our REST API.

How to Implement CRUD Operations for the Recipe Model

In this section we'll implement the CRUD operations for the Recipe model. We'll start by generating the REST resources for the Recipe model. Then we'll add the Prisma Client to the Recipe module. Finally, we'll implement the CRUD operations for the Recipe model.

How to Generate REST Resources with NestJS CLI

Before we can implement the CRUD operations for the Recipe model, we need to generate the REST resources for the Recipe model. This will create the boilerplate code for the Recipe module, controller, service, and DTOs.

To generate the REST resources for the Recipe model, execute the following command:

npx nest generate resource recipe

And it will ask you what type of API you want to generate. So now we will select the REST API .

Check out the below image for reference:

Selecting REST API when creating the CRUD operations using the Nest CLI

This command will generate the following files:

CREATE src/recipe/recipe.controller.ts (959 bytes)
CREATE src/recipe/recipe.controller.spec.ts (596 bytes)
CREATE src/recipe/recipe.module.ts (264 bytes)
CREATE src/recipe/recipe.service.ts (661 bytes)
CREATE src/recipe/recipe.service.spec.ts (478 bytes)
CREATE src/recipe/dto/create-recipe.dto.ts (33 bytes)
CREATE src/recipe/dto/update-recipe.dto.ts (176 bytes)
CREATE src/recipe/entities/recipe.entity.ts (24 bytes)
UPDATE src/app.module.ts (385 bytes)

If you open the Swagger API page again, you should see something like this:

The Swagger UI displaying the newly created CRUD operations.

The swagger page now has a new section called Recipe API . This section contains the REST resources for the Recipe model.

Now when you open Swagger you will see something like this:

• POST /recipes: Create a new recipe.
• GET /recipes: Retrieve all recipes.
• GET /recipes/{id}: Retrieve a specific recipe by its ID.
• PATCH /recipes/{id}: Update a specific recipe by its ID.
• DELETE /recipes/{id}: Delete a specific recipe by its ID.

How to Add PrismaClient to the Recipe Module

Now that we've generated the REST resources for the Recipe model, we're ready to add the Prisma Client to the Recipe module. This will allow us to send queries to the database.

Firstly, open the recipe.module.ts file and add the following code:

// src/recipes/recipes.module.ts

import { Module } from '@nestjs/common';
import { RecipeService } from './recipe.service';
import { RecipeController } from './recipe.controller';
import { PrismaModule } from '../prisma/prisma.module';

@Module({
  imports: [PrismaModule],
  controllers: [RecipeController],
  providers: [RecipeService]
})
export class RecipeModule {}

So now we have imported the PrismaModule and added it to the imports array. This will make the PrismaService available to the RecipeService.

Next, open the recipe.service.ts file and add the following code:

// src/recipes/recipes.service.ts
import { Body, Injectable, Post } from '@nestjs/common';
import { CreateRecipeDto } from './dto/create--recipe.dto';
import { UpdateRecipeDto } from './dto/update--recipe.dto';
import { PrismaService } from 'src/prisma/prisma.service';

@Injectable()
export class RecipesService {
  constructor(private readonly prisma: PrismaService) {}

  //  rest of the code
}

So now we have defined the prisma service as a private property of the RecipeService class. This will allow us to access the PrismaService from within the RecipeService class. So now we use the prisma service to perform the CRUD operations.

Sine we have defined the service for the Recipe model, we're ready to implement the CRUD operations for the Recipe model.

How to Define the GET /recipes Endpoint

Let's kickstart our journey into crafting API endpoints by defining the GET /recipes endpoint. This endpoint will serve as a gateway to fetch all the recipes stored in our database.

In your recipes.controller.ts file, you'll find a method named findAll. This method, as the name suggests, is responsible for fetching all the recipes. Here's how we'll define it:

// src/recipes/recipes.controller.ts

// Other code...

@Get()
async findAll() {
  return await this.recipeService.findAll();
}

// Other code...

In the above code:

• The @Get() decorator maps the findAll method to the GET /recipes endpoint.
• The findAll method invokes the findAll method of the recipeService, which retrieves all the recipes from the database.

As we've previously seen, the Controller is the heart of our application's logic. In this context, we're aiming to implement a findAll method that fetches all recipes from our database. To accomplish this, we'll harness the power of Prisma's services within our recipe.service.ts file.

When you open the recipe.service.ts file you will see something like this :

// Other code...
// src/recipes/recipes.service.ts
 findAll() {
    return `This action returns all recipe`;
  }
// Other code...

NOW we will replace the findAll method with the following code:

// src/recipes/recipes.service.ts
// Other code...

async findAll() {
    return this.prisma.recipe.findMany();
}
// Other code...

In the above snippet:

• The findAll method utilizes Prisma's findMany function to retrieve all recipes from the database.
• The await keyword is not necessary here because the async function implicitly wraps the returned value in a Promise.

We've now successfully implemented the service method that our findAll controller will use to fetch all recipes.

Given that we already have seed data in our database, opening Swagger should allow us to retrieve all the recipes. Here's what you can expect to see:

The Swagger UI displaying the result of the 'Fetch All Recipes' operation.

As depicted in the image above, our GET /recipes endpoint is functioning as expected, successfully fetching all recipes from our database.

This marks a significant milestone in our journey of building a robust recipe management system. Let's continue on and add some more features.

How to Define the GET /recipes/{id} Endpoint

Let's now focus on the GET /recipes/{id} endpoint, which retrieves a specific recipe based on its ID. To implement this, we'll need to modify both the controller and the service.

First, navigate to the recipes.controller.ts file. Here, you'll find the findOne method, which is defined as follows:

// src/recipes/recipes.controller.ts

// other code ...
@Get(':id')
async findOne(@Param('id') id: string) {
  return await this.recipeService.findOne(+id);
}
// other code ...

In this code:

• The @Get(':id') decorator maps to the GET /recipes/{id} endpoint.
• The findOne method accepts an id parameter, which is extracted from the route parameters.

Next, let's turn our attention to the recipes.service.ts file. Here, you'll find a placeholder findOne method:

// src/recipes/recipes.service.ts
// other code ...
  findOne(id: number) {
    return `This action returns a #${id} recipe`;
  }

// other code ...

We'll replace this placeholder with a method that fetches a recipe based on its id:

// src/recipes/recipes.service.ts

findOne(id: number) {
  return this.prisma.recipe.findUnique({
    where: { id },
  });
}

In this code:

• The findOne method takes an id as an argument and uses Prisma's findUnique function to retrieve the recipe with the corresponding id.

With the recent modifications, you've unlocked the ability to fetch individual recipes by their ID.

To see this feature in action, navigate to your Swagger page. Here's a snapshot of what you can expect:

The Swagger UI displaying the result of the 'GET BY ID' operation.

Having achieved this milestone, we're ready to venture into creating our own recipes, adding to the existing ones in our database.

How to Define the POST /recipes Endpoint

The NestJS CLI has conveniently generated a create method for us when we created the resource for the Recipe model. Now, we need to implement the logic for this method in the recipe.service.ts file.

First, let's look at the create method in the recipe.controller.ts file:
We will see something like this:

// src/recipes/recipes.controller.ts

// other code ...
@Post()
create(@Body() createRecipeDto: CreateRecipeDto) {
  return this.recipesService.create(createRecipeDto);
}
// other code ...

In this code:

• The @Post() decorator maps the method to the POST /recipes endpoint.
• The create method accepts a createRecipeDto parameter, which is extracted from the request body.

The NestJS CLI has thoughtfully provided us with DTO (Data Transfer Object) files within the recipe folder. One of these, CreateRecipeDto, will be our tool of choice for validating incoming client data.

A Quick DTO Primer: If you're new to the concept of DTOs, they're essentially objects that carry data between processes. In the context of our application, we'll use DTOs to ensure the data we receive aligns with our expectations. If you're keen to delve deeper into DTOs, check out this comprehensive guide.

Now, let's implement the create method in the recipe.service.ts file to interact with our database.

But before we proceed, let's harness the power of the DTO (Data Transfer Object) folder, generated by the Nest CLI, to model our data.

The CreateRecipeDto class, as shown below, is a prime example of a DTO. It's designed to validate incoming client data, ensuring it aligns with our expectations.

// src/recipes/dto/create-recipe.dto.ts
import { IsString, IsOptional } from 'class-validator';

export class CreateRecipeDto {
  @IsString()
  title: string;

  @IsOptional()
  @IsString()
  description?: string;

  @IsString()
  ingredients: string;

  @IsString()
  instructions: string;
}

In this class, we're using the class-validator package to enforce data validation. This package offers a suite of decorators, such as IsString and IsOptional, which we've employed to validate the title, description, ingredients, and instructions fields.

With this setup, we can confidently ensure that these fields will always be strings, with description being optional.

Now, let's implement the create method in the recipe.service.ts file to interact with our database. When you open the recipe.service.ts file you will see something like this:

// src/recipes/recipes.service.ts

// other code ...
  create(createRecipeDto: CreateRecipeDto) {
    return 'This action adds a new recipe';
  }

// other code ...

Replace the create method with the following code:

// src/recipes/recipes.service.ts

// other code ...
create(createRecipeDto: CreateRecipeDto) {
  return this.prisma.recipe.create({
    data: createRecipeDto,
  });
}
// other code ...

In this code:

• The create method uses Prisma's create function to add a new recipe to the database. The data for the new recipe is provided by the createRecipeDto.

With these changes, you can now create new recipes in your swagger page. Here's what you can expect to see:

The Swagger UI displaying the process of creating a new recipe.

As depicted in the image above, we've successfully added a third recipe to our collection. This demonstrates the effectiveness of our POST method in creating new recipes.

How to Define the PATCH /recipes/{id} Endpoint

Having implemented the endpoints to create and retrieve recipes, let's now focus on updating a recipe. We'll implement the PATCH /recipes/{id} endpoint, which updates a specific recipe based on its ID. This requires modifications in both the controller and the service.

In the recipes.controller.ts file, locate the update method. This method is mapped to the PATCH /recipes/{id} endpoint:

// src/recipes/recipes.controller.ts

// other code ...
@Patch(':id')
update(@Param('id') id: string, @Body() updateRecipeDto: UpdateRecipeDto) {
  return this.recipesService.update(+id, updateRecipeDto);
}
// other code ...

In this code:

• The @Patch(':id') decorator maps the method to the PATCH /recipes/{id} endpoint.
• The update method accepts two parameters: id (extracted from the route parameters) and updateRecipeDto (extracted from the request body).

Next, let's implement the update method in the recipe.service.ts file. When you open the recipe.service.ts file, you will see something like this:

// src/recipes/recipes.service.ts

// other code ...
  update(id: number, updateRecipeDto: UpdateRecipeDto) {
    return `This action updates a #${id} recipe`;
  }

// other code ...

Replace the update method with the following code:

// src/recipes/recipes.service.ts

update(id: number, updateRecipeDto: UpdateRecipeDto) {
  return this.prisma.recipe.update({
    where: { id },
    data: updateRecipeDto,
  });
}

In this code:

• The update method uses Prisma's update function to update the recipe in the database. The where clause specifies the recipe to update (based on id), and the data clause specifies the new data for the recipe (provided by updateRecipeDto).

With the recent modifications, we've unlocked the ability to update individual recipes by their ID.

Let's put this new feature to the test by updating the recipe with an ID of 3.

Here's a snapshot of the current state of the recipe:

Displaying the current data of a specific recipe.

As depicted above, this is the existing data for the recipe we're about to update.

After executing the update operation, here's how our recipe transforms:

Displaying the updated data of a specific recipe after modification.

As you can see, our update operation has successfully modified the recipe, demonstrating the effectiveness of our newly implemented feature.

Let's now turn our attention to deleting recipes.

How to Define the DELETE /recipes/{id} Endpoint

Having successfully defined the GET, POST, and PATCH endpoints, our next task is to implement the DELETE /recipes/{id} endpoint. This endpoint will let us remove a specific recipe using its ID. As with the previous endpoints, we'll need to make modifications in both the controller and the service.

In the recipes.controller.ts file, we have a remove method. This method is mapped to the DELETE /recipes/{id} endpoint:

// src/recipes/recipes.controller.ts

@Delete(':id')
async remove(@Param('id', ParseIntPipe) id: number) {
  return await this.recipesService.remove(id);
}

In this updated code:

• The @Delete(':id') decorator maps the method to the DELETE /recipes/{id} endpoint.
• The remove method accepts an id parameter, which is extracted from the route parameters and parsed to a number using ParseIntPipe.

Next, let's implement the remove method in the recipe.service.ts file. Now with the remove method you see this:

// src/recipes/recipes.service.ts
// other code ...
 @Delete(':id')
  remove(@Param('id') id: string) {
    return this.recipeService.remove(+id);
  }

  // other code ...

Replace the remove method with this code:

// src/recipes/recipes.service.ts


// other code 
async remove(id: number) {
  return await this.prisma.recipe.delete({
    where: { id },
  });
}

// other code ..

In this code, the remove method uses Prisma's delete function to remove the recipe with the specified id from the database.

In this code:

• The remove method uses Prisma's delete function to remove the recipe with the corresponding id from the database.

With these changes, you can now delete individual recipes by their ID. Check the Swagger page to see the updated API documentation.

Displaying the process of deleting a specific recipe.

Summary and Final Remarks

In this handbook, we've journeyed through the process of building a REST API using NestJS and Prisma.

We started by setting up a NestJS project, configuring a PostgreSQL database using Docker, and integrating Prisma.

We then dove into the heart of our application, creating a Recipe model and implementing CRUD operations for it. This involved generating RESTful routes, integrating the Prisma Client into our Recipe service, and crafting the logic for each operation.

This guide serves as a solid foundation for your future projects. Feel free to expand upon it, adding more features and functionalities to suit your needs. Thank you for following along, and happy coding!

What we really need is a way to reliably store and manipulate our data within the application environment.

In this article, I'm going to show you how to connect a back end database to your data collection process. The plan involves tossing some HTML, JavaScript, and the tiny database engine SQLite into a bowl, mixing vigorously, and seeing what comes out.

This article comes from my Complete LPI Web Development Essentials Study Guide course. If you'd like, you can follow the video version here:

As you may already know, the SQL in SQLite stands for structured query language. This means that the syntax you'll use for interacting with a SQLite database will closely parallel how you'd do it with databases like MariaDB, Amazon Aurora, Oracle, or Microsoft's SQL Server. If you've got experience with any of those, you'll be right at home here.

Why are we going to use SQLite here? Because it's a very popular choice for the kind of work you're likely to undertake in a web environment.

You'll need to create a new directory on your machine along with some files with JavaScript code. We'll learn how to create, modify, and delete records in a SQLite database.

I could incorporate all those actions into a single file, of course, but I think breaking them out into multiple files will make it easier to understand what's going on.

Connecting to a Database and Creating a Table

Here's what the first file will look like:

const sqlite3 = require('sqlite3').verbose();

// Create/connect to the database
const db = new sqlite3.Database('mydatabase.db');

// Create a table
db.run(`CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY,
    name TEXT,
    age INTEGER
)`);

// Insert data
const insertQuery = `INSERT INTO users (name, age) VALUES (?, ?)`;
const name = 'Trevor';
const age = 5;
db.run(insertQuery, [name, age], function (err) {
    if (err) {
        console.error(err.message);
    } else {
        console.log(`Inserted data with id ${this.lastID}`);
    }
});

// Close the database connection
db.close();

We begin by loading the sqlite3 module as sqlite3 and then creating the db variable to represent our new database instance. The database will be called mydatabase.db.

const sqlite3 = require('sqlite3').verbose();
const db = new sqlite3.Database('mydatabase.db');

If there isn't a database using that name in our local directory, the code will create one, otherwise it'll just connect to the one that's there already.

Since this is our first run, I'll create a new table within the mydatabase.db database. There will be three keys in our table: id, name, and age.

db.run(`CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY,
    name TEXT,
    age INTEGER
)`);

As you can see, id will be the primary key that we'll use to reference individual records.

We defined the data type of each key: integer, text and, again, integer. This definition is something we only need to do once. But we do want to get it right, because changing it later, after we've already added data, can be tricky.

Inserting New Data into a Table

In this section, we'll will add a new record to the table using the SQL INSERT command.

const insertQuery = `INSERT INTO users (name, age) VALUES (?, ?)`;
const name = 'Trevor';
const age = 5;
db.run(insertQuery, [name, age], function (err) {
    if (err) {
        console.error(err.message);
    } else {
        console.log(`Inserted data with id ${this.lastID}`);
    }
});

You'll probably discover that official SQL documentation always capitalizes key syntax terms like INSERT and SELECT. That's a useful best practice, but it's not actually necessary. As a rule, I'm way too lazy to bother.

The query itself is templated as insertQuery, with the name and age details added as constants in the lines that follow.

The db.run method, using the insertQuery constant and those two values (name and age) as attributes, is then executed. Based on the success or failure of the operation, log messages will be generated.

But hang on for a moment. What's with those question marks after declaring insertQuery? And why did we need to break this process into two parts?

This is actually an important security practice known as an escape variable. With this in place, when the db.run() method executes the prepared statement, it'll automatically handle the escaping of the variable value, preventing SQL injection.

Lastly, we close down the connection:

db.close();

Modifying Data

Now let's see how the "modify" code works. Like before, we create a SQLite3 constant and then connect to our database.

This time, however, our table already exists, so we can go straight to the "modify" section.

const sqlite3 = require('sqlite3').verbose();

// Create/connect to the database
const db = new sqlite3.Database('mydatabase.db');

// Modify data
const updateQuery = `UPDATE users SET age = ? WHERE name = ?`;
const updatedAge = 30;
const updatedName = 'name2';
db.run(updateQuery, [updatedAge, updatedName], function (err) {
    if (err) {
        console.error(err.message);
    } else {
        console.log(`Modified ${this.changes} row(s)`);
    }
});

// Close the database connection
db.close();

The pattern is similar. We define an updateQuery method to UPDATE a record that we'll define. This operation will change the age value for an entry whose name equals Trevor.

You may recall that Trevor's age was earlier listed as 25. We're going to update that to 30. Everything else will work the same as before, including closing the connection when we're done.

This section of code from the third file will delete a record:

const deleteQuery = `DELETE FROM users WHERE name = ?`;
const deletedName = 'name1';
db.run(deleteQuery, [deletedName], function (err) {
    if (err) {
        console.error(err.message);
    } else {
        console.log(`Deleted ${this.changes} row(s)`);
    }
});

The code above will delete the record where the name equals Trevor.

You can run any of those files using the node command. But you should first make sure that you've installed the sqlite3 module:

$ npm install sqlite3

Next I'll use node to run the first file (that you could choose to call db.js).

$ node db.js
Inserted data with id 1

We'll see that a new record has been successfully inserted. If you list the directory contents, you'll also see that a new mydatabase.db file has been created.

You can always manually log into sqlite3 to see how things might have changed. I'll reference the mydatabase.db file so we can open it up right away.

$ sqlite3 mydatabase.db

Typing .tables within the SQLite interface will list all the existing tables in this database. In our case, it'll be the users table we created.

sqlite> .tables
users
sqlite>

Now I'll use the SQL select command to display a record. Here I'll use the asterisk to represent all records and specify the users table.

sqlite> SELECT * FROM users;
1|Trevor|25
sqlite>

We can see that record 1 containing Trevor who is 25 years old has been created. Great!

Finally, we can run the delete code which should remove Trevor altogether:

const deleteQuery = `DELETE FROM users WHERE name = ?`;
const deletedName = 'Trevor';
db.run(deleteQuery, [deletedName], function (err) {
    if (err) {
        console.error(err.message);
    } else {
        console.log(`Deleted ${this.changes} row(s)`);
    }
});

I should note that the db.run and db.close format I used for those methods can also be referred to as Database.run(), and database.close(). It's just a matter of preference - or, in my case, laziness. I'm a Linux admin, after all, and the very best admins are, in principle, lazy.

Summary

We've seen how use JavaScript to connect to a back end database, create a new table, and then add, modify, and delete records in that table. And we seem to have gotten away with it, too!

Now try this on your own computer. But play around with the values. Even better: build something practical.

This article comes from my Complete LPI Web Development Essentials Study Guide course. And there's much more technology goodness available at bootstrap-it.com

If you're looking for a tutorial to teach you the basics of Nodejs and the command line, you're in the right place.

You can use JavaScript to build almost any software (web, mobile, bots, and so on). The reason is that computers no longer depend on browsers only to understand JavaScript code. Check out this article to see How Computers Understand JavaScript Code.

Node.js is used to run backend applications that are written in JavaScript.

I will teach you how to build a command line application that can read, write, edit, and delete data using Node.js. It will not require connecting to external databases like MySQL, MongoDB, Postgresql, and so on. See the project here.

By the end of the article, you should be able to set up a basic Node project, manipulate files, use modules, navigate promises, collect input, and so on.

I also added videos to enhance your learning.

Prerequisites

You do not need any prior programming knowledge to understand this tutorial.

How the Finished Project Will Function

The application that we are going to build will be able to do the following:

• Check if a database exists
• Retrieve data from the database
• Add new data to the database
• Update database with new data
• Remove data from the database

How to Install Node and NPM

Please go to the Nodejs website and download the one recommended for all users. Install it after the download is complete.

Use the command below to check if the installation was successful:

• For Node

node -v

• For npm

npm -v

The installation is successful if each command returns a version number.

How to Setup a Node.js Project

The steps below will help you set up your project:

Open your terminal or CMD and create the project directory:

mkdir node_CLI_app

Navigate into the directory:

cd node_CLI_app

Initialize the project:

npm init

It will bring up some questions. Press the Enter button for every prompt.

A new file (package.json) should have been added to your project directory. We will use the file to add external code (module) to the project.

Add the following line before the closing curly brace (}) to enable ES6 import:

"type": "module"

That completes the project setup!

How to Install Dependencies

You will recall that the package.json file is for adding external code to the project. This external code is also called Dependencies, Modules, or Packages. It's written by other programmers (usually free of charge) to help others build applications faster. You will find a lot of these on the npm website.

We need two (2) packages for this project: inquirer and uuid. I will show you how to install them in this section.

Installing of packages follows this pattern:

npm install <package_name>

We can install more than one package at a time by separating the package names with a space:

npm install <package_name_1> <package_name_2> <package_name_3>

The install command can be replaced with i for convenience.

So run the following command to install the packages:

npm i inquirer uuid

Your package.json file should have the following lines of code added to it when the installation is complete:

  "dependencies": {
    "inquirer": "^9.1.4",
    "uuid": "^9.0.0"
  }

The version numbers may differ, but that’s fine.

You will also notice that a file (package.lock.json) and a folder (node_modules) have been added. You do not have to worry about them. Just know that they help to manage the external code we just added.

That completes the installation of dependencies!

How to Create a New File from the Terminal

You can create a file from the terminal using the following command:

• On Mac:

touch <file_name>

• On Windows:

echo.><file_name>

You can also create more than one file at a time by separating the files with a space. That is how we will generate the files for this project:

touch addData.js removeData.js retrieveData.js updateData.js queryDB.js dbFileCheck.js

Each of those files will play a unique role in the application.

• addData.js adds data to the database. It also fabricates the database file if it doesn’t exist.
• removeData.js removes selected data.
• retrieveData.js fetches all data.
• updateData.js edits data.
• queryDB.js checks if a database exists and executes a function passed to it.
• dbFileCheck.js confirms if the database file has been created.

There is one more file that we did not create: the database file (db.json). We will auto-generate it using our code.

How to Check if a File Exists

Node.js provides a built-in module for manipulating files – file system (fs). One of the methods that the module contains is the existsSync method. It returns true or false depending on if the file has been created. I will use that to check if the db.json file is in the project. See the code below:

  import fs from "fs";
  import { exit } from "process";  

  if (fs.existsSync("db.json")) {
    console.log("File exists!");
    exit(1);
  }

The exit method terminates a process.

That is what we want to do in the dbFileCheck.js file. However, we want to invert the result by adding a ! before the fs.existsSync method like this:

  import fs from "fs";
  import { exit } from "process";  

  if (!fs.existsSync("db.json")) {
    console.log("File does not exist!");
    exit(1);
  }

This will be necessary when building other functionalities like updating and deleting data.

So how will those files gain access to this code? It is through a modular structure. That entails bundling this code and making it accessible through other files in the project. The export command makes this possible:

import fs from "fs";
import { exit } from "process";

export default function dbFileCheck() {
  if (!fs.existsSync("db.json")) {
    console.log("Database is Empty. Create some data!");
    exit(1);
  }
}

The code above puts the code in a function (dbFileCheck) and exports it using the export command. This function can now be imported and used in other files within this project.

Note that the default keyword is necessary for the first export from a file.

How to Query the Database

Another method the file system has is the readFile method. It returns the content of any file passed to it.

The readFile method takes in two parameters: the file to be read and a callback function that returns the result of the operation.

We will use the following code to retrieve data from our database:

import fs from "fs";

fs.readFile("db.json", function (err, data) {
  if (err) {
    console.log(err);
  }
  console.log(data.toString());
});

The code above imports the file system module and tries to read the database file. If there is an error, it will return the error. If there are no errors, it will return the data it got.

The .toString() method attached to the data returned (data.toString()) is because the data retrieved is of the type buffer by default, which is not readable.

buffer output

Open your project in a code editor and paste that code into the queryDB.js file.

Run the command below to see if it is working:

node queryDB

The command above will execute every code in the queryDB.js. The .js extension is optional. It will run either way.

The result of that operation will be an error because we do not have the file.

You can create the db.json file, add some content, and check the output.

But we do not want our app to try to read the database file if it has not been generated. So use the existsSync method to check if the file has been created. See how I use it in the code below:

    import fs from "fs";

    if (fs.existsSync("db.json")) {
      fs.readFile("db.json", function (err, data) {
        if (err) {
          console.log(err);
        }
        console.log(data.toString());
      });
    } else {
      console.log("No data available!");
    }

The code above checks if the file exists by passing the file name (db.json) to the fs.existsSync method. If it is true, then it reads the file. If it is false, it returns a string.

Now that we have that clean code, we want to make it even more robust.

Since we are building a CRUD application, we must have access to and keep track of the data returned. I have introduced a new variable in the code below to make that happen:

    import fs from "fs";

    let info = [];
    if (fs.existsSync("db.json")) {
      fs.readFile("db.json", function (err, data) {
        if (err) {
          console.log(err);
        }
        info = JSON.parse(data.toString());
        console.log(info);
      });
    } else {
      console.log("No data available!");
    }

The code above now has a variable, info. It keeps track of the data returned. I passed the data through the JSON.parse method to convert the data from string to array.

We can now manipulate the info as we deem fit. We have to export the code and accept a function to make this possible. That function will take the info variable as input and then use it as required.

import fs from "fs";

export default async function queryDB(externalFunction) {
  try {
    let info = [];

    if (fs.existsSync("db.json")) {
      await fs.readFile("db.json", function (err, data) {
        info = JSON.parse(data.toString());
        console.log(info);

        if (err) {
          console.log(err);
          return;
        }

        if (externalFunction && !err) {
          externalFunction(info);
          return;
        }
      });
    } else {
      if (externalFunction) {
        externalFunction(info);
        return;
      }
    }
  } catch (error) {
    console.error(`Something Happened: ${error.message}`);
  }
}

This code takes in a function and executes it only if there are no errors. However, there will be one exception – when adding data. In that case, the database will be created.

The try…catch… block helps pick out errors, and the async await keywords are used when executing code that will take a long time to run.

The queryDB.js will no longer return any output when we execute the node queryDB command. But that is fine. We will trigger it from other files.

How to Add Data to a File

In this section, I will teach you how to add data to the store. The file for this section is the addData.js file.

We will start by importing all necessary modules:

import inquirer from "inquirer";
import fs from "fs";
import { v4 as uuidv4 } from "uuid";
import queryDB from "./queryDB.js";

Next, create the boilerplate for the function:

export default async function addData(info) {
  try {

  } catch (error) {
    console.log("Something went wrong!", error);
  }
}

This is similar to what we have done before now. All the code we would write next will go into the try… block. The info array passed into the function is coming from the queryDB file.

The first thing to do in the try… block is to collect the data to be stored. We will use inquirer to do that with the code below:

const answers = await inquirer.prompt([
      {
        type: "input",
        name: "name",
        message: "What's your name?",
      },
      {
        type: "number",
        name: "phone",
        message: "What's your phone?",
      },
      {
        type: "list",
        name: "age",
        message: "Are you an adult?",
        choices: [
          { name: "Y", value: "Adult" },
          { name: "N", value: "Minor" },
        ],
      },
    ]);