Travel-Book API Documentation

SahilSahil
10 min read

Table of contents

To check out the project click on Travel-Book .

Diagram showing users accessing a Node.js app on Amazon EC2 via HTTPS. The system uses PM2 and SSL certificates, with integrations to GitHub via webhook and monitoring via CloudWatch.

Base URL

All API endpoints are accessible via:

api.travelbook.sahilfolio.live

Authentication

Most API endpoints require authentication. Authentication is implemented using JSON Web Tokens (JWT).

To authenticate, include the JWT token in the Authorization header of your request:

Authorization: Bearer <your-access-token>

Error Handling

API responses follow a consistent format:

{
  "error": true,
  "message": "Error description"
}

Successful responses typically include:

{
  "error": false,
  "message": "Success message",
  // Additional data...
}

API Endpoints

Authentication and User Management

Create Account

Creates a new user account.

  • URL: /create-account

  • Method: POST

  • Authentication: Not required

  • Request Body:

      {
    "fullName": "John Doe",
    "email": "john@example.com",
    "password": "SecurePassword123!"
  }

  • Success Response:

      {
    "error": false,
    "user": {
      "fullName": "John Doe",
      "email": "john@example.com"
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "message": "Successfully Registered for a Travel Book!"
  }

Send Signup OTP

Sends a one-time password (OTP) to verify email during signup.

  • URL: /send-signup-otp

  • Method: POST

  • Authentication: Not required

  • Request Body:

      {
    "fullName": "John Doe",
    "email": "john@example.com",
    "password": "SecurePassword123!"
  }

  • Success Response:

      {
    "error": false,
    "message": "OTP sent to your email. Please verify to complete registration."
  }

Verify Signup OTP

Verifies the OTP sent during signup.

  • URL: /verify-signup-otp

  • Method: POST

  • Authentication: Not required

  • Request Body:

      {
    "email": "john@example.com",
    "otp": "123456"
  }

  • Success Response:

      {
    "error": false,
    "message": "Account verified successfully!",
    "user": {
      "fullName": "John Doe",
      "email": "john@example.com"
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }

Login

Logs in a user with email and password.

  • URL: /login

  • Method: POST

  • Authentication: Not required

  • Request Body:

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

  • Success Response:

      {
    "error": false,
    "message": "Login Successfully to Travel Book",
    "user": {
      "fullName": "John Doe",
      "email": "john@example.com"
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }

Send Login OTP

Sends an OTP for login verification.

  • URL: /send-login-otp

  • Method: POST

  • Authentication: Not required

  • Request Body:

      {
    "email": "john@example.com"
  }

  • Success Response:

      {
    "error": false,
    "message": "OTP sent to your email. Please verify to login."
  }

Verify Login OTP

Verifies the OTP sent for login.

  • URL: /verify-login-otp

  • Method: POST

  • Authentication: Not required

  • Request Body:

      {
    "email": "john@example.com",
    "otp": "123456"
  }

  • Success Response:

      {
    "error": false,
    "message": "Login successful!",
    "user": {
      "fullName": "John Doe",
      "email": "john@example.com"
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }

Resend OTP

Resends an OTP for login or signup verification.

  • URL: /resend-otp

  • Method: POST

  • Authentication: Not required

  • Request Body:

      {
    "email": "john@example.com",
    "isSignup": true  // true for signup, false for login
  }

  • Success Response:

      {
    "error": false,
    "message": "OTP resent to your email."
  }

Get User

Retrieves authenticated user information.

  • URL: /get-user

  • Method: GET

  • Authentication: Required

  • Success Response:

      {
    "user": {
      "fullName": "John Doe",
      "email": "john@example.com",
      // Other user fields...
    },
    "message": ""
  }

Get Profile

Gets detailed user profile with statistics.

  • URL: /profile

  • Method: GET

  • Authentication: Required

  • Success Response:

      {
    "error": false,
    "user": {
      "fullName": "John Doe",
      "email": "john@example.com",
      "bio": "Travel enthusiast",
      // Other profile fields...
    },
    "stats": {
      "stories": 10,
      "locations": 5,
      "favorites": 3
    }
  }

Update Profile

Updates user profile information.

  • URL: /update-profile

  • Method: PUT

  • Authentication: Required

  • Request Body:

      {
    "fullName": "John Doe",
    "bio": "Passionate traveler and photographer",
    "location": "New York, USA",
    "phone": "+1234567890",
    "website": "https://johndoe.com",
    "socialLinks": {
      "facebook": "https://facebook.com/johndoe",
      "twitter": "https://twitter.com/johndoe",
      "instagram": "https://instagram.com/johndoe",
      "linkedin": "https://linkedin.com/in/johndoe"
    },
    "preferences": {
      "notificationsEnabled": true,
      "privacySettings": {
        "showEmail": false,
        "showPhone": false,
        "profileVisibility": "public"
      },
      "theme": "dark"
    }
  }

  • Success Response:

      {
    "user": {
      // Updated user object
    },
    "message": "Profile updated successfully"
  }

Update Profile Image

Updates the user's profile image.

  • URL: /update-profile-image

  • Method: PUT

  • Authentication: Required

  • Request Body: Form data with an image file

      image: [file]

  • Success Response:

      {
    "profileImage": "https://res.cloudinary.com/travel-book/image/upload/v1/travel_book/profiles/image.jpg",
    "message": "Profile image updated successfully"
  }

Forgot Password

Initiates the password reset process.

  • URL: /forgot-password

  • Method: POST

  • Authentication: Not required

  • Request Body:

      {
    "email": "john@example.com"
  }

  • Success Response:

      {
    "error": false,
    "message": "Password reset link sent to your email."
  }

Reset Password

Resets the password using a token.

  • URL: /reset-password

  • Method: POST

  • Authentication: Not required

  • Request Body:

      {
    "email": "john@example.com",
    "token": "reset-token-from-email",
    "newPassword": "NewSecurePassword123!"
  }

  • Success Response:

      {
    "error": false,
    "message": "Password has been reset successfully. Please log in with your new password."
  }

Change Password

Changes the password for an authenticated user.

  • URL: /change-password

  • Method: POST

  • Authentication: Required

  • Request Body:

      {
    "currentPassword": "OldPassword123!",
    "newPassword": "NewPassword123!"
  }

  • Success Response:

      {
    "error": false,
    "message": "Password changed successfully"
  }

Update Privacy Settings

Updates user privacy settings.

  • URL: /api/user/privacy-settings

  • Method: PATCH

  • Authentication: Required

  • Request Body:

      {
    "profileVisibility": "public" // or "private"
  }

  • Success Response:

      {
    "error": false,
    "message": "Privacy settings updated successfully",
    "privacySettings": {
      "profileVisibility": "public"
    }
  }

Travel Stories

Add Travel Story

Creates a new travel story.

  • URL: /add-travel-story

  • Method: POST

  • Authentication: Required

  • Request Body:

      {
    "title": "My Trip to Paris",
    "story": "It was an amazing experience visiting the Eiffel Tower...",
    "visitedLocation": ["Paris, France"],
    "imageUrl": "https://res.cloudinary.com/travel-book/image/upload/v1/travel_book/paris.jpg",
    "visitedDate": "1621458000000" // Timestamp in milliseconds
  }

  • Success Response:

      {
    "story": {
      // Travel story object
    },
    "message": "Added Successfully"
  }

Get All Stories

Retrieves all travel stories for the authenticated user.

  • URL: /get-all-stories

  • Method: GET

  • Authentication: Required

  • Success Response:

      {
    "stories": [
      // Array of travel story objects
    ]
  }

Edit Travel Story

Updates an existing travel story.

  • URL: /edit-story/:id

  • Method: PUT

  • Authentication: Required

  • URL Parameters:

    • id: ID of the travel story to edit

  • Request Body:

      {
    "title": "Updated Trip to Paris",
    "story": "Updated content about my Paris trip...",
    "visitedLocation": ["Paris, France"],
    "imageUrl": "https://res.cloudinary.com/travel-book/image/upload/v1/travel_book/paris_updated.jpg",
    "visitedDate": "1621458000000" // Timestamp in milliseconds
  }

  • Success Response:

      {
    "story": {
      // Updated travel story object
    },
    "message": "Update Successful"
  }

Delete Travel Story

Deletes a travel story.

  • URL: /delete-story/:id

  • Method: DELETE

  • Authentication: Required

  • URL Parameters:

    • id: ID of the travel story to delete

  • Success Response:

      {
    "message": "Travel Story deleted successfully!"
  }

Update Favorite Status

Updates the favorite status of a travel story.

  • URL: /update-is-favourite/:id

  • Method: PUT

  • Authentication: Required

  • URL Parameters:

    • id: ID of the travel story

  • Request Body:

      {
    "isFavourite": true
  }

  • Success Response:

      {
    "story": {
      // Updated travel story object
    },
    "message": "Update Successful"
  }

Toggle Profile Visibility

Toggles whether a story is shown on the public profile.

  • URL: /toggle-show-on-profile/:id

  • Method: PUT

  • Authentication: Required

  • URL Parameters:

    • id: ID of the travel story

  • Request Body:

      {
    "showOnProfile": true
  }

  • Success Response:

      {
    "story": {
      // Updated travel story object
    },
    "message": "Profile visibility updated successfully"
  }

Search Stories

Searches travel stories by query text.

  • URL: /search

  • Method: GET

  • Authentication: Required

  • Query Parameters:

    • query: Search term

  • Success Response:

      {
    "stories": [
      // Array of matching travel story objects
    ]
  }

Filter Stories by Date Range

Filters travel stories by date range.

  • URL: /travel-stories-filter

  • Method: GET

  • Authentication: Required

  • Query Parameters:

    • startDate: Start date (timestamp or ISO string)

    • endDate: End date (timestamp or ISO string)

  • Success Response:

      {
    "stories": [
      // Array of filtered travel story objects
    ]
  }

Performs advanced search with multiple filters.

  • URL: /advanced-search

  • Method: POST

  • Authentication: Required

  • Request Body:

      {
    "location": "Paris",
    "title": "Trip",
    "dateRange": {
      "startDate": "2023-01-01",
      "endDate": "2023-12-31"
    },
    "isFavourite": true,
    "sortBy": "newest" // "newest", "oldest", "a-z", "z-a"
  }

  • Success Response:

      {
    "stories": [
      // Array of matching travel story objects
    ],
    "count": 5,
    "message": "Search results found"
  }

Search by Location

Groups and searches travel stories by location.

  • URL: /search-by-location

  • Method: GET

  • Authentication: Required

  • Success Response:

      {
    "locations": [
      {
        "location": "Paris, France",
        "count": 3,
        "previewStory": {
          // Sample story object for this location
        }
      },
      // More locations...
    ],
    "totalLocations": 5
  }

Search by Tags

Searches travel stories by hashtags in content.

  • URL: /search-by-tags

  • Method: GET

  • Authentication: Required

  • Query Parameters:

    • tags: Comma-separated list of tags (without #)

  • Success Response:

      {
    "stories": [
      // Array of matching travel story objects
    ],
    "count": 7,
    "tags": ["paris", "france", "travel"],
    "message": "Found 7 stories with the specified tags"
  }

Public API Endpoints

Get Public Story

Retrieves a single travel story by ID for sharing.

  • URL: /api/story/:id

  • Method: GET

  • Authentication: Not required

  • URL Parameters:

    • id: ID of the travel story

  • Success Response:

      {
    // Travel story object
  }

Get Public Profile

Retrieves public profile information for a user.

  • URL: /api/public-profile/:userId

  • Method: GET

  • Authentication: Not required

  • URL Parameters:

    • userId: ID of the user

  • Success Response:

      {
    "error": false,
    "profile": {
      // Public user profile data
    },
    "stats": {
      "stories": 10,
      "locations": 5,
      "favorites": 3
    },
    "recentStories": [
      // Array of recent public travel story objects
    ]
  }

Get Public Stories

Retrieves public travel stories for a specific user.

  • URL: /api/public-stories/:userId

  • Method: GET

  • Authentication: Not required

  • URL Parameters:

    • userId: ID of the user

  • Query Parameters:

    • limit: Number of stories to return (default: 10)

    • page: Page number for pagination (default: 1)

  • Success Response:

      {
    "error": false,
    "stories": [
      // Array of public travel story objects
    ],
    "pagination": {
      "total": 25,
      "page": 1,
      "limit": 10,
      "pages": 3
    }
  }

Image Upload

Upload Image

Uploads an image to be used in travel stories.

  • URL: /image-upload

  • Method: POST

  • Authentication: Required

  • Request Body: Form data with an image file

      image: [file]

  • Success Response:

      {
    "imageUrl": "https://res.cloudinary.com/travel-book/image/upload/v1/travel_book/image.jpg"
  }

System Health

Health Check

Checks if the API is running.

  • URL: /health

  • Method: GET

  • Authentication: Not required

  • Success Response:

      OK

Ping

Endpoint for uptime monitoring.

  • URL: /ping

  • Method: GET

  • Authentication: Not required

  • Success Response:

      Ping received correctly by backend!!

Data Models

User

{
  "fullName": "String (required)",
  "email": "String (required, unique)",
  "password": "String (hashed, required)",
  "createdOn": "Date",
  "otp": "String (optional)",
  "otpExpiry": "Date (optional)",
  "isVerified": "Boolean (default: false)",
  "resetPasswordToken": "String (optional)",
  "resetPasswordExpiry": "Date (optional)",
  "profileImage": "String (URL)",
  "bio": "String",
  "location": "String",
  "phone": "String",
  "website": "String",
  "socialLinks": {
    "facebook": "String",
    "twitter": "String",
    "instagram": "String",
    "linkedin": "String"
  },
  "preferences": {
    "notificationsEnabled": "Boolean",
    "privacySettings": {
      "showEmail": "Boolean",
      "showPhone": "Boolean",
      "profileVisibility": "String (enum: 'public', 'private')"
    },
    "theme": "String (enum: 'light', 'dark', 'system')"
  }
}

Travel Story

{
  "title": "String (required)",
  "story": "String (required)",
  "visitedLocation": "Array of Strings",
  "isFavourite": "Boolean (default: false)",
  "showOnProfile": "Boolean (default: false)",
  "userId": "ObjectId (reference to User, required)",
  "createdOn": "Date",
  "imageUrl": "String (URL, required)",
  "visitedDate": "Date (required)"
}

Rate Limiting and Usage

The API currently does not impose strict rate limits, but excessive requests may be throttled to ensure service stability. Please use the API responsibly.

🚀 Deployment

Support and Feedback

For support or feedback regarding the API, please contact the developer at the email contact@sahilfolio.live

For more information or to connect with me, feel free to check out my portfolio, GitHub, LinkedIn, and Twitter:

© 2025 Travel Book API. All rights reserved.

0
Subscribe to my newsletter

Read articles from Sahil directly inside your inbox. Subscribe to the newsletter, and don't miss out.

Node.jsExpress.jscloudinaryrender.comJavaScriptjavascript frameworkroutesGitHubAWSaws ec2

Written by

Sahil
Sahil

I’m a passionate third-year BTech student pursuing Computer Science and Engineering at SRM Institute of Science and Technology, Chennai. Currently, I’m deep diving into Data Structures & Algorithms (DSA) and working with the MERN stack, focusing on building scalable web applications.