Javascript

Building full-stack React apps with Next.js API routes

Dec 17, 2021

5 min read

Besides Next.js being a great front-end framework for React, it also provides a simple way to build an API for your front-end - all in the same web app!

As of version 9, Next.js provides API routes that allows developers to create API endpoints using the Next.js folder structure. We can use API endpoints to build either a RESTful API, or a GraphQL API. This article will focus on a RESTful API for the sake of simplicity.

With Next.js API routes, there's no longer a need to set up a back-end Node.js server to build an API. Building out two separate projects for the front-end and back-end of an application introduces its own set of challenges. Next.js simplifies this process by becoming a full-stack web framework with the addition of API routes. Building and deploying a full-stack web app has never been faster and easier!

Setting up API routes

API routes go in the pages/api directory of a Next.js project.

When a file or folder is added to this pages/api folder, Next.js will create an API endpoint URL for it. Creating a pages/api/users.ts file will create an /api/users API endpoint. We can also create an /api/users API endpoint by creating a pages/api/users/index.ts file.

To create a dynamic API route for a specific user, we can create a pages/api/users/[id].ts file. This dynamic route will match requests such as /api/users/1.

Just like the pages folder maps its files and folders to URLs that can be visited in a web browser, the pages/api folder maps its files and folders to API endpoint URLs.

Creating API routes

To begin, let's create a new Next.js project called nextjs-full-stack.

npx create-next-app full-stack-nextjs

cd full-stack-nextjs

If you prefer using TypeScript with Next.js, you can use npx create-next-app --ts instead. For this article, we'll just use JavaScript.

Notice that newly created Next.js project contains a pages/api/hello.js file. An /api/hello API endpoint has already been provided for us. Let's run the project using npm run dev to try this API endpoint.

Visit http://localhost:3000/api/hello in a web browser. You should see the following response.

{ "name": "John Doe" }

Understanding API routes

Let's take a look at the code in the pages/api/hello.js file.

export default function handler(req, res) {
  res.status(200).json({ name: 'John Doe' })
}

The default export in files that are found within the api folder must be a function. Each function is a handler for a particular route. Asynchronous functions are also supported for cases where requests need to be made to external APIs or a database.

When running the Next.js project locally, it creates a Node.js server and passes the request and response objects from the server into the handler function of the requested endpoint.

A dynamic route

Let's create a pages/api/users/[id].js file to create an API route for a specific user. Let's add the following code within this file.

const users = [
	{ id: 1, name: 'John Smith' },
	{ id: 2, name: 'Jane Doe' },
];

export default (req, res) => {
  const { query: { id } } = req;

  res.json({ 
    ...users.find(user => user.id === parseInt(id)),
  });
}

For the purposes of creating an example, we mocked up a list of users within the file. More realistic usage might involve querying a database for the requested user.

The id value is retrieved from the request query parameter, and then used to find the corresponding user object in the list of users. Keep in mind that the id from the request is a string, so we must parse it to an integer in order to perform a user lookup by id on the users list.

Visit http://localhost:3000/api/users/1 in a web browser. You should see the following response.

{ "id": 1, "name": "John Smith" }

Returning an error

We can modify the user endpoint we just created to return an error when the requested user id is not found in a list of users.

const users = [
	{ id: 1, name: 'John Smith' },
	{ id: 2, name: 'Jane Doe' },
];

export default (req, res) => {
  const { query: { id } } = req;

  const user = users.find(user => user.id === parseInt(id));
  if (!user) {
    return res.status(404).json({
      status: 404,
      message: 'Not Found'
    });
  }

  res.json({ ...user });
}

Visit http://localhost:3000/api/users/3 in a web browser. You should see the following response since no user with an id of 3 exists.

{ "status": 404, "message": "Not Found" }

Handling multiple HTTP verbs

Next.js API routes allow us to support multiple HTTP verbs for the same endpoint all in one file. The HTTP verbs that we want to support for a single API endpoint are specified in the request handler function.

Let's create a pages/api/users/index.js file to create an API route for all users. We want this endpoint to support GET requests to get all users and POST requests to create users. Let's add the following code within this file.

export default (req, res) => {
  const { method } = req;

  switch (method) {
    case 'GET':
      res.json({ method: 'GET', endpoint: 'Users' });
      break;
    case 'POST':
      res.json({ method: 'POST', endpoint: 'Users' });
      break;
    default:
      res.setHeader('Allow', ['GET', 'POST']);
      res.status(405).end(`Method ${method} Not Allowed`);
      break;
  }
}

