A flexible and extensible Notification REST API built with NestJS.

Notify API

A flexible and extensible Notification REST API built with NestJS. The service currently supports email notifications via SMTP and is designed to be easily integrated into your projects. Future versions will support additional channels like SMS and push notifications.

Table of Contents

• Project Overview
• Technology Stack & Framework
• Getting Started
  • Clone the Repository
  • Install Dependencies
  • Configure Environment Variables
• Running the Application
• API Authentication & Security
• SMTP & Email Configuration
• Internationalization (i18n)
• Using the Endpoints
• API Documentation (Swagger)
• Testing
• Deployment
• Resources & Support
• License

Project Overview

The Notify API provides a RESTful interface for sending notifications. Initially focused on email notifications using SMTP, the project is designed for ease-of-use and future expansion to include additional channels.

Technology Stack & Framework

• Backend Framework: NestJS
• Programming Language: TypeScript
• Template Engine: EJS (for HTML email templates)
• Storage: Redis (for queue management and caching)
• Environments: Development, Testing, Production (managed via .env files)

Getting Started

Clone the Repository

Clone the repository to your local machine:

git clone https://github.com/YonatanQuintero/notify-api.git
cd notify-api

Install Dependencies

Install all project dependencies using npm:

npm install

Configure Environment Variables

Create a .env file in the root directory (if not already present) and configure the following key settings:

# .env

PORT=3000
API_KEY=api-key-64-length
ENVIRONMENT=development
DEFAULT_LANG=en

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=smtp-user
SMTP_PASS=smtp-pass

COMPANY_NAME="My Company"
COMPANY_ICON_URL=https://my-company.com/icon.png
COMPANY_WEBSITE_URL=https://my-company.com
COMPANY_ADDRESS="The way to the heaven"

REDIS_URL=redis://localhost:6379/0
REDIS_PORT=6379
REDIS_HOST=localhost
REDIS_DB=0

Note: Ensure that sensitive credentials like API keys and SMTP passwords are kept secure.

Running the Application

Development Mode

Start the application in development mode:

npm run start

Watch Mode

For automatic reload during development:

npm run start:dev

Production Mode

Build and run in production mode:

npm run start:prod

API Authentication & Security

• API Key Authentication:
  Every request must include the API key in the header (x-api-key).
  Example header:

  x-api-key: your_api_key_here
  

• Transport Security:
  The API should be deployed behind HTTPS (handled by your load balancer or API gateway).

SMTP & Email Configuration

The service uses SMTP to send emails. Configure your SMTP details in the .env file:

• SMTP_HOST: Your SMTP server host.
• SMTP_PORT: SMTP port (commonly 587 for TLS).
• SMTP_USER: Your SMTP username.
• SMTP_PASS: Your SMTP password.

Emails are templated using EJS with HTML templates stored in the template-renderer/templates/ directory. The email sending process includes a retry mechanism for handling transient errors.

Internationalization (i18n)

• Supported Languages:

  • English (en)
  • Spanish (es)

• Language Selection:
  Determine the language via the x-language HTTP header. If not provided or unsupported, the default language (configured in .env as DEFAULT_LANGUAGE) is used.

• Usage:
  Include error messages, system messages, and template strings that support translation using separate language resource files.

Using the api/v1/notifications/email Endpoints

Sample Request

Use the following example to send a notification using either cURL or HTTPie:

cURL Example

curl -X POST http://localhost:3000/api/v1/notifications/email/welcome \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-secret-api-key" \
  -H "x-language: es" \
  -H "Accept: */*" \
  -d '{"to": ["email@example.com"], "username": "example"}'

HTTPie Example

http POST http://localhost:3010/api/v1/notifications/email/welcome \
  Content-Type:application/json \
  x-api-key:"your-secret-api-key" \
  x-language:es \
  Accept:'*/*' \
  to:='["email@example.com"]' \
  username="example"

API Documentation (Swagger)

Detailed API documentation is available via Swagger. You can view it here:

Swagger Docs

Tip: Replace localhost:3000 with your deployed API domain if not running locally.

Testing

Run tests to ensure everything is functioning correctly:

• Unit Tests:

  npm run test:unit

• End-to-End Tests:

  npm run test:e2e

• All Tests:

  npm run test

• Unit Test Coverage:

  npm run test:cov:unit

• End-to-End Test Coverage:

  npm run test:cov:e2e

• All Tests Coverage:

  npm run test:cov

Deployment

When you're ready to deploy:

1. Build for Production:
   Ensure your .env is set up correctly for production.

2. Deployment Using Mau (Optional):
   Deploy your NestJS application with Mau on AWS:

   npm install -g mau
   mau deploy

3. Further Steps:
   Review your deployment documentation for additional steps and configuration details specific to your production environment.

Resources & Support

• NestJS Documentation: NestJS Docs
• Stay in Touch with Me: yonax73

License

Notify API is released under the MIT License.