Creating an Express.js API Project

I'll help you create a comprehensive Express.js API project that covers all the aspects you mentioned. Let's build a robust API with authentication, database integration, and proper documentation.

Project Structure

First, let's set up a well-organized Express.js API project structure:

Now, let's create our database configuration:

Let's create our error handling middleware:

Authentication System

Let's implement JWT and OAuth authentication:

Now, let's create our User model:

Let's create a Product model for our API:

Authentication Routes

Now, let's implement our authentication routes:

User Routes

Let's implement our user routes:

Product Routes

Let's implement our product routes:

API Documentation

Let's create a simple documentation file to explain how to use our API:

• Success Response:

  • Code: 201

  • Content:

    { "_id": "user_id", "name": "John Doe", "email": "john@example.com", "isAdmin": false, "apiKey": "generated_api_key", "token": "jwt_token" }

Login

• URL: /auth/login
• Method: POST
• Auth required: No

• Body:

  { "email": "john@example.com", "password": "password123" }

• Success Response:

  • Code: 200

  • Content:

    { "_id": "user_id", "name": "John Doe", "email": "john@example.com", "isAdmin": false, "token": "jwt_token" }

Get User Profile

• URL: /auth/profile
• Method: GET
• Auth required: Yes (JWT Token)

• Headers:

  Authorization: Bearer jwt_token

• Success Response:

  • Code: 200

  • Content:

    { "_id": "user_id", "name": "John Doe", "email": "john@example.com", "isAdmin": false }

Generate New API Key

• URL: /auth/api-key
• Method: POST
• Auth required: Yes (JWT Token)

• Headers:

  Authorization: Bearer jwt_token

• Success Response:

  • Code: 200

  • Content:

    { "apiKey": "new_api_key" }

Products

Get All Products

• URL: /products
• Method: GET
• Auth required: No

• Query Parameters:

  • keyword: Search term
  • page: Page number

• Success Response:

  • Code: 200

  • Content:

    { "products": [ { "_id": "product_id", "name": "Product Name", "price": 99.99, "description": "Product description", "image": "image_url", "brand": "Brand Name", "category": "Category", "countInStock": 10, "rating": 4.5, "numReviews": 12, "reviews": [] } ], "page": 1, "pages": 5, "total": 50 }

Get Product by ID

• URL: /products/:id
• Method: GET
• Auth required: No

• Success Response:

  • Code: 200

  • Content:

    { "_id": "product_id", "name": "Product Name", "price": 99.99, "description": "Product description", "image": "image_url", "brand": "Brand Name", "category": "Category", "countInStock": 10, "rating": 4.5, "numReviews": 12, "reviews": [] }

Create Product

• URL: /products
• Method: POST
• Auth required: Yes (API Key)

• Headers:

  x-api-key: your_api_key

• Body:

  { "name": "Product Name", "price": 99.99, "description": "Product description", "image": "image_url", "brand": "Brand Name", "category": "Category", "countInStock": 10 }

• Success Response:

  • Code: 201
  • Content: Created product object

Update Product

• URL: /products/:id
• Method: PUT
• Auth required: Yes (API Key)

• Headers:

  x-api-key: your_api_key

• Body:

  { "name": "Updated Product Name", "price": 89.99, "description": "Updated description", "image": "new_image_url", "brand": "Updated Brand", "category": "Updated Category", "countInStock": 15 }

• Success Response:

  • Code: 200
  • Content: Updated product object

Delete Product

• URL: /products/:id
• Method: DELETE
• Auth required: Yes (JWT Token + Admin)

• Headers:

  Authorization: Bearer jwt_token

• Success Response:

  • Code: 200

  • Content:

    { "message": "Product removed" }

Add Product Review

• URL: /products/:id/reviews
• Method: POST
• Auth required: Yes (JWT Token)

• Headers:

  Authorization: Bearer jwt_token

• Body:

  { "rating": 5, "comment": "Great product!" }

• Success Response:

  • Code: 201

  • Content:

    { "message": "Review added" }

Users (Admin Only)

Get All Users

• URL: /users
• Method: GET
• Auth required: Yes (JWT Token + Admin)

• Headers:

  Authorization: Bearer jwt_token

• Success Response:

  • Code: 200
  • Content: Array of user objects

Get User by ID

• URL: /users/:id
• Method: GET
• Auth required: Yes (JWT Token + Admin)

• Headers:

  Authorization: Bearer jwt_token

• Success Response:

  • Code: 200
  • Content: User object

Update User

• URL: /users/:id
• Method: PUT
• Auth required: Yes (JWT Token + Admin)

• Headers:

  Authorization: Bearer jwt_token

• Body:

  { "name": "Updated Name", "email": "updated@example.com", "isAdmin": true }

• Success Response:

  • Code: 200
  • Content: Updated user object

Delete User

• URL: /users/:id
• Method: DELETE
• Auth required: Yes (JWT Token + Admin)

• Headers:

  Authorization: Bearer jwt_token

• Success Response:

  • Code: 200

  • Content:

    { "message": "User removed" }

