The Natours API originated from a server-rendered web application tutorial in JavaScript, where Pug was used for server-side rendering across all routes.
I refactored and rebuilt the entire project in TypeScript, transforming it into a robust API featuring user authentication, tour bookings, and reviews, with MongoDB for data storage.
Additionally, I introduced Zod for input validation and Cloudinary for efficient image storage.
Pug continues to be utilized exclusively for email templates.
I also added comprehensive testing with Jest and SuperTest to ensure the API's reliability.
The Natours API now serves as the backend for another project I developed— a React Single Page Application (SPA) tested with Cypress — providing a seamless web application experience.
To facilitate easy interaction with the API, I have included a comprehensive Postman documentation.
- Getting Started
- Installation
- Environment Variables
- Seeding the Database
- Running Tests
- Running the API
- API Routes
- Technologies Used
- Deployment
- Postman Documentation
Follow these instructions to get a copy of the project up and running on your local machine for development and testing purposes.
Ensure you have the following installed & set up:
- Node.js
20.x - Mongo DB account
- Cloudinary account
- Mailtrap account (for email notifications in development mode)
- Brevo account (for email notifications in production mode)
- Stripe account
Clone the repository and install the dependencies:
git clone https://github.com/your-repo/api_ts_zod.git
cd api_ts_zod
npm install# SERVER
PORT=1337
SERVER_DOMAIN_NAME=localhost
# CLIENT
CORS_ALLOWED_ORIGINS=http://localhost:3000
# MONGO
MONGO_DB_URL=your_mongo_db_url
# STRIPE
STRIPE_PRIVATE_KEY=your_stripe_private_key
STRIPE_PUBLIC_KEY=your_stripe_public_key
STRIPE_WEBHOOK_ENDPOINT_SECRET=your_stripe_webhook_endpoint_secret
# EMAIL
[email protected]
# EMAIL - DEV
MAILTRAP_EMAIL_HOST=your_mailtrap_host
MAILTRAP_EMAIL_PORT=your_mailtrap_port
MAILTRAP_EMAIL_USERNAME=your_mailtrap_username
MAILTRAP_EMAIL_PASSWORD=your_mailtrap_password
# EMAIL - PROD
BREVO_EMAIL_ADMIN=your_brevo_admin_email
BREVO_EMAIL_SMTP_KEY=your_brevo_smtp_key
# CLOUDINARY
CLOUDINARY_CLOUD_NAME=your_cloudinary_cloud_name
CLOUDINARY_API_KEY=your_cloudinary_api_key
CLOUDINARY_API_SECRET=your_cloudinary_api_secret
# PASSWORD_RESET TOKEN
PASSWORD_RESET_TOKEN_EXPIRES_IN=600000
# JWTs TOKENS
ACCESS_TOKEN_PRIVATE_KEY=your_access_token_private_key
ACCESS_TOKEN_PUBLIC_KEY=your_access_token_public_key
REFRESH_TOKEN_PRIVATE_KEY=your_refresh_token_private_key
REFRESH_TOKEN_PUBLIC_KEY=your_refresh_token_public_key
To seed the database, use the following commands:
In development mode:
npm run seed:devIn production mode:
npm run seed:productionThe tests written with Jest and Supertest can be run with:
npm run testTo start the development server, use the following command:
npm run devTo build and start the production server, use the following commands:
npm run build
npm start# Healthcheck Route
- GET /api/v1/healthcheck**: Check the health of the API.
# Tours Routes
- GET /api/v1/tours : Fetch all tours.
- GET /api/v1/tours/top-5-cheap : Fetch top 5 cheapest tours.
- GET /api/v1/tours/:tourId : Fetch a tour by tour ID.
- GET /api/v1/tours/stats : Fetch statistics about tours.
- GET /api/v1/tours/within/:distance/center/:latlng/unit/:unit : Fetch tours within a given distance from a point.
- GET /api/v1/tours/distances-from/:latlng/unit/:unit : Fetch distances to all tours from a point.
- GET /api/v1/tours/:id/reviews : Get all reviews for a given tour.
# Users Routes
- POST /api/v1/users/signup : Create a new user account.
# Sessions Routes
- POST /api/v1/sessions/login : Login a user.
- DELETE /api/v1/sessions/logout : Logout a user.
# Reviews Routes
- GET /api/v1/reviews : Get all reviews for all tours.
- GET /api/v1/reviews/:reviewId : Get a review by review ID.
- GET /api/v1/tours/:id/reviews : Get all reviews for a given tour.
# Logged in as user routes
- GET /api/v1/bookings/checkout-session/:tourId : Get the Stripe checkout session for a booking on a tour.
- GET /api/v1/users/me : Fetch the logged-in user's profile.
- POST /api/v1/users/forgot-my-password : Step 1 in the forgot/reset password process.
- POST /api/v1/users/reset-my-password : Step 2 in the forgot/reset password process.
- PATCH /api/v1/users/update-me : Update the logged-in user's profile.
- PATCH /api/v1/users/update-my-password : Update the logged-in user's password.
- PATCH /api/v1/users/delete-me : Deactivate the logged-in user's account.
- GET /api/v1/users/my-bookings : Get the bookings belonging to the logged-in user.
- POST /api/v1/tours/:id/reviews : Create a review for a tour.
- PATCH /api/v1/reviews/:reviewId : Update a review.
# Logged in as admin routes
- GET /api/v1/users : Get all users data.
- GET /api/v1/users/:userId : Get user by user ID.
- PATCH /api/v1/users/:userId : Update user data (name and/or role).
- GET /api/v1/tours/:id/bookings : Fetch all bookings for a tour.
- GET /api/v1/bookings : Fetch all bookings.
- GET /api/v1/bookings/:bookingId : Fetch a booking by ID.
- DELETE /api/v1/reviews/:reviewId : Delete a review.
# Logged in as admin or lead-guide routes
- POST /api/v1/tours : Create a tour.
- PATCH /api/v1/tours/:tourId : Update a tour.
- DELETE /api/v1/tours/:tourId : Delete a tour.
# Logged in as admin, lead-guide or guide routes
- GET /api/v1/tours/monthly-stats/:year : Get monthly stats for tours.
# Webhook Route
- POST /stripe/webhook : Endpoint for Stripe webhook.
- Allows Stripe to send events after user checkout.
- Listens for `checkout.session.completed` events.
- Creates a booking record in the database upon receiving `checkout.session.completed` event.
- Node.js
- Express
- TypeScript
- MongoDB
- Mongoose
- Zod (for request validation)
- JWT (for authentication)
- Nodemailer (for email notifications)
- Pug (for email templates)
- Stripe (for payment processing)
- Multer (for handling file uploads)
- Cloudinary (for image storage)
- Day.js (for date manipulation)
- Pino (for logging)
- Husky (for Git hooks)
- ESLint (for code linting)
- Prettier (for code formatting)
- Jest (for unit testing)
- Supertest (for testing HTTP APIs)
The Natours API is deployed on Render.com