The req.method value will tell us what HTTP verb was used to make the request. We can use a switch statement to support multiple HTTP verbs for the same endpoint. Any HTTP requests that are not GET or POST, requests will enter the default case and return a 405 Method Not Allowed error.

Visit http://localhost:3000/api/users in a web browser. You should see the following response.

{ "method": "GET", "endpoint": "Users" }

We can use an API platform like Postman or Insomnia to test POST, PUT, and DELETE requests to this API endpoint.

Testing the POST request will return the following response.

{
  "method": "POST",
  "endpoint": "Users"
}

Testing PUT and DELETE requests will return Method Not Allowed errors with a 405 Method Not Allowed response code.

Using API routes from the front-end

Let's create a users/[id].js page to retrieve a specific user when the page loads, and then mimic a save profile operation when the form on the page is submitted.

We will use client-side rendering within Next.js for this page. Client-side rendering is when the client makes requests for API data. The approach used in this example can also apply for pages that use server-side Rendering (SSR).

import { useEffect, useState } from 'react';
import { useRouter } from 'next/router';

export default function User() {
  const router = useRouter();
  const { id } = router.query;
  const [name, setName] = useState();

  // GET request to get a user
  useEffect(() => {
    // wait for the useRouter hook to asynchronously get the query id
    if (!id) {
      return;
    }

    const fetchUser = async () => {
      const response = await fetch(`/api/users/${id}`, {
        method: "GET",
        headers: {
          "Content-Type": "application/json"
        },
      });

      if (!response.ok) {
        throw new Error(`Error: ${response.status}`);
      }

      const user = await response.json();
      setName(user?.name);
    }

    fetchUser();
  }, [id]);

  // POST request to mimic the saving of a user
  const onSubmit = async (e) => {
    e.preventDefault();
    const response = await fetch("/api/users", {
      method: "POST",
      headers: {
        "Content-Type": "application/json"
      },
      body: JSON.stringify({}),
    });

    if (!response.ok) {
      throw new Error(`Error: ${response.status}`);
    }

    const data = await response.json();
    console.log('POST: ', data);
  };

  return (
    <div>
      <h1>User Form</h1>
      <form onSubmit={onSubmit}>
        <div>
          <label htmlFor="name">Name</label>
          <input 
            type="text" 
            id="name" 
            name="name" 
            value={name ?? ''} 
            onChange={(e) => setName(e.target.value)}
          />
        </div>
        <button type="submit">Submit</button>
      </form>
    </div>
  );
}

To retrieve a user by id when the page loads, we can use the React useEffect hook with the id as a dependency. The browser-supported Fetch API is used to make a GET request to /api/users/[id]. Async/await is used to wait for this asynchronous request to complete. Once it is completed, the user's name is saved to the component state using setName, and displayed within the input text box.

When the form is submitted, a POST request is made to the /api/users API route that we created earlier. To keep things simple, the response of the request is then logged to the console.

Conlusion

Next.js makes it fast and easy to build an API for your next project. A very good use case to get started with Next.js API routes is for the implementation of CRUD operations to handle form input.

API endpoints are created as Node.js serverless functions. You can build out your entire application's API with Next.js API routes. Go ahead and build something awesome with them!

This Dot is a consultancy dedicated to guiding companies through their modernization and digital transformation journeys. Specializing in replatforming, modernizing, and launching new initiatives, we stand out by taking true ownership of your engineering projects.

We love helping teams with projects that have missed their deadlines or helping keep your strategic digital initiatives on course. Check out our case studies and our clients that trust us with their engineering.

Steven Spadotto

@stevenspads @stevenspads

Maximizing Routing Flexibility with Next.js Parallel and Intercepting Routes

