MeinholC/Veranstaltungen-APP
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
79755d2421
Veranstaltungen-APP/docs/USER_API_GUIDE.md

15 KiB
Raw Blame History

USER API & Password Reset Documentation

Overview

This document provides comprehensive documentation for the USER API endpoints and password reset functionality of the Veranstaltungen APP. The USER API allows authenticated users to manage their profiles, events, and favorites.

Table of Contents

  1. Authentication
  2. Password Reset System
  3. USER API Endpoints
  4. Web UI Pages
  5. Integration Examples
  6. Error Handling

Authentication

Token-Based Authentication (Sanctum)

All protected endpoints require a valid authentication token sent via the Authorization header:

Authorization: Bearer YOUR_TOKEN_HERE

Obtaining a Token

Login Endpoint

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

Response (201 - Success):

{
  "success": true,
  "message": "Login erfolgreich",
  "user": {
    "id": 1,
    "name": "Test User",
    "email": "user@example.com",
    "role": "user"
  },
  "token": "1|PZHueLvJEr6d9mU1d4J7FUVJiPh0LD1Uy6S2Qc"
}

Password Reset System

1. Request Password Reset

Endpoint: POST /api/auth/forgot-password

Request a password reset link to be sent to your email.

POST /api/auth/forgot-password
Content-Type: application/json

{
  "email": "user@example.com"
}

Response (200 - Success):

{
  "success": true,
  "message": "Passwort-Zurücksetzen-Link wurde gesendet",
  "token": "your_reset_token_here"
}

Response (422 - Validation Error):

{
  "success": false,
  "message": "Validierungsfehler",
  "errors": {
    "email": ["Diese E-Mail Adresse existiert nicht"]
  }
}

2. Verify Reset Token

Endpoint: POST /api/auth/verify-reset-token

Verify if a reset token is still valid before allowing password reset.

POST /api/auth/verify-reset-token
Content-Type: application/json

{
  "email": "user@example.com",
  "token": "your_reset_token_here"
}

Response (200 - Valid Token):

{
  "success": true,
  "valid": true,
  "message": "Token ist gültig"
}

Response (422 - Invalid/Expired Token):

{
  "success": false,
  "valid": false,
  "message": "Token ist abgelaufen"
}

3. Reset Password

Endpoint: POST /api/auth/reset-password

Complete the password reset process.

POST /api/auth/reset-password
Content-Type: application/json

{
  "email": "user@example.com",
  "token": "your_reset_token_here",
  "password": "newpassword123",
  "password_confirmation": "newpassword123"
}

Response (200 - Success):

{
  "success": true,
  "message": "Passwort erfolgreich zurückgesetzt. Bitte melden Sie sich erneut an"
}

Response (422 - Validation Error):

{
  "success": false,
  "message": "Validierungsfehler",
  "errors": {
    "password": ["Passwort muss mindestens 8 Zeichen lang sein"]
  }
}

Token Validity

  • Tokens are valid for 1 hour after generation
  • Tokens are automatically invalidated after first use
  • After password reset, all existing auth tokens are revoked

USER API Endpoints

1. Get User Profile

Endpoint: GET /api/user/profile
Authentication: Required (Bearer Token)
Method: GET

Get the current authenticated user's profile information.

GET /api/user/profile
Authorization: Bearer YOUR_TOKEN_HERE

Response (200):

{
  "success": true,
  "data": {
    "id": 1,
    "name": "Test User",
    "email": "user@example.com",
    "role": "user",
    "created_at": "2024-04-14T10:00:00Z",
    "updated_at": "2024-04-14T10:00:00Z"
  }
}

2. Get User's Events

Endpoint: GET /api/user/events
Authentication: Required
Pagination: Yes (default: 15 per page)

Get all events created by the current user.

GET /api/user/events?page=1
Authorization: Bearer YOUR_TOKEN_HERE

Response (200):

{
  "success": true,
  "data": [
    {
      "id": 1,
      "title": "Großes Musikfestival",
      "description": "Ein großes Musikfestival...",
      "location": {
        "id": 1,
        "name": "Berlin",
        "slug": "berlin"
      },
      "category": {
        "id": 1,
        "name": "Musik"
      },
      "occurrences": [
        {
          "id": 1,
          "date": "2024-06-15",
          "time": "19:00:00",
          "status": "scheduled"
        }
      ],
      "created_at": "2024-04-14T10:00:00Z"
    }
  ],
  "pagination": {
    "total": 5,
    "per_page": 15,
    "current_page": 1,
    "last_page": 1
  }
}