```

Testing with Postman/CURL

Let's create a file with examples of how to test our API using both Postman and CURL:

Login

• Method: POST
• URL: {base_url}/auth/login
• Body (raw JSON):

• After successful login, copy the token from the response and set it as the token environment variable

Get User Profile

• Method: GET
• URL: {base_url}/auth/profile

• Headers:

  • Authorization: Bearer {token}

Testing Products API

Get All Products

• Method: GET
• URL: {base_url}/products

• Optional Query Params:

  • keyword: product
  • page: 1

Get Product by ID

• Method: GET
• URL: {base_url}/products/{product_id}

Create Product

• Method: POST
• URL: {base_url}/products

• Headers:

  • x-api-key: {api_key}
• Body (raw JSON):

Update Product

• Method: PUT
• URL: {base_url}/products/{product_id}

• Headers:

  • x-api-key: {api_key}
• Body (raw JSON):

Delete Product

• Method: DELETE
• URL: {base_url}/products/{product_id}

• Headers:

  • Authorization: Bearer {token}

Testing with CURL

Authentication

Register a new user

Login

Get User Profile (replace TOKEN with your JWT token)

Products API

Get All Products

Get Products with Search and Pagination

Get Product by ID (replace PRODUCT_ID with an actual product ID)

Create Product (replace API_KEY with your API key)

Update Product (replace PRODUCT_ID and API_KEY)

Delete Product (replace PRODUCT_ID and TOKEN)

Add Product Review (replace PRODUCT_ID and TOKEN)

Python Example

Java Example

Advantages of GraphQL

1. Precise Data Fetching: Clients request exactly what they need
2. Single Request: Can fetch complex, nested data in a single request
3. Strong Typing: Schema provides clear contract and validation
4. Introspection: Self-documenting API
5. Versioning: Easier to evolve API without versioning

Disadvantages of GraphQL

1. Complexity: More complex to set up and understand initially
2. Caching: HTTP caching is more challenging
3. File Uploads: Not built into the specification
4. Rate Limiting: More difficult to implement than with REST
5. Learning Curve: Steeper learning curve for developers

When to Use REST vs GraphQL

Choose REST when:

• Building simple CRUD applications
• Working with resource-oriented data
• HTTP caching is important
• You need maximum compatibility with clients
• File uploads are a primary feature
• You want to leverage existing tools and middleware

Choose GraphQL when:

• Clients need flexible data requirements
• Your API serves multiple client platforms with different needs
• You have complex, nested data relationships
• Network performance is critical (reducing over-fetching)
• You want a strongly typed API contract
• You need powerful developer tools for exploring the API

Hybrid Approaches

Many modern applications use both REST and GraphQL:

1. REST for simple operations: Use REST for simple CRUD operations
2. GraphQL for complex queries: Use GraphQL for complex, nested data needs
3. REST for file uploads: Use REST endpoints for file uploads
4. GraphQL as a gateway: Use GraphQL as an API gateway in front of REST services

Conclusion

Both REST and GraphQL have their strengths and weaknesses. The choice between them depends on your specific application requirements, team expertise, and client needs. Our Express API currently uses REST, but could be extended with GraphQL capabilities if needed in the future.

Deployment Guide

Let's create a guide for deploying our Express API to Vercel:

Step 2: Modify Your Server Code

Ensure your server code exports the Express app. In server.js, make sure you have:

Step 3: Install Vercel CLI

Step 4: Login to Vercel

Step 5: Deploy to Vercel

Navigate to your project directory and run:

Follow the prompts to configure your deployment. When asked if you want to override the settings, choose "No" to use the settings from your vercel.json file.

Step 6: Set Environment Variables

After deployment, you need to set up your environment variables in the Vercel dashboard:

1. Go to your Vercel dashboard
2. Select your project
3. Go to "Settings" > "Environment Variables"
4. Add all the environment variables from your .env file

Step 7: Connect to MongoDB Atlas

For production, you should use a hosted MongoDB service like MongoDB Atlas:

1. Create a MongoDB Atlas account
2. Create a new cluster
3. Get your connection string
4. Add it as the MONGO_URI environment variable in Vercel

Step 8: Production Deployment

When you're ready to deploy to production, run:

Additional Considerations for Vercel Deployment

Serverless Function Limitations

Vercel serverless functions have some limitations:

1. Execution Time: Limited to 10 seconds in the free tier
2. Payload Size: Limited to 4.5MB
3. Statelessness: Functions are stateless, so don't rely on local file storage

Cold Starts

Serverless functions experience "cold starts" when they haven't been used for a while. To minimize the impact:

1. Keep your dependencies minimal
2. Use connection pooling for databases
3. Consider premium plans for improved cold start performance

Monitoring

Use Vercel's built-in analytics and logging to monitor your API:

1. Go to your project in the Vercel dashboard
2. Check the "Analytics" tab for usage metrics
3. Check the "Logs" tab for function execution logs

Alternative Deployment Options

If Vercel's serverless model doesn't fit your needs, consider these alternatives:

1. Heroku: Traditional platform-as-a-service with easy deployment
2. DigitalOcean App Platform: Managed platform with more resources
3. AWS Elastic Beanstalk: Managed service that handles deployment details
4. Docker + Kubernetes: For complex, scalable deployments

References

For more information on deploying Express.js applications to Vercel, see the official Vercel documentation 1.