Maximizing Routing Flexibility with Next.js Parallel and Intercepting Routes Introduction: Next.js, a powerful React framework, offers two essential features - Parallel Routes and Intercepting Routes - that enable developers to create highly dynamic and seamless user experiences in their applications. In this blog post, we will explore both Parallel Routes and Intercepting Routes, highlighting their functionalities, use cases, and how they can be combined to enhance application routing. What are Parallel Routes? Parallel Routes in Next.js allow the rendering of multiple pages within a shared layout. Rather than navigating to a completely separate page, Parallel Routes enable the simultaneous rendering of different pages based on certain conditions such as user roles or tab navigation. By leveraging named slots, defined using the @folder convention, multiple pages can be seamlessly integrated into a single layout, enhancing user experience and reducing code duplication. How to Use Parallel Routes: To utilize Parallel Routes in Next.js, you must define named slots for the desired pages within your application's folder structure. These slots are then passed as props to a shared parent layout component. For example, consider a social networking application where two pages, feed and notifications, must be rendered within a common layout. You can define Parallel Routes using the following structure: ` The layout component in app/layout.js will accept the @feed and @notifications slots as props and render them alongside the children prop. Here's an example of the layout component: ` It's important to note that slots do not affect the URL structure and are not considered route segments. This means the URL would be /mypage/@feed/views for a route like /mypage/views since @feed is a slot. Also, to prevent the application from rendering nothing or throwing an error, we could use the default.tsx file: ` In this example, the default.tsx file specifies the default content (or fallback) to render when none of the named slots match the current route. It acts as a catch-all for routes without a corresponding slot. Some Use Cases: *Conditional Routes:* Parallel Routes can conditionally render routes based on certain conditions, such as user roles. For example, you can render a different dashboard page for admins and users. This can be achieved by creating a layout component specific to the dashboard and checking the user role to determine which slot to render. *Tab Groups:* You can utilize Parallel Routes to create tabbed navigation within a section. This is especially useful for analytics or multi-page views. Adding a layout inside a slot allows users to navigate between different pages within that slot independently. *Loading and Error UI:* Parallel Routes can be independently streamed, allowing you to define custom error and loading states for each route. This enables better control over the user experience by providing distinct feedback for different app sections. *Modals:* Parallel Routes can be combined with Intercepting Routes to create modals with shareable URLs, preserved context on refresh, and customized navigation behavior. By intercepting certain routes and rendering them within a modal component, you can create a seamless modal experience. Understanding Intercepting Routes: Intercepting Routes in Next.js allows you to load content from another route within the current layout without changing the URL or refreshing the page. Using the (..) Convention: Intercepting routes are defined using the (..) convention, which is similar to the relative path convention ../ but for route segments. The convention allows for matching segments on the same level (.), one level above (..), two levels above (..)(..), or from the root app directory (...). For example, to intercept the photo segment from within the feed segment, you can create a (..)photo directory. Integrating Intercepting Routes with Parallel Routes - Modals: One powerful use case for Intercepting Routes is creating modals, which can be combined with Parallel Routes to solve common challenges such as making the modal content shareable through a URL, preserving context on page refresh, and handling backward and forward navigation. Let's make an example: ` Our folder structure will be: In this example, when a user clicks on a photo within the /gallery page, the route /photo/:photoId will be intercepted and rendered within the (..)photo directory, overlaying the gallery content. This means that the photo route is only one segment level higher despite being two file-system levels higher. In the example above, the path to the photo segment can use the (..) matcher since @modal is a slot and not a segment. Common Use Cases - Beyond Modals: Intercepting Routes can also be utilized in other scenarios. Some examples include opening a login modal in a top navbar while having a dedicated /login page, or opening a shopping cart in a side modal for better accessibility or creating wizards or multi-step forms within a single page. The possibilities are endless. Conclusion Next.js Parallel and Intercepting Routes offer powerful methods for enhancing the routing capabilities of your applications. With Parallel Routes, multiple pages can be seamlessly integrated within a shared layout, simplifying navigation and enhancing user experience. By incorporating Intercepting Routes, you can create dynamic overlays like modals, enabling content from different routes to be displayed within the current layout. By leveraging these features, you can unlock exciting possibilities and take your Next.js applications to new heights of user engagement....

Apr 5, 2024

3 mins

NextJSJavaScript

Exploring the Hidden Gems of the Next Image Component: What You Might Be Overlooking