3. Get User's Favorite Events

Endpoint: GET /api/user/favorites
Authentication: Required
Pagination: Yes (default: 15 per page)

Get all events the user has marked as favorites.

GET /api/user/favorites?page=1
Authorization: Bearer YOUR_TOKEN_HERE

Response (200): Same structure as "Get User's Events"

4. Toggle Event Favorite Status

Endpoint: POST /api/user/favorites/{event}/toggle
Authentication: Required
Method: POST

Add or remove an event from the user's favorites.

POST /api/user/favorites/1/toggle
Authorization: Bearer YOUR_TOKEN_HERE

Response (200 - Added to Favorites):

{
  "success": true,
  "message": "Event zu Favoriten hinzugefügt",
  "is_favorite": true
}

Response (200 - Removed from Favorites):

{
  "success": true,
  "message": "Event aus Favoriten entfernt",
  "is_favorite": false
}

5. Get User Statistics

Endpoint: GET /api/user/stats
Authentication: Required

Get user account statistics.

GET /api/user/stats
Authorization: Bearer YOUR_TOKEN_HERE

Response (200):

{
  "success": true,
  "data": {
    "total_events_created": 3,
    "total_favorites": 12,
    "is_organizer": false,
    "is_admin": false,
    "user_role": "user"
  }
}

Web UI Pages

Login Page

  • URL: http://localhost:8000/login
  • Template: resources/views/auth/login.blade.php
  • Features:
    • Email/password form
    • "Remember me" checkbox
    • "Forgot password?" link
    • Register link
    • Demo credentials display
    • Real-time validation

Register Page

  • URL: http://localhost:8000/register
  • Template: resources/views/auth/register.blade.php
  • Features:
    • Name, email, password fields
    • Password confirmation
    • Terms agreement checkbox
    • Error display
    • Link to login page
    • Responsive design

Forgot Password Page

  • URL: http://localhost:8000/forgot-password
  • Template: resources/views/auth/forgot-password.blade.php
  • Features:
    • Email input field
    • Reset token display (demo mode)
    • Success/error messages
    • Back to login link

Reset Password Page

  • URL: http://localhost:8000/reset-password?token=TOKEN
  • Template: resources/views/auth/reset-password.blade.php
  • Features:
    • Email, token, password fields
    • Auto-fills token from URL parameter
    • Password confirmation
    • Token verification
    • Redirects to login after success

Integration Examples

JavaScript/Frontend Integration

Login Flow

// Step 1: Send login credentials
const loginResponse = await fetch('/api/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]').content,
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'password123'
  })
});

const loginData = await loginResponse.json();

// Step 2: Store token
if (loginData.success) {
  localStorage.setItem('auth_token', loginData.token);
  localStorage.setItem('user', JSON.stringify(loginData.user));
}

// Step 3: Use token for authenticated requests
const userProfile = await fetch('/api/user/profile', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${localStorage.getItem('auth_token')}`,
    'Content-Type': 'application/json',
  }
});

Password Reset Flow

// Step 1: Request password reset
const forgotResponse = await fetch('/api/auth/forgot-password', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'user@example.com' })
});

const forgotData = await forgotResponse.json();
const resetToken = forgotData.token;

// Step 2: Verify token (optional)
const verifyResponse = await fetch('/api/auth/verify-reset-token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    token: resetToken
  })
});

// Step 3: Reset password
const resetResponse = await fetch('/api/auth/reset-password', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    token: resetToken,
    password: 'newpassword123',
    password_confirmation: 'newpassword123'
  })
});

if (resetResponse.ok) {
  // Redirect to login
  window.location.href = '/login';
}

Favorites Management

// Toggle favorite status
async function toggleFavorite(eventId) {
  const response = await fetch(`/api/user/favorites/${eventId}/toggle`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${localStorage.getItem('auth_token')}`,
      'Content-Type': 'application/json',
    }
  });

  const data = await response.json();
  if (data.success) {
    console.log(`Event is now ${data.is_favorite ? 'favorited' : 'unfavorited'}`);
  }
}

