Building basic API's with Express.js

––– views

By Max Campbell

So you want to build an API? This tutorial is going to show you how to build an API using Express.js & Node.js. Today you are going to build an API which returns images of art while automagically resizing them.

To get started clone the repo using:

git clone https://github.com/maxall41/basic-art-image-api

git clone https://github.com/maxall41/basic-art-image-api

Once you have done that you can open up your favorite text editor mine is vscode and open up the initial folder inside of that repo once you have done that run this to install the required packages:

npm install

npm install

Once you have installed all the packages you can startup the app using:

npm run start

npm run start

Now if you go to:

http://localhost:3000/api/art

http://localhost:3000/api/art

You should see 🖼 so we better get to work implementing the actual API!

Let's start by looking at the file tree:

initial/
  - src/
    - api/
      index.ts | This loads our routes
      - routes/
        art.ts | This defines our routes
    - art/ | We are going to use this to hold our images
      ...
    - config/
      index.ts | This holds some of our config stuff like the default image size if it's not provided
    - loaders/ | This is used to initalize our application and the express.js server
      ...
    - services/ | This holds our services so we can seperate our logic from our route handlers
      image.ts | Handles image logic

initial/
  - src/
    - api/
      index.ts | This loads our routes
      - routes/
        art.ts | This defines our routes
    - art/ | We are going to use this to hold our images
      ...
    - config/
      index.ts | This holds some of our config stuff like the default image size if it's not provided
    - loaders/ | This is used to initalize our application and the express.js server
      ...
    - services/ | This holds our services so we can seperate our logic from our route handlers
      image.ts | Handles image logic

As you can see it looks complicated but it's actually pretty simple now that you know a little bit more about how this works lets get started implementing the API.

Image.ts service:

So to get started where going to install sharp which is an image processing library with native bindings for better performance you can install it like this:

npm install sharp

npm install sharp

And then you can import it like this in the image.ts file under services/. Also make sure to import the filesystem into node!

import sharp from 'sharp';
import fs from 'fs';

import sharp from 'sharp';
import fs from 'fs';

So to implement the resizeImage function we can do this:

public async resizeImage(path: string, x: number, y: number) {
		// Resize image using sharp and save it as a buffer
		const image = await sharp(path).resize(x, y).toBuffer();
		// Return the buffer
		return image;
}

public async resizeImage(path: string, x: number, y: number) {
		// Resize image using sharp and save it as a buffer
		const image = await sharp(path).resize(x, y).toBuffer();
		// Return the buffer
		return image;
}

This resizes the image and converts the output to a buffer to return to the user. You can think of a buffer like a big array of ones and zeroes that represent our resized image.

Now we can go ahead and implement the pickRandomFileInDirectory function which picks a random file in a directory and returns the file's name we can implement it like this:

public async pickRandomFileInDirectory(path: string) {
		// Get all files in directory
		const files = fs.readdirSync(path);
		// Pick random file in directory
		const file = files[Math.floor(Math.random() * files.length)];
		// Return the file name
		return file;
}

public async pickRandomFileInDirectory(path: string) {
		// Get all files in directory
		const files = fs.readdirSync(path);
		// Pick random file in directory
		const file = files[Math.floor(Math.random() * files.length)];
		// Return the file name
		return file;
}

This grabs the names of all the files in a directory and then we pick a random one and return it.

And that's it for the image.ts service!

API Route handling

The route handling is pretty simple we use celebrate to validate the query data in the request. We validate the data x and y as numbers. We first use the pickRandomFileInDirectory function to pick a random file in the art/ directory after that we use resizeImage to resize the image and return the image buffer to the user.

import { Router, Request, Response } from 'express';
import ImageService from '@/services/image';
import { Container } from 'typedi';
import path from 'path';
import config from '@/config';
import { celebrate, Joi } from 'celebrate';
const route = Router();
export default (app: Router) => {
	app.use('/art', route);

	route.get(
		'/',
		celebrate({
			query: Joi.object({
				x: Joi.number(),
				y: Joi.number()
			})
		}),
		async (req: Request, res: Response) => {
			// Get the image service
			const imageService = Container.get(ImageService);
			// Pick random image
			const image = await imageService.pickRandomFileInDirectory(path.join(__dirname, '../../art'));
			const bufferImage = await imageService.resizeImage(
				path.join(__dirname, '../../art/' + image),
				//@ts-ignore
				parseInt(req.query.x || config.defaultImageSize),
				//@ts-ignore
				parseInt(req.query.y || config.defaultImageSize)
			);
			return res.send(bufferImage);
		}
	);
};

import { Router, Request, Response } from 'express';
import ImageService from '@/services/image';
import { Container } from 'typedi';
import path from 'path';
import config from '@/config';
import { celebrate, Joi } from 'celebrate';
const route = Router();
export default (app: Router) => {
	app.use('/art', route);

	route.get(
		'/',
		celebrate({
			query: Joi.object({
				x: Joi.number(),
				y: Joi.number()
			})
		}),
		async (req: Request, res: Response) => {
			// Get the image service
			const imageService = Container.get(ImageService);
			// Pick random image
			const image = await imageService.pickRandomFileInDirectory(path.join(__dirname, '../../art'));
			const bufferImage = await imageService.resizeImage(
				path.join(__dirname, '../../art/' + image),
				//@ts-ignore
				parseInt(req.query.x || config.defaultImageSize),
				//@ts-ignore
				parseInt(req.query.y || config.defaultImageSize)
			);
			return res.send(bufferImage);
		}
	);
};

Adding the config

Now you just need to configure a value to use for the size of the image in case it's not defined. Todo this just open up config/index.ts and add something like this in if you want more control over the fault size you can define the x and y defaults separately

defaultImageSize: 100,

Conclusion

Now you are done! You can open up the demo.html file in the github repo that you cloned to see a quick example of using the API

Using the API is pretty simple in the route handling code we grab the x and y from the URL query params and use those to resize the image so we can pass them like this:

http://localhost:3000/api/art?x=99&y=200

http://localhost:3000/api/art?x=99&y=200

Or because if they are not defined we default to the setting in the config file just like this:

http://localhost:3000/api/art

http://localhost:3000/api/art

You can even do something like this and only pass one of the size params

http://localhost:3000/api/art?x=150

http://localhost:3000/api/art?x=150