Welcome to a journey of discovery where we'll explore the often-overlooked capabilities of the Next.js Image component. At first glance, this component might seem like a straightforward tool, merely enhancing performance compared to a regular img tag. However, there's more to it than meets the eye. In this blog post, we'll uncover the magic of some features of the Next.js Image component. It's easy to use, yes, but it also packs a punch with features that go beyond simple image rendering. These hidden features can significantly impact your project, and missing them could mean not fully utilizing the component's potential. Let's dive into this exploration, unraveling the subtle yet powerful aspects of the Next.js Image component that are easy to overlook. So, without further delay, let's get started! Size First up, let's chat about width and height. These are rules for how big your image shows on the screen. You gotta use them most of the time. But hey, if you're pulling in an image directly into your code (that's what we call 'static importing') or you want your image to just fill up whatever space it's in (using the 'fill' prop), then you can skip these rules. Neat, right? But that's not all there's to it. You see, when Next.js fetches the image from the server, it does something behind the scenes. It doesn’t just grab any size of the image. Instead, Next.js is smart and picks the best size that fits the spot on your webpage. This means your images load faster and look just right, whether on a big desktop screen or a small phone screen. It's like having a personal assistant for your images, making sure they are always looking their best and not slowing down your site. Here's a part that's easy to miss: Next.js uses a feature called 'srcset' to decide which image size to download from the server. By default, Next.js uses the following default: ` So, imagine you have an image that's 75 pixels wide. Next.js will look at this list and pick the closest size. In our case, with these default settings, it would download the 96-pixel version. This occurs because Next.js selects the smallest available size from the list that exceeds the original's width, ensuring the image remains clear on all devices; even if your image is a bit smaller or larger, Next.js picks the nearest size from this list. This is important to know because if you are looking to get the most performant image possible, you should be aware of these size values. By understanding how Next.js selects the image size, you can better tailor your images to match these presets. This way, you ensure that your site is not only loading the appropriate image size for different devices but also optimizing for speed and efficiency. Keeping an eye on these sizes helps you balance between image quality and fast loading times, which is key for a great user experience on your site. Quality Now, let's highlight something about image quality. It's often overlooked, but by default, Next.js sets the image quality to 75. Sure, you can tweak this with the quality prop, but here's the catch: bumping up the quality to 100 will significantly increase the image's file size. This means your images will look super sharp, but they'll also take longer to load. It's all about finding that sweet spot where your images look great without slowing down your website. Remember, a faster site often means a better experience for your visitors. My advice is to always check what is better for you in each situation. Ask yourself: Consider whether it's more beneficial to opt for larger images at a slightly reduced quality, in alignment with the “srcset” configurations we explored, or if it's preferable to enhance the image quality, even if it means working with smaller dimensions? It's a balancing act. Usually, cranking up the quality to 100 isn't the best move because it makes the image file really big, which can slow down your site. It's all about making smart choices. Go for a quality that makes your images look good without burdening your site's load time. Sometimes, a slightly lower quality image, but well optimized, can be way more effective than a perfect but sluggish, high-quality image. Loader The loader prop in Next.js is a key player. It's not just about fetching images; it’s about fetching them smartly and securely. When using images from different places, like a CMS or your server, the loader prop helps you manage them efficiently and safely. For instance, say you have images on Contentful. Next.js doesn't automatically know the best way to fetch these, but with a custom loader, you can define this process. This loader optimizes your images, selecting the right format, width, and quality. Your images not only look great but load faster, too. Remember, when fetching images from external sources, it's crucial to use remotePatterns (inside your next.config file) for security reasons. This ensures your site stays safe while handling images from outside. This approach is scalable and saves time. You set up the loader once, and it works for all your images, making your site efficient and your code neat. Here’s an example: ` ` Placeholder Prop A little-known yet impactful feature of the Next.js Image component is the placeholder prop. It's all about improving the user experience while your images are loading. Imagine visiting a website and waiting for images to load – it can be a bit dull, right? The placeholder prop can make this wait a lot more pleasant. You can use this prop to display a blur effect or a solid color before the image fully loads. This creates a smoother visual experience. The blur placeholder is particularly popular because it gives a sneak peek of the image without revealing all the details. It's like a teaser, building anticipation for what's to come. Here’s how you can use it: ` In this example, blurDataURL is a small, low-quality version of your image that loads much faster. Once the actual image is ready, it seamlessly replaces the blur. This approach significantly enhances the perceived loading speed and keeps your users engaged. Incorporating the placeholder prop can make a big difference in how professional and polished your site feels, especially on slower connections where image load times are noticeable. Conclusion The Next.js Image component is a powerful tool that goes beyond simple image rendering. By understanding its hidden features and capabilities, you can optimize your project for performance and user experience. From utilizing the 'width' and 'height' properties to ensuring the right image quality and using the 'loader' prop for efficient image fetching, there are several aspects to consider. Additionally, the 'placeholder' prop can enhance the user experience by displaying a blur effect or solid color while images load. By exploring these often-overlooked features, you can unlock the full potential of the Next.js Image component and create a more engaging and optimized website....