// Get all favorites
async function getFavorites() {
  const response = await fetch('/api/user/favorites?page=1', {
    headers: {
      'Authorization': `Bearer ${localStorage.getItem('auth_token')}`,
    }
  });

  const data = await response.json();
  return data.data; // Array of favorite events
}

Mobile App Integration (React Native / Flutter)

// React Native Example
import axios from 'axios';

const API_BASE_URL = 'http://localhost:8000/api';

const apiClient = axios.create({
  baseURL: API_BASE_URL,
  headers: {
    'Content-Type': 'application/json',
  }
});

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

// Login
const login = async (email, password) => {
  const { data } = await apiClient.post('/auth/login', { email, password });
  if (data.success) {
    await AsyncStorage.setItem('auth_token', data.token);
    await AsyncStorage.setItem('user', JSON.stringify(data.user));
  }
  return data;
};

// Get user profile
const getUserProfile = async () => {
  const { data } = await apiClient.get('/user/profile');
  return data.data;
};

// Get user's favorite events
const getFavoriteEvents = async (page = 1) => {
  const { data } = await apiClient.get(`/user/favorites?page=${page}`);
  return data.data;
};

Error Handling

HTTP Status Codes

Code Meaning Example
200 OK Request successful
201 Created Resource created (registration/login)
400 Bad Request Malformed request
401 Unauthorized Missing/invalid token
404 Not Found Resource not found
422 Unprocessable Entity Validation error
500 Server Error Internal server error

Error Response Format

{
  "success": false,
  "message": "Human-readable error message",
  "errors": {
    "field_name": ["Error message for this field"]
  }
}

Common Errors

Invalid Credentials

{
  "success": false,
  "message": "Ungültige Anmeldedaten"
}

Token Expired

{
  "success": false,
  "message": "Token ist abgelaufen",
  "valid": false
}

Validation Error

{
  "success": false,
  "message": "Validierungsfehler",
  "errors": {
    "email": ["E-Mail Adresse ist erforderlich"],
    "password": ["Passwort ist erforderlich"]
  }
}

Unauthorized Access

{
  "message": "Unauthenticated."
}

Demo Test Users

Test the system with these pre-configured accounts:

Email Password Role
user@example.com password123 user
organizer@example.com password123 organizer
admin@example.com password123 admin

API Security Best Practices

  1. Never share tokens - Keep tokens secure and never expose them in logs
  2. Use HTTPS - Always use HTTPS in production
  3. Token expiration - Implement automatic token refresh mechanisms
  4. Rate limiting - Implement rate limiting to prevent abuse
  5. Input validation - Always validate user input on both client and server
  6. Password requirements - Enforce strong password policies (min 8 characters)
  7. CORS headers - Configure appropriate CORS headers for your domain
  8. Environment variables - Store sensitive configuration in .env files

Testing the API with cURL

Login

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password123"
  }'

Get User Profile

curl -X GET http://localhost:8000/api/user/profile \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json"

Forgot Password

curl -X POST http://localhost:8000/api/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

Reset Password

curl -X POST http://localhost:8000/api/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "token": "YOUR_RESET_TOKEN",
    "password": "newpassword123",
    "password_confirmation": "newpassword123"
  }'

Troubleshooting

Issue: "Unauthenticated" error on protected endpoints

  • Solution: Verify token is correctly sent in Authorization: Bearer TOKEN header
  • Check token hasn't expired
  • Re-login to get a fresh token

Issue: Password reset token is invalid

  • Solution: Tokens expire after 1 hour
  • Request a new reset token
  • Verify email address matches the account

Issue: CORS errors when calling API from frontend

  • Solution: Ensure frontend domain is configured in config/cors.php
  • Use Accept: application/json header
  • Use Content-Type: application/json header

Issue: User can't register with valid email

  • Solution: Verify email isn't already registered
  • Check email format is correct
  • Verify database connection

Support & Additional Resources

  • API Documentation: /docs/API_AUTHENTICATION_GUIDE.md
  • Main README: /README.md
  • Swagger UI: http://localhost:8000/api/docs
  • Contact: [Your contact information]

Last Updated: April 14, 2024
Version: 1.0
Framework: Laravel 13.4
PHP Version: 8.5+