Express API seed

This is a RESTful API seed project. As an example this API allows you to create users and articles.

Table of Contents

• Express API seed
  • Table of Contents
  • Prerequisites
    • MongoDB
    • Node.js
  • Clone repo and install dependencies
  • Start API
  • Tests
  • Design decisions
  • API Docs
    • Models
      • User
      • Article
    • Errors
    • Authentication
    • Endpoints
      • POST /v1/users
        • Description
        • Request
        • Response
      • POST /v1/articles
        • Description
        • Request
        • Response
      • PUT /v1/articles/:id
        • Description
        • Request
        • Response
      • DELETE /v1/articles:id
        • Description
        • Request
        • Response
      • GET /v1/articles?tags=tag1,tag2,..,tagn
        • Description
        • Request
        • Response

Prerequisites

MongoDB

Make sure that MongoDB is installed and running in your local machine. If you are use to use Docker you can use this image. Version: >= 4.0

Node.js

Install the latest LTS Node.js version. If you are using nvm you can just run nvm use in the root folder.

Clone repo and install dependencies

1. git clone https://github.com/hpieroni/simple-user-article-api.git
2. cd simple-user-article-api
3. npm install

Start API

In order to start the API you need to configure some ENV variables first. You can do this through an .env file (check .env.example ).

Variable	Default	Description
PORT	3000	Port where the server will listen
TOKEN		Authentication token
DB_CONNECTION_URI		Mongo connection URI. Example: mongodb://localhost:27017/dbTest See reference

Finally run npm start and check the console for a message similar to:

[Database]: connection was successful
[HTTP-Server]: listening on port 3000

Tests

• npm run test runs the test suit
• npm run test:coverage displays a test coverage report

Design decisions

I tried to minimize the amount of libraries in this solution. Also, I didn't implement any kind of foreign key constraints, that is why the api allows you to create an article whether the user exists or not.

API Docs

Models

User

Field	Type
_id	ObjectId
name	String
avatar	URL

Article

Field	Type
_id	ObjectId
userId	ObjectId
title	String
text	String
tags	[String]

Errors

The shape of an error is:

{
  "statusCode": 400,
  "status": "Bad Request",
  "appCode": "INVALID_REQUEST_BODY",
  "message": "Invalid request body",
  "details": {
    "name": "is required",
    "avatar": "must be a valid uri"
  }
}

Where:

HTTP Code	Status Text	App Code	Message
400	Bad Request	INVALID_REQUEST_BODY	Invalid request body
		INVALID_REQUEST_QUERY	Invalid request querystring
		INVALID_REQUEST_PARAMS	Invalid request route params
401	Unauthorized	MISSING_AUTH_HEADER	Missing Authorization header
		INVALID_AUTH_SCHEMA	Invalid Authorization header schema
		INVALID_AUTH_TOKEN	Invalid token in Authorization header
404	Not Found	NOT_FOUND	Requested resource was not found
500	Server Error	UNEXPECTED	Ups! Something went wrong :(

Every error can contain a details field for more specific information. See the error example above. By default an Unexpected error will contain a message and error (the original) y the details section.

Authentication

All endpoints are protected by Authorization: Bearer <TOKEN> header. The token is the one provided in .env file.

Endpoints

POST /v1/users

Description

Creates a new user

Request

curl -i -X POST -H "Content-Type: application/json" \
 -H "Authorization: Bearer myToken" \
 -d '{"name":"john","avatar":"http://www.avatar.com"}' \
 http://localhost:3000/v1/users

Response

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "_id": "5e3ad6deaac3ad522a47ad4b",
  "name": "john",
  "avatar": "http://www.avatar.com"
}

POST /v1/articles

Description

Creates a new article

Request

curl -i -X POST -H "Content-Type: application/json" \
 -H "Authorization: Bearer myToken" \
 -d '{"userId":"5e3ad6deaac3ad522a47ad4b","title":"Title","text":"Lorem ipsum","tags":["music","relax"]}' \
 http://localhost:3000/v1/articles

Response

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "_id": "5e3ad860aac3ad522a47ad4c",
  "userId":"5e3ad6deaac3ad522a47ad4b",
  "title": "Title"
  "tags: ["music","relax"],
  "text": "Lorem ipsum"
}

PUT /v1/articles/:id

Description

Updates article of given id

Request

curl -i -X PUT -H "Content-Type: application/json" \
 -H "Authorization: Bearer myToken" \
 -d '{"userId":"5e3ad6deaac3ad522a47ad4b","title":"T2","text":"Lorem ipsum 2","tags":["nature"]}' \
 http://localhost:3000/v1/articles/5e3ad860aac3ad522a47ad4c

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "_id": "5e3ad860aac3ad522a47ad4c",
  "userId":"5e3ad6deaac3ad522a47ad4b",
  "title": "T2"
  "tags: ["nature"],
  "text": "Lorem ipsum 2"
}

DELETE /v1/articles:id

Description

Deletes article of given id

Request

curl -i -X DELETE \
 -H "Authorization: Bearer myToken" \
 http://localhost:3000/v1/articles/5e3ad860aac3ad522a47ad4c

Response

HTTP/1.1 204 No Content

GET /v1/articles?tags=tag1,tag2,..,tagn

Description

Find articles that contains the given tags

Request

curl -i -X GET \
 -H "Authorization: Bearer myToken" \
 http://localhost:3000/v1/articles?tags=nature,music,relax

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "_id": "5e3ad860aac3ad522a47ad4c",
    "userId":"5e3ad6deaac3ad522a47ad4b",
    "title": "T2"
    "tags: ["nature"],
    "text": "Lorem ipsum 2"
  }
]