Skip to content

Commit 4644083

Browse files
Copilotarchitxkumar
Copilot
and
architxkumar
committed
Create comprehensive README with API endpoint specifications
Co-authored-by: architxkumar <177444949+architxkumar@users.noreply.github.com>
1 parent fb15b8e commit 4644083

File tree

1 file changed

+359
-2
lines changed

1 file changed

+359
-2
lines changed

‎README.md‎

Lines changed: 359 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,362 @@
11
# Blogging Platform API
22

3-
A simple RESTful API with basic CRUD operations for a personal blogging platform.
3+
A simple RESTful API with basic CRUD operations for a personal blogging platform built with Go, Gorilla Mux, and PostgreSQL.
44

5-
Built as a [learning project](https://roadmap.sh/projects/blogging-platform-api) for [Backend Roadmap](https://roadmap.sh/backend/projects) on [roadmap,sh](https://roadmap.sh/).
5+
Built as a [learning project](https://roadmap.sh/projects/blogging-platform-api) for [Backend Roadmap](https://roadmap.sh/backend/projects) on [roadmap.sh](https://roadmap.sh/).
6+
7+
## Table of Contents
8+
9+
- [Features](#features)
10+
- [Tech Stack](#tech-stack)
11+
- [Prerequisites](#prerequisites)
12+
- [Installation](#installation)
13+
- [Database Setup](#database-setup)
14+
- [Running the Application](#running-the-application)
15+
- [API Endpoints](#api-endpoints)
16+
- [Create Blog Post](#create-blog-post)
17+
- [Update Blog Post](#update-blog-post)
18+
- [Delete Blog Post](#delete-blog-post)
19+
- [Get Single Blog Post](#get-single-blog-post)
20+
- [Get All Blog Posts](#get-all-blog-posts)
21+
- [Search Blog Posts](#search-blog-posts)
22+
- [Project Structure](#project-structure)
23+
- [Error Handling](#error-handling)
24+
25+
## Features
26+
27+
- ✅ Create new blog posts
28+
- ✅ Update existing blog posts
29+
- ✅ Delete blog posts
30+
- ✅ Retrieve a single blog post by ID
31+
- ✅ Retrieve all blog posts
32+
- ✅ Search blog posts by term (searches in title, content, and category)
33+
- ✅ Request ID tracking for debugging
34+
- ✅ Comprehensive logging middleware
35+
- ✅ Input validation with proper error responses
36+
37+
## Tech Stack
38+
39+
- **Language:** Go 1.24
40+
- **Web Framework:** Gorilla Mux
41+
- **Database:** PostgreSQL
42+
- **Environment Management:** godotenv
43+
- **Database Driver:** lib/pq
44+
45+
## Prerequisites
46+
47+
- Go 1.24 or higher
48+
- PostgreSQL database
49+
- Git
50+
51+
## Installation
52+
53+
1. Clone the repository:
54+
```bash
55+
git clone https://github.com/architxkumar/Blogging-Platform-API.git
56+
cd Blogging-Platform-API
57+
```
58+
59+
2. Install dependencies:
60+
```bash
61+
go mod download
62+
```
63+
64+
3. Configure environment variables:
65+
66+
Create or update the `.env.development` file in the root directory:
67+
```env
68+
PGHOST=localhost
69+
PGPORT=5432
70+
PGUSER=your_postgres_user
71+
PGPASSWORD=your_postgres_password
72+
PGSSLNEGOTIATION=disable
73+
PGDATABASE=blogs
74+
```
75+
76+
## Database Setup
77+
78+
1. Create the PostgreSQL database:
79+
```sql
80+
CREATE DATABASE blogs;
81+
```
82+
83+
2. Run the schema to create the posts table:
84+
```bash
85+
psql -U your_postgres_user -d blogs -f internal/db/schema.sql
86+
```
87+
88+
The schema includes:
89+
- `posts` table with auto-incrementing ID
90+
- Automatic `created_at` and `updated_at` timestamp management
91+
- Support for arrays (tags)
92+
93+
3. (Optional) Load sample data:
94+
```bash
95+
psql -U your_postgres_user -d blogs -f internal/db/sample_posts_insert.sql
96+
```
97+
98+
## Running the Application
99+
100+
Start the server:
101+
```bash
102+
go run main.go
103+
```
104+
105+
The API will be available at `http://localhost:8080`
106+
107+
## API Endpoints
108+
109+
### Create Blog Post
110+
111+
Create a new blog post.
112+
113+
**Endpoint:** `POST /posts`
114+
115+
**Request Body:**
116+
```json
117+
{
118+
"title": "My First Blog Post",
119+
"content": "This is the content of my first blog post.",
120+
"category": "Technology",
121+
"tags": ["Tech", "Programming"]
122+
}
123+
```
124+
125+
**Validation Rules:**
126+
- `title`: Required, maximum 255 characters
127+
- `content`: Required
128+
- `category`: Optional, maximum 30 characters
129+
- `tags`: Optional, array of strings
130+
131+
**Success Response (201 Created):**
132+
```json
133+
{
134+
"id": 1,
135+
"title": "My First Blog Post",
136+
"content": "This is the content of my first blog post.",
137+
"category": "Technology",
138+
"tags": ["Tech", "Programming"],
139+
"created_at": "2021-09-01T12:00:00Z",
140+
"updated_at": "2021-09-01T12:00:00Z"
141+
}
142+
```
143+
144+
**Error Responses:**
145+
- `400 Bad Request` - Invalid JSON format or empty request body
146+
- `422 Unprocessable Entity` - Validation errors (empty title, title too long, empty content, category too long)
147+
148+
---
149+
150+
### Update Blog Post
151+
152+
Update an existing blog post.
153+
154+
**Endpoint:** `PUT /posts/{id}`
155+
156+
**URL Parameters:**
157+
- `id` (integer, required) - The ID of the blog post to update
158+
159+
**Request Body:**
160+
```json
161+
{
162+
"title": "My Updated Blog Post",
163+
"content": "This is the updated content of my first blog post.",
164+
"category": "Technology",
165+
"tags": ["Tech", "Programming", "Updated"]
166+
}
167+
```
168+
169+
**Validation Rules:**
170+
- Same as Create Blog Post
171+
- ID must be a positive integer
172+
173+
**Success Response (200 OK):**
174+
```json
175+
{
176+
"id": 1,
177+
"title": "My Updated Blog Post",
178+
"content": "This is the updated content of my first blog post.",
179+
"category": "Technology",
180+
"tags": ["Tech", "Programming", "Updated"],
181+
"created_at": "2021-09-01T12:00:00Z",
182+
"updated_at": "2021-09-01T12:30:00Z"
183+
}
184+
```
185+
186+
**Error Responses:**
187+
- `400 Bad Request` - Invalid ID format or validation errors
188+
- `404 Not Found` - Blog post with the given ID not found
189+
- `422 Unprocessable Entity` - Validation errors
190+
191+
---
192+
193+
### Delete Blog Post
194+
195+
Delete an existing blog post.
196+
197+
**Endpoint:** `DELETE /posts/{id}`
198+
199+
**URL Parameters:**
200+
- `id` (integer, required) - The ID of the blog post to delete
201+
202+
**Success Response (204 No Content):**
203+
No response body
204+
205+
**Error Responses:**
206+
- `400 Bad Request` - Invalid ID format
207+
- `404 Not Found` - Blog post with the given ID not found
208+
209+
---
210+
211+
### Get Single Blog Post
212+
213+
Retrieve a single blog post by ID.
214+
215+
**Endpoint:** `GET /posts/{id}`
216+
217+
**URL Parameters:**
218+
- `id` (integer, required) - The ID of the blog post to retrieve
219+
220+
**Success Response (200 OK):**
221+
```json
222+
{
223+
"id": 1,
224+
"title": "My First Blog Post",
225+
"content": "This is the content of my first blog post.",
226+
"category": "Technology",
227+
"tags": ["Tech", "Programming"],
228+
"created_at": "2021-09-01T12:00:00Z",
229+
"updated_at": "2021-09-01T12:00:00Z"
230+
}
231+
```
232+
233+
**Error Responses:**
234+
- `400 Bad Request` - Invalid ID format
235+
- `404 Not Found` - Blog post with the given ID not found
236+
237+
---
238+
239+
### Get All Blog Posts
240+
241+
Retrieve all blog posts.
242+
243+
**Endpoint:** `GET /posts`
244+
245+
**Success Response (200 OK):**
246+
```json
247+
[
248+
{
249+
"id": 1,
250+
"title": "My First Blog Post",
251+
"content": "This is the content of my first blog post.",
252+
"category": "Technology",
253+
"tags": ["Tech", "Programming"],
254+
"created_at": "2021-09-01T12:00:00Z",
255+
"updated_at": "2021-09-01T12:00:00Z"
256+
},
257+
{
258+
"id": 2,
259+
"title": "My Second Blog Post",
260+
"content": "This is the content of my second blog post.",
261+
"category": "Lifestyle",
262+
"tags": ["Life", "Tips"],
263+
"created_at": "2021-09-01T12:30:00Z",
264+
"updated_at": "2021-09-01T12:30:00Z"
265+
}
266+
]
267+
```
268+
269+
---
270+
271+
### Search Blog Posts
272+
273+
Search and filter blog posts by a search term. The search is performed on the `title`, `content`, and `category` fields using a wildcard (LIKE) query.
274+
275+
**Endpoint:** `GET /posts?term={search_term}`
276+
277+
**Query Parameters:**
278+
- `term` (string, optional) - Search term to filter posts
279+
280+
**Example Request:**
281+
```
282+
GET /posts?term=tech
283+
```
284+
285+
This will return all blog posts that contain "tech" (case-insensitive) in their title, content, or category.
286+
287+
**Success Response (200 OK):**
288+
```json
289+
[
290+
{
291+
"id": 1,
292+
"title": "My First Blog Post",
293+
"content": "This is the content about technology.",
294+
"category": "Technology",
295+
"tags": ["Tech", "Programming"],
296+
"created_at": "2021-09-01T12:00:00Z",
297+
"updated_at": "2021-09-01T12:00:00Z"
298+
}
299+
]
300+
```
301+
302+
**Notes:**
303+
- If no `term` parameter is provided, all posts are returned (same as Get All Blog Posts)
304+
- The search is case-insensitive
305+
- The search performs a wildcard match (partial matching)
306+
307+
---
308+
309+
## Project Structure
310+
311+
```
312+
Blogging-Platform-API/
313+
├── main.go # Application entry point
314+
├── internal/
315+
│ ├── handler/ # HTTP request handlers
316+
│ │ ├── task_creation.go # POST /posts handler
317+
│ │ ├── task_updation.go # PUT /posts/{id} handler
318+
│ │ ├── deletion.go # DELETE /posts/{id} handler
319+
│ │ └── retrival.go # GET /posts and /posts/{id} handlers
320+
│ ├── middleware/ # HTTP middlewares
321+
│ │ ├── logging.go # Request logging
322+
│ │ ├── request_id.go # Request ID generation
323+
│ │ └── validation.go # Input validation
324+
│ ├── model/ # Data models
325+
│ │ └── post.go # Post and PostDTO structs
326+
│ └── db/ # Database files
327+
│ ├── schema.sql # Database schema
328+
│ └── sample_posts_insert.sql # Sample data
329+
├── .env.development # Environment configuration
330+
├── go.mod # Go module definition
331+
└── README.md # This file
332+
```
333+
334+
## Error Handling
335+
336+
The API uses standard HTTP status codes:
337+
338+
- `200 OK` - Successful GET or PUT request
339+
- `201 Created` - Successful POST request
340+
- `204 No Content` - Successful DELETE request
341+
- `400 Bad Request` - Invalid request format or parameters
342+
- `404 Not Found` - Resource not found
343+
- `422 Unprocessable Entity` - Validation errors
344+
- `500 Internal Server Error` - Server-side errors
345+
346+
All error responses include a descriptive error message in the response body.
347+
348+
## Features Not Implemented
349+
350+
The following features are intentionally not implemented as per project requirements:
351+
- Pagination
352+
- Authentication
353+
- Authorization
354+
- Rate limiting
355+
356+
---
357+
358+
**License:** MIT
359+
360+
**Author:** Archit Kumar
361+
362+
**Repository:** [https://github.com/architxkumar/Blogging-Platform-API](https://github.com/architxkumar/Blogging-Platform-API)

0 commit comments

Comments
 (0)