Shop Microservers exposes every backend capability through a single Nginx reverse proxy. Whether you are calling from the Next.js frontend, a mobile client, or aDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/astrxnomo/shop-microservers/llms.txt
Use this file to discover all available pages before exploring further.
curl terminal session, all requests travel through the gateway and are routed to the correct internal microservice — Auth (port 3004), Catalog (port 3001), Cart (port 3002), or Orders (port 3003). The frontend itself is served at the root path and also communicates exclusively through this gateway; it never contacts a service directly.
Base URL
The default gateway base URL is:80 by default. You can override this with the GATEWAY_PORT environment variable in your .env file. The Next.js frontend reads NEXT_PUBLIC_API_URL to construct its API calls — set this to match your gateway address when deploying outside of the default Docker Compose setup.
| Variable | Purpose | Default |
|---|---|---|
GATEWAY_PORT | Public port the Nginx gateway listens on | 80 |
NEXT_PUBLIC_API_URL | Base URL the frontend uses to reach the gateway | http://localhost |
Authentication
Most endpoints require a JSON Web Token (JWT). Obtain a token by callingPOST /api/auth/register to create a new account or POST /api/auth/login to authenticate an existing one. Both endpoints return a signed JWT in the response body.
Once you have a token, attach it to every protected request using the standard Authorization header:
JWT_SECRET and expire after 7 days. The frontend stores the token in localStorage and includes it automatically on every API call.
Endpoints marked No in the Auth column below are publicly accessible and do not require an
Authorization header. All other endpoints will return 401 Unauthorized if the header is absent or the token is invalid or expired.Response Format
Every response from every microservice follows the same envelope shape, enforced by a sharedrespond() utility:
success is false, data is null, and error contains a human-readable message:
success boolean before reading data, regardless of which service handled the request.
Common HTTP Status Codes
| Status | Meaning |
|---|---|
| 200 | Success |
| 201 | Created |
| 400 | Validation error |
| 401 | Invalid or missing JWT |
| 404 | Resource not found |
| 409 | Conflict (e.g., email already registered) |
| 500 | Internal server error |
Endpoints Summary
| Method | Path | Auth | Service | Description |
|---|---|---|---|---|
| POST | /api/auth/register | No | Auth | Register a new account |
| POST | /api/auth/login | No | Auth | Login and receive JWT |
| GET | /api/catalog/products | No | Catalog | List all products |
| GET | /api/catalog/products/:id | No | Catalog | Get a product |
| PATCH | /api/catalog/products/:id/stock | No* | Catalog | Decrement stock |
| GET | /api/cart/ | Yes | Cart | Get current cart |
| POST | /api/cart/items | Yes | Cart | Add item to cart |
| DELETE | /api/cart/items/:productId | Yes | Cart | Remove item from cart |
| DELETE | /api/cart/ | Yes | Cart | Clear cart |
| GET | /api/orders/ | Yes | Orders | List orders |
| GET | /api/orders/:id | Yes | Orders | Get order by ID |
| POST | /api/orders/ | Yes | Orders | Checkout |
| GET | /health | No | Gateway | Health check |
The
PATCH /api/catalog/products/:id/stock endpoint is called internally by the Orders service during checkout to decrement product stock. It does not require a JWT in the gateway routing layer, but it is not intended for direct external use.Explore by Service
Auth: Register
Create a new user account and receive a JWT.
Catalog: Products
Browse products and retrieve stock information.
Cart: Cart
Manage the current user’s ephemeral shopping cart.
Orders: Orders
Checkout, and retrieve past order history.