atahango/belgeler/API_ENDPOINTS.md

# 🌐 GAuth-Central API Endpoints

## Base URL

```
Local Development: http://localhost:8080
Production: http://your-domain.com
```

## API Version: v1

Base Path: `/v1`

---

## 📍 Endpoints

### Public Endpoints (No Authentication Required)

#### 1. Homepage
```
GET /
Content-Type: text/html
```

**Response:** HTML homepage

---

#### 2. Swagger Documentation
```
GET /docs/index.html
Content-Type: text/html
```

**Response:** Swagger UI

---

### Authentication Endpoints

#### 3. Register User
```
POST /v1/auth/register
Content-Type: application/json
Rate Limit: 3 requests / 5 minutes
```

**Request Body:**
```json
{
  "email": "user@example.com",
  "password": "SecurePass123!",
  "user_name": "username"
}
```

**Response (201):**
```json
{
  "message": "User created successfully. Please verify your email.",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "user_name": "username"
  }
}
```

**cURL Example:**
```bash
curl -X POST http://localhost:8080/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!",
    "user_name": "username"
  }'
```

---

#### 4. Login
```
POST /v1/auth/login
Content-Type: application/json
Rate Limit: 5 requests / 1 minute
```

**Request Body:**
```json
{
  "email": "user@example.com",
  "password": "SecurePass123!"
}
```

**Response (200):**
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "user_name": "username"
  }
}
```

**cURL Example:**
```bash
curl -X POST http://localhost:8080/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!"
  }'
```

---

#### 5. Email Verification
```
GET /v1/auth/verify-email?token={verification_token}
```

**Query Parameters:**
- `token` (required): Email verification token

**Response (200):**
```json
{
  "message": "Email verified successfully"
}
```

**cURL Example:**
```bash
curl -X GET "http://localhost:8080/v1/auth/verify-email?token=abc123xyz"
```

---

#### 6. OAuth Login (Google/GitHub)
```
GET /v1/auth/{provider}
```

**Parameters:**
- `provider`: `google` or `github`

**Example:**
```
http://localhost:8080/v1/auth/google
http://localhost:8080/v1/auth/github
```

**Response:** Redirects to OAuth provider

---

#### 7. OAuth Callback
```
GET /v1/auth/{provider}/callback
```

**Parameters:**
- `provider`: `google` or `github`

**Query Parameters:** (Provided by OAuth provider)
- `code`
- `state`

**Response (200):**
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "user_name": "username"
  }
}
```

---

#### 8. Refresh Token
```
POST /v1/auth/refresh
Content-Type: application/json
```

**Request Body:**
```json
{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}
```

**Response (200):**
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}
```

**cURL Example:**
```bash
curl -X POST http://localhost:8080/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "your_refresh_token_here"
  }'
```

---

### Protected Endpoints (Authentication Required)

**Note:** All protected endpoints require the `Authorization` header:
```
Authorization: Bearer {access_token}
```

---

#### 9. Get Current User
```
GET /v1/auth/me
Authorization: Bearer {access_token}
```

**Response (200):**
```json
{
  "id": "uuid",
  "email": "user@example.com",
  "user_name": "username",
  "email_verified": true,
  "created_at": "2026-02-04T00:00:00Z"
}
```

**cURL Example:**
```bash
curl -X GET http://localhost:8080/v1/auth/me \
  -H "Authorization: Bearer your_access_token_here"
```

---

#### 10. Validate Token
```
GET /v1/auth/validate
Authorization: Bearer {access_token}
```

**Response (200):**
```json
{
  "message": "Token is valid",
  "user_id": "uuid",
  "email": "user@example.com"
}
```

**cURL Example:**
```bash
curl -X GET http://localhost:8080/v1/auth/validate \
  -H "Authorization: Bearer your_access_token_here"
```

---

## 🔒 Authentication Flow

### Standard Email/Password Flow

```
1. Register
   POST /v1/auth/register
   ↓
2. Verify Email
   GET /v1/auth/verify-email?token=...
   ↓
3. Login
   POST /v1/auth/login
   ↓
4. Access Protected Resources
   GET /v1/auth/me (with Bearer token)
```

### OAuth Flow

```
1. Initiate OAuth
   GET /v1/auth/google (or /github)
   ↓
2. User authorizes on OAuth provider
   ↓
3. Callback with code
   GET /v1/auth/google/callback?code=...
   ↓
4. Access Protected Resources
   GET /v1/auth/me (with Bearer token)
