seanlowe/services-api

A simple API project assigned as a take home project.

---

Description

An API to handle CRUD operations for a database record called a "Utility". Updating a Utility creates a "Version", which is a copy of the Utility as it was before it was updated. The API supports pagination, filtering, and sorting (in a limited sense).

This project was written in TypeScript on top of NodeJS with the Nest.JS framework, making use of TypeORM and PostgreSQL as additional tools.

---

Installation

$ npm install

---

Running the API

# set up the database
$ npm run db:build

# start up the server
$ npm run start

---

API Functionality

Routes

METHOD	ROUTES	Returns
GET	/utility	list of all Utility records
	/utility?parameter=value	list of all Utility records that match the query parameters (see below)
	/utility/{id}	a singular Utility record with id = id
	/utility/{id}/versions	list of all Version records tied to the Utility with id
	/versions	list of all Version records
POST	/utility	the newly created Utility record
PUT	/utility/{id}	the updated Utility record with id = id
DELETE	/utility/{id}	status code 200 OK

Route Request Body Requirements

POST / PUT Available Properties:

• title
• description
• published

{
  // property: value
  "title": "legs",
  "description": "an essential part of any bipedal organism"
}

Query Parameters

All query parameters below can be mixed and matched as needed.

Example:

• /utility?sort=version:asc&filter=description:turtle&page=4&results_per_page=1

Sorting

• Sorting has been restricted to a sorting by single column, for now
• Available fields to sort by:
  • title
  • created_at
  • updated_at
  • version
  • published
• Available directions to sort:
  • asc
  • desc
• Examples:
  • /utility?sort=title:asc
  • /utility?sort=published:desc

Filtering

• Filtering has been restricted to filtering by one field, for now
• Available fields to sort by:
  • title
  • description
  • published
  • version
• Examples:
  • /utility?filter=title:raven
  • /utility?filter=description:really

Pagination

Pagination has implicit support on all API routes that can return multiple records. Any route may have a query parameter appended (?page=2) in order to show another page

Pagination options:

• page
• results_per_page (Utility only)

Examples:

• /versions?page=3
• /utility?results_per_page=2&

The pagination in a typical response looks like this:

// /utility/1/versions?page=2
{
  "content": { /* data returned here */ },
  "page": 2,
  "results_per_page": 5,
  "total_results": 6
}

---

Licenses

Read NodeJS's License section here

Read NestJS's License section here

Read PostgreSQL's License here

Read TypeORM's License here

Read TypeScript's License here