# Introduction

REST API for a blog platform, built with **Node.js**, **TypeScript**, **Express 5**, **MongoDB** (Mongoose), **JWT** authentication (access token + refresh cookie), and **Cloudinary** for banner uploads.

This backend is documented for API consumers: endpoints, auth usage, request/response behavior, and error handling.

## ✨ What This API Includes

* Register, login, refresh access token, logout
* User management (profile, admin-only listing and deletion)
* Blog CRUD (slug, `draft` / `published`, multipart banner)
* Comments on posts
* Like / unlike posts
* Security defaults: Helmet, CORS, global rate limiting, validator middleware

## 🧱 API Flow At A Glance

* Clients call versioned endpoints under `/api/v1`
* Protected endpoints require Bearer access token
* Token refresh is handled with `refreshToken` cookie on the refresh endpoint
* OpenAPI contract is published in `docs/openapi.json` and served at `/api-docs`

See the high-level flow in [Architecture](https://docs.blog-api.mk-ts-04.site/architecture).

## 🩺 Authentication And Security Highlights

* Access token via `Authorization: Bearer <token>`
* Refresh token via httpOnly `refreshToken` cookie
* Request validation with `express-validator`
* Standard protection headers and global rate limiting

## 🔗 Base URL And Version

* API prefix: **`/api/v1/`** (example: `https://your-host/api/v1/auth/login`)

### 🧪 Health check (no authentication)

`GET /api/v1/` returns `message`, `status`, `version`, `environment`, `uptime`, `server`, `docs`, and `timestamp`. Use it as a quick readiness and post-deploy verification endpoint.

## 🚀 Start Here

* [Installation and environment](https://docs.blog-api.mk-ts-04.site/installation)
* [Architecture](https://docs.blog-api.mk-ts-04.site/architecture)
* [OpenAPI and Swagger](https://docs.blog-api.mk-ts-04.site/openapi)
* [Authentication API](https://docs.blog-api.mk-ts-04.site/api-reference-v1/auth)
* [Database schema](https://docs.blog-api.mk-ts-04.site/data-model/schema)
* [Security and tokens](https://docs.blog-api.mk-ts-04.site/security-and-errors/authentication)

## 📚 Documentation Notes

* Swagger UI (when server is running): open `{origin}/api-docs`
* OpenAPI source: [openapi.json](https://github.com/MT-KS-04/Blog-API-Week1/blob/main/docs/openapi.json)
* Regenerate spec after API contract changes: `npm run generate:openapi` or `npm run build`

{% hint style="success" %}
After any endpoint change, regenerate and commit `docs/openapi.json` together with the code change so GitBook and Swagger stay synchronized.
{% endhint %}