Feb 9, 2024

5 mins

UXJavaScriptNextJS

Introduction to RESTful APIs with NestJS

Welcome to an introduction to RESTful APIs with NestJS. Understanding JavaScript and TypeScript will make it easier to follow the directions in this article, but you don't necessarily need to be proficient. NestJS is one of the most rapidly growing frameworks for building Node.js server-side applications. Companies such as *Roche*, *Adidas*, and *Autodesk*, all trust NestJS when it comes to building efficient and scalable server-side applications. NestJS is based heavily on *Angular*, and uses Angular-like modules, services, controllers, pipes, and decorators. This allows NestJS to help developers create scalable, testable, loosely coupled, and easily maintainable applications. NestJS was built with TypeScript, but it can also support pure JavaScript development. NestJS offers a level of abstraction above two very popular Node.js frameworks, either *Express.js* or *Fastify*. This means that all of the great middleware that are available for Express.js and Fastify can also be used with NestJS. The best way to get familiar with NestJS is to build a basic RESTful API with CRUD (Create, Read, Update, and Delete) functionality. This is exactly what we'll be doing together in this article. We'll be building a simple RESTful API for a Blog, with endpoints to handle CRUD operations on blog posts. Getting Started Code editor Using Visual Studio Code as a code editor can help speed up NestJS development because of its smart IntelliSense and great TypeScript support. In Visual Studio Code, make sure that you have the following user setting by going to File / Preferences / Settings, and searching for the user setting named typescript.preferences.importModuleSpecifier. Make sure to set it to relative as seen below. ` This will allow Visual Studio Code to use relative paths rather than absolute paths when auto-importing. Using absolute path imports in our application can lead to problems if and when our code ends up in a different directory. Insomnia Insomnia is a useful API testing tool that we will use to test the NestJS API that we will be building. The NestJS CLI To get started with NestJS, let's install the Nest CLI. The Nest CLI is a command-line interface tool that makes it easy to develop, and maintain NestJS applications. It allows us to run our application in development mode, and to build and bundle it for a production-ready release. ` Creating a new NestJS project With the Nest CLI now installed, we can use it to create a new project. ` This command will create a new project directory called rest-api. It will create a base structure for our project, and add in the following core Nest files: - app.controller.ts: A controller with a single route. - app.controller.spec.ts: The controller's unit tests. - app.module.ts: The root module of our application. - app.service.ts: A service for the AppModule's business logic. - main.ts: The entry file of our application. The initial project structure created by the Nest CLI encourages us to follow the common convention of keeping each module in its own directory. Testing the sample endpoint The installation of NestJS comes with a sample API endpoint that we can test by making a request to it. If we open app.controller.ts, we can see that there is a GET endpoint that was created for us with the @Get() decorator. It returns a 'Hello World!' string. ` Let's run npm run start:dev from our project folder. This will run our NestJS app in watch mode, which provides live-reload support when application files are changed. Once NestJS is running, let's open http://localhost:3000 in our web browser. We should see a blank page with the Hello World! greeting. We can also use API testing tools such as Insomnia to make a GET request to http://localhost:3000. We should get the same Hello World! greeting as our result. Let's remove this endpoint since it was only added by the Nest CLI for demo purposes. Go ahead and delete app.controller.ts, app.service.ts, and app.controller.spec.ts. Also, delete all references to AppController and AppService in app.module.ts. Creating a feature module The architectural design of NestJS encourages feature modules. This feature-based design groups the functionality of a single feature in one folder, registered in one module. This design simplifies the codebase and makes code-splitting very easy. Module We create modules in NestJS by decorating a class with the @Module decorator. Modules are needed to register controllers, services, and any other imported sub-modules. Imported sub-modules can have their own controllers, and services, registered. Let's use the Nest CLI to create the module for our blog posts. ` This gives us an empty PostsModule class in the posts.module.ts file. Interface We will use a TypeScript interface to define the structure of our JSON object that will represent a blog post. An interface is a virtual or abstract structure that only exists in TypeScript. Interfaces are used only for type-checking purposes by the TypeScript compiler. TypeScript interfaces do not produce any JavaScript code during the transpilation of TypeScript to JavaScript. Let's use the Nest CLI to create our interface. ` These commands allow us to create a posts.interface.ts file in the feature-based folder for our blog posts, which is /src/posts. The TypeScript interface keyword is used to define our interface. Let's make sure to prefix it with export to allow this interface to be used throughout our application ` From the command-line prompt, let's reset our current working directory back to the root folder of our project by using the following command. ` Service Services are classes that handle business logic. The PostsService that we will be creating will handle the business logic needed to manage our blog posts. Let's use the Nest CLI to create the service for our blog posts. ` This will give us an empty PostsService class in the posts.service.ts file. The @Injectable() decorator marks the PostsService class as a provider that we can register in the providers array of our PostsModule, and then inject into our controller class. More on this later. Controller Controllers are classes that handle incoming requests and return responses to the client. A controller can have more than one route or endpoint. Each route or endpoint can implement its own set of actions. The NestJS routing mechanism handles the routing of requests to the right controller. Let's use the Nest CLI to create the controller for our blog posts. ` This will give us an empty PostsController class in the posts.controller.ts file. Let's inject our PostsService into the constructor of the PostsController class. ` NestJS uses dependency injection to set up a reference to PostsService from within our controller. We can now use the methods provided by PostsService by referencing this.postsService from within our controller class. Registering our controller and service Let's make sure that our PostsModule registers our PostsController and PostsService. The nest generate service post and nest generate controller post commands that we ran earlier have automatically registered the PostsService and PostsController classes in the PostsModule for us. ` NestJS uses the term providers to refer to service classes, middleware, guards, and more. If the PostsService class needs to be made available to other modules within our application, we can export it from PostsModule by using the exports array. This way, any module importing the PostsModule will be able to use the PostsService. ` Importing PostsModule into AppModule We now have one cohesive and well-organized module for all the functionality related to our blog posts. However, all the functionality that will be provided by our PostsModule is not available to our application unless the AppModule imports it. If we revisit the AppModule, we can see that the PostsModule has been automatically added to the imports array by the nest generate module post command that we ran earlier. ` Adding Service and Controller logic Our PostsService and PostsController have no functionality implemented at the moment. Let's now implement our *CRUD* endpoints and their corresponding logic while adhering to RESTful standards. NestJS makes it easy to use MongoDB (using the @nestjs/mongoose package), or PostgreSQL (using *Prisma* or *TypeORM*) to persist and manage our application's data. However, for the sake of simplicity, let's create a local array in our service to mock a database. ` A service, or provider, as NestJS refers to them, can have its scope configured. By default, a service has a *singleton* scope. This means that a single instance of a service is shared across our entire application. The initialization of our service will occur only once during the startup of our application. The default singleton scope of services means that any class that injects the PostsService will share the same posts array data in memory. Get all posts Let's add a method to our PostsService that will return all of our blog posts. ` Let's add a method to our PostsController that will make the logic of the service's findAll() method available to client requests. ` The @Get decorator is used to create a GET /posts endpoint. The /posts path of the request comes from the @Controller('posts') decorator that was used in order to define our controller. Get one post Let's add a method to our PostsService that will return a specific blog post that a client may be looking for. If the id of the requested post is not found in our list of posts, let's return an appropriate 404 NOT FOUND HTTP error. ` Let's add a method to our PostsController that will make the logic of the service's findOne() method available to client requests. ` The @Get decorator is used with a parameter as @Get(':id') here to create a GET /post/[id] endpoint, where [id] is an identification number for a blog post. @Param, from the @nestjs/common package, is a decorator that makes route parameters available to us as properties in our method. @Param values are always of type string. Since we defined id to be of type number in TypeScript, we need to do a string to number conversion. NestJS provides a number of pipes that allow us to transform request parameters. Let's use the NestJS ParseIntPipe to convert the id to a number. Create a post Let's add a method to our PostsService that will create a new blog post, assign the next sequential id to it, and return it. If the title is already being used by an existing blog post, we will throw a 422 UNPROCESSABLE ENTITY HTTP error. ` Let's add a method to our PostsController that will make the logic of the service's create method available to client requests. ` The @Post decorator is used to create a POST /post endpoint. When we use the NestJS decorators for the POST, PUT, and PATCH HTTP verbs, the *HTTP body* is used to transfer data to the API, typically in JSON format. We can use the @Body decorator to parse the *HTTP body*. When this decorator is used, NestJS will run JSON.parse() on the *HTTP body* and provide us with a JSON object for our controller method. Within this decorator, we declare post to be of type Post because this is the data structure that we are expecting the client to provide for this request. Delete a post Let's add a method to our PostsService that will delete a blog post from our in-memory list of posts using the JavaScript splice() function. A 404 NOT FOUND HTTP error will be returned if the id of the requested post is not found in our list of posts. ` Let's add a method to our PostsController that will make the logic of the service's delete method available to client requests. ` Update a post Let's add a method to our PostsService that will find a blog post by id, update it with newly submitted data, and return the updated post. A 404 NOT FOUND HTTP error will be returned if the id of the requested post is not found in our list of posts. A 422 UNPROCESSABLE ENTITY HTTP error will be returned if the title is being used for another blog post. ` Let's add a method to our PostsController that will make the logic of the service's update method available to client requests. ` We use the @Put decorator to make use of the HTTP PUT request method. PUT can be used to both create and update the state of a resource on the server. If we know that a resource already exists, PUT will replace the state of that resource on the server. Testing our feature module Let's start our development server using npm run start:dev. Then, let's open the Insomnia application to test the API endpoints that we created for the PostsModule. Get all posts Let's make a GET request to http://localhost:3000/posts. The result should be a 200 OK success code with an empty array. Create a post Let's make a POST request to http://localhost:3000/posts using the following as our JSON body. ` We should get a successful 201 Created response code, along with a JSON representation of the post that was created, including the id field that has been automatically generated. Get a post Let's make a GET request to http://localhost:3000/posts/1. The result should be a successful 200 OK response code, along with the data for the post with an id of 1. Update a post Let's make a PUT request to http://localhost:3000/posts/1 using the following as our JSON body. ` The result should be a successful 200 OK response code, along with a JSON representation of the post that was updated. Delete a post Let's make a DELETE request to http://localhost:3000/posts/1. The result should be a successful 200 OK response code with no JSON object returned. Logging NestJS makes it easy to add logging to our application. Rather than using console.log() statements, we should use the Logger class provided by NestJS. This will provide us with nicely formatted log messages in the Terminal. Let's add logging to our API. The first step is to define the logger in our service class. ` With the logger now defined, we can add log statements in our service class. Here is an example of a log statement that we can add as the first line of the findAll() method in the PostsService class. ` Such statements provide us with a convenient log message in the Terminal every time a service method is called during a client's request to our API. When a GET /posts request is sent, we should see the following message in the Terminal. ` Swagger NestJS makes it easy to add the *OpenAPI* specification to our API using the NestJS *Swagger* package. The OpenAPI specification is used to describe RESTful APIs for documentation and reference purposes. Swagger setup Let's install Swagger for NestJS. ` Swagger configuration Let's update the main.ts file that bootstraps our NestJS application by adding Swagger configuration to it. ` With our NestJS app running, we can now go to http://localhost:3000/api to view the Swagger documentation for our API. Notice that default is displayed above the routes for our posts. Let's change that by adding @ApiTags('posts') right below @Controller('posts') in our PostsController class. This will replace default with posts to indicate that this set of endpoints belongs to the posts feature model. ` ApiProperty Let's make the properties of our PostModel interface visible to Swagger. We do so by annotating fields with the ApiProperty() decorator, or the ApiPropertyOptional() decorator for optional fields. To use these decorators, we must first change our interface to a class in the posts.interface.ts file. ` Within the ApiProperty() decorator applied to each field, we describe the field type. The id field is optional since we don't know of a new blog post's id when creating it. A date-time string format is used for the date field. These changes allow the PostModel structure to be documented within Swagger. With our NestJS app running, we can now go to http://localhost:3000/api to view the documentation of the PostModel. ApiResponse Let's use the @ApiResponse() decorator for Swagger to document all the possible responses from our API's endpoints. This will be helpful for informing users of our API what responses they can expect to receive by calling a given endpoint. We will be making these changes in the PostsController class. For the findAll method, let's use the @ApiOkResponse() decorator to document a 200 OK success response. ` For the findOne method, let's use the @ApiOkResponse() decorator to document a 200 OK response when the post is found. Let's use the @ApiNotFoundResponse() decorator to document a 404 NOT FOUND HTTP error when a post is not found. ` For the create method, let's use the @ApiCreatedResponse() decorator to document a 201 CREATED response when a post is created. Let's use the @ApiUnprocessableEntityResponse() decorator to document a 422 UNPROCESSABLE ENTITY HTTP error when a duplicate post title is found. ` For the delete method, let's use the @ApiOkResponse() decorator to document a 200 OK response when a post is deleted. Let's use the @ApiNotFoundResponse() decorator to document a 404 NOT FOUND HTTP error when the post to be deleted is not found. ` For the update method, let's use the @ApiOkResponse() decorator to document a 200 OK response when a post is updated. Let's use the @ApiNotFoundResponse() decorator to document a 404 NOT FOUND HTTP error when the post to be updated is not found. Let's use the @ApiUnprocessableEntityResponse() decorator to document a 422 UNPROCESSABLE ENTITY HTTP error when a duplicate post title is found. ` After saving these changes, all response codes and their related descriptions should now be listed for each endpoint on the Swagger web page at http://localhost:3000/api. We could also use Swagger instead of Insomnia to test our API. By clicking on the "Try it out" button that appears under each endpoint on the Swagger web page, we can see if they are working as expected. Exception filter Exception filters give us full control over the exceptions layer of NestJS. We can use an exception filter to add custom fields to a HTTP exception response body or to print out logs of every HTTP exception that occurs to the Terminal. Let's create a new filters folder in the /src folder, as well as a new file called http-exception.filter.ts within it. Let's add the following class in this file. ` This class makes use of the NestJS logger to print a warning message to the Terminal whenever a HTTP exception occurs. It also returns two custom fields within the response body whenever a HTTP exception occurs. The timestamp field reports when the exception occurred, and the endpoint field reports which route triggered the exception. In order to apply this filter, we need to decorate the PostsController with @UseFilters(new HttpExceptionFilter()). ` After saving these changes, NestJS will reload our application for us. If we use Insomnia to send a PUT /posts/1 request to our API, it should trigger a 404 NOT FOUND HTTP error, since no blog posts exist for updating in our application when it starts. The HTTP exception response body that is returned to Insomnia should now contain the timestamp and endpoint fields. ` We should also see the following line printed out to the Terminal. ` Summary In this article, we saw how NestJS makes back-end API development fast, simple, and effective. The NestJS application structure has helped us build a very well-organized project. We covered a lot, so let's recap what we learned: - How to use the NestJS CLI. - How to build feature modules in NestJS. - How to use services and controllers. - How to test an API with Insomnia. - How to add logging to NestJS apps. - How to use Swagger for documenting and previewing NestJS APIs. - How to get full control of HTTP exceptions in NestJS. Happy developing with NestJS! Code Visit the following GitHub repository in order to access the code featured in this article....