```

---

## 📝 Error Responses

### Standard Error Format

```json
{
  "error": "Error message description"
}
```

### Common Error Codes

| Status Code | Meaning |
|------------|---------|
| 400 | Bad Request - Invalid input |
| 401 | Unauthorized - Invalid or missing token |
| 403 | Forbidden - Valid token but insufficient permissions |
| 404 | Not Found - Resource not found |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error |

---

## 🚦 Rate Limits

| Endpoint | Limit | Time Window |
|----------|-------|-------------|
| POST /v1/auth/register | 3 requests | 5 minutes |
| POST /v1/auth/login | 5 requests | 1 minute |
| All API endpoints | 100 requests | 1 minute |

**Rate Limit Headers:**
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1643980800
```

---

## 🔑 Authentication Headers

### Access Token
```
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

### CORS Headers
```
Origin: http://localhost:3000
Content-Type: application/json
```

---

## 🌍 CORS Configuration

**Allowed Origins:**
- `http://localhost:3000` (development)

**Allowed Methods:**
- GET, POST, PUT, PATCH, DELETE, OPTIONS

**Allowed Headers:**
- Origin, Content-Type, Accept, Authorization

**Credentials:**
- Enabled (`Access-Control-Allow-Credentials: true`)

---

## 📦 Response Examples

### Successful Response
```json
{
  "message": "Operation successful",
  "data": { ... }
}
```

### Error Response
```json
{
  "error": "Invalid credentials"
}
```

### Validation Error
```json
{
  "error": "Validation failed: email is required"
}
```

---

## 🔗 Frontend Integration

### JavaScript/TypeScript Example

```javascript
// Base URL
const API_BASE_URL = 'http://localhost:8080';

// Login
async function login(email, password) {
  const response = await fetch(`${API_BASE_URL}/v1/auth/login`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    credentials: 'include',
    body: JSON.stringify({ email, password })
  });
  
  const data = await response.json();
  
  if (response.ok) {
    localStorage.setItem('access_token', data.access_token);
    localStorage.setItem('refresh_token', data.refresh_token);
    return data;
  } else {
    throw new Error(data.error);
  }
}

// Get Current User (Protected)
async function getCurrentUser() {
  const token = localStorage.getItem('access_token');
  
  const response = await fetch(`${API_BASE_URL}/v1/auth/me`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    credentials: 'include'
  });
  
  const data = await response.json();
  
  if (response.ok) {
    return data;
  } else {
    throw new Error(data.error);
  }
}

// Register
async function register(email, password, username) {
  const response = await fetch(`${API_BASE_URL}/v1/auth/register`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    credentials: 'include',
    body: JSON.stringify({ 
      email, 
      password, 
      user_name: username 
    })
  });
  
  const data = await response.json();
  
  if (!response.ok) {
    throw new Error(data.error);
  }
  
  return data;
}
```

### Axios Example

```javascript
import axios from 'axios';

const api = axios.create({
  baseURL: 'http://localhost:8080/v1',
  withCredentials: true,
  headers: {
    'Content-Type': 'application/json'
  }
});

// Add token to requests
api.interceptors.request.use((config) => {
  const token = localStorage.getItem('access_token');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

// Login
export const login = (email, password) => 
  api.post('/auth/login', { email, password });

// Register
export const register = (email, password, user_name) => 
  api.post('/auth/register', { email, password, user_name });

// Get current user
export const getCurrentUser = () => 
  api.get('/auth/me');

// Refresh token
export const refreshToken = (refresh_token) => 
  api.post('/auth/refresh', { refresh_token });
```

---

## 🧪 Postman Collection

You can import these endpoints into Postman:

**Environment Variables:**
```
base_url: http://localhost:8080
access_token: {{access_token}}
```

**Collection Structure:**
```
GAuth-Central API
├── Public
│   ├── Register
│   ├── Login
│   ├── Verify Email
│   ├── Refresh Token
│   ├── OAuth Google
│   └── OAuth GitHub
└── Protected (Auth Required)
    ├── Get Current User
    └── Validate Token
```

---

## 📚 Additional Resources

- **Swagger Documentation**: http://localhost:8080/docs/index.html
- **API Version**: v1.0
- **Last Updated**: February 4, 2026

---

## ⚡ Quick Start

```bash
# 1. Start the server
go run main.go

# 2. Test with curl
curl http://localhost:8080/

# 3. Register a user
curl -X POST http://localhost:8080/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"test@test.com","password":"Test123!","user_name":"testuser"}'

# 4. Login
curl -X POST http://localhost:8080/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@test.com","password":"Test123!"}'

# 5. Use the token from login response
curl http://localhost:8080/v1/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"
```

---

💡 **Tip**: Use the Swagger UI at http://localhost:8080/docs/index.html for interactive API testing!