Chirpy

A RESTful web API that implements a backend server in Golang for a twitter-like website.

Features:

• JSON data storage safely exposed in an internal database package
• User and 'chirp' creation, storage and management
• Authorization with JWT refresh and access tokens
• Subscribed users and non-subscribed users
• Middleware for web app pages

Contents

• Getting Started
  
  • Prerequisites
    
  • Environment Variables
    
  • Building and Running The Application
    
• API Endpoints
  
  • /api/users
    
  • /api/login
    
  • /api/chirps
    
  • /api/refresh
    
  • /api/revoke
    
  • /api/healthz
    
  • /api/reset
• Webpages
  
  • /app/index.html
  • /app/assets/logo.png
  • /admin/metrics

Getting Started

Prerequisites

Ensure you have Go v1.22+ installed on your system.

Environment Variables

Create a .env file in your project root directory with the following environment variables:

JWT_SECRET=<Your JWT Secret Key>
POLKA_APIKEY=<Your Polka API Key>

Building and Running the Application

From the project's root directory, use the Go command-line tool to build the executable:

go build -o chirpy

This command generates an executable named chirpy, which starts the web API server on the specified port.

Execute the built binary:

./chirpy

Back To Top

API Endpoints

• /api/users
  
• /api/login
  
• /api/chirps
  
• /api/refresh
  
• /api/revoke
  
• /api/healthz
  
• /api/reset

/api/users

POST http://localhost:<Port>/api/users

Creates a new user database entry and returns it.

• Headers: None
• Request Body:

{
  "email": "<User Name>",
  "password": "<User Password>"
}

• Response Body:

{
  "id": "<User ID>", 
  "email": "<User Name>",
  "is_chirpy_red": "<Boolean Value>" 
}

PUT http://localhost:<Port>/api/users

Updates a user's database entry details - their email and password.

• Headers: Requires authentication header:

Authentication: Bearer <Access Token>

• Request Body:

{
  "email": "<User Name>",
  "password": "<User Password>"
}

• Response Body:

{
  "id": "<User ID>", 
  "email": "<User Name>",
  "is_chirpy_red": "<Boolean Value>" 
}

Back To Top   Back To Endpoints

/api/login

POST http://localhost:<Port>/api/login

Authenticates a user and returns to them new access and refresh tokens.

• Headers: None
• Request Body:

{
  "email": "<User Name>",
  "password": "<User Password>"
}

• Response Body:

{
  "id": "<User ID>", 
  "email": "<User Name>",
  "is_chirpy_red": "<Boolean Value>", 
  "token": "<JWT Access Token>",
  "refresh_token": "<JWT Refresh Token>"
}

Back To Top   Back To Endpoints

/api/chirps

POST http://localhost:<Port>/api/chirps

Creates a new chirp database entry associated with a specific user and returns it.

• Headers: Requires authentication header:

Authentication: Bearer <Access Token>

• Request Body:

{
  "body": "<Chrip Message>"
}

• Response Body:

{
  "id": "<Chirp ID>", 
  "author_id": "<User ID>", 
  "body": "<Chirp Message>"
}

GET http://localhost:<Port>/api/chirps

Returns a list of all chirp database entries.
Defaults sorting by ascending id. Use optional query parameter sort to sort chirps in descending order. For example: http://localhost:8080/api/chirps?sort=desc
Use optional query parameter author_id to limit chirps to a specific author. For example: http://localhost:8080/api/chirps?author_id=1

• Headers: None
• Request Body: None
• Response Body:

[
  {
    "id": "<Chirp ID>", 
    "author_id": "<User ID>", 
    "body": "<Chirp Message>"
  }
]

GET http://localhost:<Port>/api/chirps/{id}

Returns a specific chirp database entry with the ID that is provided in the URL.

• Headers: None
• Request Body: None
• Response Body:

{
  "id": "<Chirp ID>", 
  "author_id": "<User ID>", 
  "body": "<Chirp Message>"
}

DELETE http://localhost:<Port>/api/chirps/{id}

Deletes a specific chirp database entry with the ID that is provided in the URL, for an authenticated user.

• Headers: Requires authentication header:

Authentication: Bearer <Access Token>

• Request Body: None
• Response Body: None

Back To Top   Back To Endpoints

/api/refresh

POST http://localhost:<Port>/api/refresh

Creates a new JWT access token and returns it in the response.

• Headers: Requires authentication header:

Authentication: Bearer <Refresh Token>

• Request Body: None
• Response Body:

{
  "token": "<Access Token>"
}

Back To Top   Back To Endpoints

/api/revoke

POST http://localhost:<Port>/api/revoke

Revokes a JWT token.

• Headers: Requires authentication header:

Authentication: Bearer <JWT Token>

• Request Body: None
• Response Body: None

Back To Top   Back To Endpoints

/api/polka/webhooks

POST http://localhost:<Port>/api/polka/webhooks

Webhook endpoint for polka service that updates user's subscription status.

• Headers: Requires authentication header:

Authentication: Bearer <Polka API Key>

• Request Body:

{
  "event": "user.upgraded",
  "data": {
    "user_id": "<UserID>"
  }
}

• Response Body: None

Back To Top   Back To Endpoints

/api/healthz

GET http://localhost:<Port>/api/healthz

Returns status of the web server.

• Headers: None
• Request Body: None
• Response Body:

OK

Back To Top   Back To Endpoints

/api/reset

GET http://localhost:<Port>/admin/metrics

Resets the middleware counter for the number of the times the app pages have been viewed.

• Headers: None
• Request Body: None
• Response Body: None

Back To Top   Back To Endpoints

Webpages

• /app/index.html
• /app/assets/logo.png
• /admin/metrics

/app/index.html

Serves the web app welcome page.

Back To Top   Back To Webpages

/app/assets/logo.png

Serves the web app logo.

Back To Top   Back To Webpages

/admin/metrics

Displays how many times an app page is viewed.

Back To Top   Back To Webpages