Sep 15, 2021

13 mins

NestJSJavaScriptNodeJS

6 Steps to AI Adoption: Building with AI APIs

Tracy Lee, Jerome Hardaway, and Rob Ocel continue their six part series on the six steps for AI adoption. In this episode they discuss AI API integration and better building with AI models. One key takeaway was the importance of choosing the right tools for specific tasks. Jerome emphasized the significance of using content moderation APIs for filtering inappropriate content as an example. These tools help developers improve user experiences by ensuring content accuracy and appropriateness. However, Jerome also warned against blindly relying on AI tools and encouraged programmers to assess their benefits and limitations before implementation. The discussion also touched on how AI impacts coding abilities and problem-solving. AI-powered tools can boost developer productivity by automating repetitive tasks and offering helpful suggestions. Yet, it's important to strike a balance and not become overly dependent on AI, which could hinder critical thinking and problem-solving skills crucial for programmers. One challenge discussed was the difficulty of working with poorly documented APIs, which makes it hard for developers to understand and utilize AI tools effectively. While AI has the potential to enhance productivity and user experiences, it's important for developers to choose the right tools and avoid over-reliance. By carefully evaluating AI tools and investing in clear documentation, developers can leverage AI effectively to improve their coding abilities and problem-solving skills. Download this episode here!...

Apr 15, 2024

2 mins

AIArtificial Intelligence

Building full-stack React apps with Next.js API routes

Setting up API routes

Creating API routes

Understanding API routes

A dynamic route

Returning an error

Handling multiple HTTP verbs

Using API routes from the front-end

Conlusion

Steven Spadotto

You might also like

Maximizing Routing Flexibility with Next.js Parallel and Intercepting Routes

Exploring the Hidden Gems of the Next Image Component: What You Might Be Overlooking

Introduction to RESTful APIs with NestJS

6 Steps to AI Adoption: Building with AI APIs

You might also like

Maximizing Routing Flexibility with Next.js Parallel and Intercepting Routes

Exploring the Hidden Gems of the Next Image Component: What You Might Be Overlooking

Introduction to RESTful APIs with NestJS

6 Steps to AI Adoption: Building with AI APIs