first commit
This commit is contained in:
Beyhan Oğur
267
belgeler/api-referans.md
Normal file
267
belgeler/api-referans.md
Normal file
@@ -0,0 +1,267 @@
|
||||
# API Referansı
|
||||
|
||||
Base URL: `http://localhost:8080`
|
||||
|
||||
---
|
||||
|
||||
## Public Endpoint'ler
|
||||
_Token gerektirmez._
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/v1/auth/register`
|
||||
|
||||
Yeni kullanıcı oluşturur ve doğrulama maili gönderir.
|
||||
|
||||
**İstek gövdesi**
|
||||
```json
|
||||
{
|
||||
"username": "ali",
|
||||
"email": "ali@ornek.com",
|
||||
"password": "gizli1234",
|
||||
"confirm_password": "gizli1234"
|
||||
}
|
||||
```
|
||||
|
||||
| Alan | Tip | Kural |
|
||||
|---|---|---|
|
||||
| `username` | string | Zorunlu, 3–50 karakter |
|
||||
| `email` | string | Zorunlu, geçerli e-posta |
|
||||
| `password` | string | Zorunlu, min 8 karakter |
|
||||
| `confirm_password` | string | Zorunlu, `password` ile aynı olmalı |
|
||||
|
||||
**Yanıtlar**
|
||||
|
||||
| Durum | Açıklama | Gövde örneği |
|
||||
|---|---|---|
|
||||
| `201 Created` | Kayıt başarılı, doğrulama maili gönderildi | `{ "message": "user created. please verify your email", "user_id": 1 }` |
|
||||
| `400 Bad Request` | Doğrulama hatası | `{ "error": "Key: 'RegisterRequest.Email' Error:..." }` |
|
||||
| `400 Bad Request` | Şifreler eşleşmiyor | `{ "error": "password and confirm_password do not match" }` |
|
||||
| `409 Conflict` | E-posta zaten kayıtlı | `{ "error": "email already in use" }` |
|
||||
| `500 Internal Server Error` | Doğrulama maili gönderilemedi | `{ "error": "failed to send verification email" }` |
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/auth/verify-email`
|
||||
|
||||
Kullanıcı email doğrulama linkindeki token ile hesabı aktive eder.
|
||||
|
||||
**Query parametreleri**
|
||||
|
||||
| Alan | Tip | Kural |
|
||||
|---|---|---|
|
||||
| `token` | string | Zorunlu |
|
||||
|
||||
**Yanıtlar**
|
||||
|
||||
| Durum | Açıklama | Gövde örneği |
|
||||
|---|---|---|
|
||||
| `200 OK` | Email doğrulandı | `{ "message": "email verified successfully" }` |
|
||||
| `400 Bad Request` | Token eksik/geçersiz | `{ "error": "invalid or expired verification token" }` |
|
||||
| `500 Internal Server Error` | Sunucu hatası | `{ "error": "could not verify email" }` |
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/v1/auth/login`
|
||||
|
||||
E-posta ve şifre ile giriş yapar; token çifti döner.
|
||||
|
||||
**İstek gövdesi**
|
||||
```json
|
||||
{
|
||||
"email": "ali@ornek.com",
|
||||
"password": "gizli1234"
|
||||
}
|
||||
```
|
||||
|
||||
**Yanıtlar**
|
||||
|
||||
| Durum | Açıklama | Gövde örneği |
|
||||
|---|---|---|
|
||||
| `200 OK` | Giriş başarılı | Aşağıya bakın |
|
||||
| `400 Bad Request` | Eksik alan | `{ "error": "..." }` |
|
||||
| `401 Unauthorized` | Yanlış bilgi | `{ "error": "invalid email or password" }` |
|
||||
| `403 Forbidden` | Email doğrulanmamış | `{ "error": "email is not verified" }` |
|
||||
|
||||
```json
|
||||
// 200 OK
|
||||
{
|
||||
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"token_type": "Bearer"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `POST /api/v1/auth/refresh`
|
||||
|
||||
Süresi dolmuş access token'ı yeniler.
|
||||
|
||||
**İstek gövdesi**
|
||||
```json
|
||||
{ "refresh_token": "eyJ..." }
|
||||
```
|
||||
|
||||
**Yanıtlar**
|
||||
|
||||
| Durum | Açıklama | Gövde örneği |
|
||||
|---|---|---|
|
||||
| `200 OK` | Yenileme başarılı | `{ "access_token": "eyJ...", "token_type": "Bearer" }` |
|
||||
| `400 Bad Request` | Eksik alan | `{ "error": "..." }` |
|
||||
| `401 Unauthorized` | Token geçersiz/süresi dolmuş | `{ "error": "invalid or expired refresh token" }` |
|
||||
| `403 Forbidden` | Email doğrulanmamış | `{ "error": "email is not verified" }` |
|
||||
|
||||
---
|
||||
|
||||
## Korumalı Endpoint'ler
|
||||
_`Authorization: Bearer <access_token>` başlığı zorunludur._
|
||||
|
||||
---
|
||||
|
||||
### `GET /api/v1/me`
|
||||
|
||||
Oturum açmış kullanıcının kimlik bilgilerini döner.
|
||||
|
||||
**İstek başlığı**
|
||||
```
|
||||
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||
```
|
||||
|
||||
**Yanıtlar**
|
||||
|
||||
| Durum | Açıklama | Gövde örneği |
|
||||
|---|---|---|
|
||||
| `200 OK` | Başarılı | `{ "user_id": 1, "email": "ali@ornek.com", "username": "ali" }` |
|
||||
| `401 Unauthorized` | Başlık eksik veya token geçersiz | `{ "error": "authorization header missing or malformed" }` |
|
||||
|
||||
---
|
||||
|
||||
## Admin Yetkisi Gerektiren Endpoint'ler
|
||||
|
||||
Bu endpointler için kullanıcı hem giriş yapmış olmalı hem de `is_admin=true` olmalıdır.
|
||||
|
||||
### Settings
|
||||
|
||||
- `PUT /api/v1/settings`
|
||||
- `POST /api/v1/settings/heroes`
|
||||
- `PUT /api/v1/settings/heroes/{id}`
|
||||
- `DELETE /api/v1/settings/heroes/{id}`
|
||||
- `POST /api/v1/settings/cors/whitelist`
|
||||
- `PUT /api/v1/settings/cors/whitelist/{id}`
|
||||
- `DELETE /api/v1/settings/cors/whitelist/{id}`
|
||||
- `POST /api/v1/settings/cors/blacklist`
|
||||
- `PUT /api/v1/settings/cors/blacklist/{id}`
|
||||
- `DELETE /api/v1/settings/cors/blacklist/{id}`
|
||||
- `POST /api/v1/settings/rate-limits`
|
||||
- `PUT /api/v1/settings/rate-limits/{id}`
|
||||
- `DELETE /api/v1/settings/rate-limits/{id}`
|
||||
|
||||
### Shop
|
||||
|
||||
- `POST /api/v1/shop/categories`
|
||||
- `PUT /api/v1/shop/categories/{id}`
|
||||
- `DELETE /api/v1/shop/categories/{id}`
|
||||
- `POST /api/v1/shop/tags`
|
||||
- `PUT /api/v1/shop/tags/{id}`
|
||||
- `DELETE /api/v1/shop/tags/{id}`
|
||||
- `POST /api/v1/shop/products`
|
||||
- `PUT /api/v1/shop/products/{id}`
|
||||
- `DELETE /api/v1/shop/products/{id}`
|
||||
|
||||
### Blog
|
||||
|
||||
- `POST /api/v1/blog/categories`
|
||||
- `PUT /api/v1/blog/categories/{id}`
|
||||
- `DELETE /api/v1/blog/categories/{id}`
|
||||
- `POST /api/v1/blog/tags`
|
||||
- `PUT /api/v1/blog/tags/{id}`
|
||||
- `DELETE /api/v1/blog/tags/{id}`
|
||||
- `POST /api/v1/blog/posts`
|
||||
- `PUT /api/v1/blog/posts/{id}`
|
||||
- `DELETE /api/v1/blog/posts/{id}`
|
||||
|
||||
---
|
||||
|
||||
## Auth Gerekli (Okuma / Kullanıcı İşlemleri)
|
||||
|
||||
### Settings (read)
|
||||
- `GET /api/v1/settings`
|
||||
- `GET /api/v1/settings/heroes`
|
||||
- `GET /api/v1/settings/cors/whitelist`
|
||||
- `GET /api/v1/settings/cors/blacklist`
|
||||
- `GET /api/v1/settings/rate-limits`
|
||||
|
||||
### Shop
|
||||
- `GET /api/v1/shop/categories`
|
||||
- `GET /api/v1/shop/tags`
|
||||
- `GET /api/v1/shop/products`
|
||||
- `GET /api/v1/shop/products/{id}`
|
||||
- `GET /api/v1/shop/cart`
|
||||
- `POST /api/v1/shop/cart/items`
|
||||
- `PUT /api/v1/shop/cart/items/{itemId}`
|
||||
- `DELETE /api/v1/shop/cart/items/{itemId}`
|
||||
|
||||
### Blog
|
||||
- `GET /api/v1/blog/categories`
|
||||
- `GET /api/v1/blog/tags`
|
||||
- `GET /api/v1/blog/posts`
|
||||
- `GET /api/v1/blog/posts/{id}`
|
||||
|
||||
---
|
||||
|
||||
## Runtime Güvenlik Davranışı
|
||||
|
||||
- **CORS blacklist**: origin varsa doğrudan blok (`403`).
|
||||
- **CORS whitelist**: origin whitelist'te ise rate-limit muaf.
|
||||
- **Whitelist/blacklist dışı**: CORS geçer, rate-limit uygulanır.
|
||||
- **Rate limit kural sırası**:
|
||||
1. Endpoint adı (`api/v1/auth/login` gibi)
|
||||
2. Fallback `api`
|
||||
|
||||
> En güncel endpoint listesi ve request/response şemaları için Swagger UI kullanın.
|
||||
|
||||
---
|
||||
|
||||
## Hata Formatı
|
||||
|
||||
Tüm hata yanıtları aynı yapıdadır:
|
||||
|
||||
```json
|
||||
{ "error": "açıklayıcı hata mesajı" }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## curl Örnekleri
|
||||
|
||||
```bash
|
||||
# Kayıt
|
||||
curl -X POST http://localhost:8080/api/v1/auth/register \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username":"ali","email":"ali@ornek.com","password":"gizli1234","confirm_password":"gizli1234"}'
|
||||
|
||||
# Email doğrulama
|
||||
curl "http://localhost:8080/api/v1/auth/verify-email?token=<verification_token>"
|
||||
|
||||
# Giriş
|
||||
curl -X POST http://localhost:8080/api/v1/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"email":"ali@ornek.com","password":"gizli1234"}'
|
||||
|
||||
# Korumalı endpoint
|
||||
curl http://localhost:8080/api/v1/me \
|
||||
-H "Authorization: Bearer <access_token>"
|
||||
|
||||
# Token yenile
|
||||
curl -X POST http://localhost:8080/api/v1/auth/refresh \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"refresh_token":"<refresh_token>"}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Swagger
|
||||
|
||||
- UI: `http://localhost:8080/swagger/index.html`
|
||||
- OpenAPI dosyaları: `docs/swagger.json`, `docs/swagger.yaml`
|
||||
Reference in New Issue
Block a user