Skip to content

API ReferenceΒΆ

Comprehensive REST API documentation for the Spring Security Reference project. This section covers all available endpoints, authentication flows, and integration patterns.

🌐 API Architecture Overview¢

graph TD
    A[Client Request] --> B{Authentication Required?}
    B -->|No| C[Public Endpoints]
    B -->|Yes| D[Authentication Check]

    D --> E{Auth Method}
    E -->|JWT Token| F[JWT Filter]
    E -->|Token / API Key| T[Token Filter]
    E -->|Basic Auth| G[HTTP Basic<br/>not wired]
    E -->|OAuth2| H[OAuth2 Filter]
    E -->|Session| I[Session Auth]

    F --> J[Authorization Check]
    T --> J
    G -.-> J
    H --> J
    I --> J

    J --> K{Role/Permission Check}
    K -->|βœ… Authorized| L[Controller Handler]
    K -->|❌ Forbidden| M[403 Access Denied]

    C --> L
    L --> N[Business Logic]
    N --> O[JSON Response]

    D -->|❌ Invalid| P[401 Unauthorized]

    style A fill:#e1f5fe
    style F fill:#c8e6c9
    style G fill:#c8e6c9
    style H fill:#c8e6c9
    style I fill:#c8e6c9
    style L fill:#fff3e0
    style O fill:#e8f5e8

πŸ“Š API CategoriesΒΆ

πŸ”“ Public EndpointsΒΆ

No authentication required - accessible to all clients.

πŸ” Authenticated EndpointsΒΆ

Require valid authentication tokens or credentials.

πŸ‘₯ Role-Based EndpointsΒΆ

Require specific roles (ROLE_ADMIN, ROLE_USER) for access.

🎯 Method-Specific Endpoints¢

Demonstrate different authentication methods (JWT, JDBC, LDAP, OAuth2).

🎯 Quick Start¢

1. Start the ApplicationΒΆ

# Run with default profile (supports all auth methods)
./gradlew :rest-api:bootRun

# Or run with a specific profile
./gradlew :rest-api:bootRun --args='--spring.profiles.active=jwt'

2. Test Public EndpointΒΆ

curl http://localhost:8080/api/public/hello

3. Get JWT TokenΒΆ

curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=password"

4. Access Protected EndpointΒΆ

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  http://localhost:8080/api/admin/secure

πŸ“‹ Available EndpointsΒΆ

Category Endpoint Method Auth Required Role Required
Public /api/public/hello GET ❌ -
Auth /api/auth/login POST ❌ -
Auth /api/auth/info GET βœ… Any
Admin /api/admin/secure GET βœ… ROLE_ADMIN
User /api/user/secure GET βœ… ROLE_USER, ROLE_ADMIN
JDBC /api/jdbc/users GET βœ… JWT (JDBC-backed login)
LDAP /api/ldap/users GET βœ… JWT (LDAP-backed login)
OAuth2 /api/oauth2/profile GET βœ… JWT or OAuth2User session

πŸ” Authentication MethodsΒΆ

JWT Token AuthenticationΒΆ

Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...

HTTP Basic AuthenticationΒΆ

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

Not wired

No httpBasic(...) chain exists in this project β€” shown for reference only. See Authentication Methods.

OAuth2 AuthenticationΒΆ

Redirect-based OAuth2 flow with provider integration.

Session-Based AuthenticationΒΆ

Traditional session cookies with CSRF protection.

πŸŽ“ Learning PathΒΆ

BeginnerΒΆ

  1. REST Endpoints β†’ - Explore all available API endpoints
  2. Authentication Flow β†’ - Understand authentication patterns
  3. Error Handling β†’ - Learn about API error responses

AdvancedΒΆ

πŸ› οΈ Development ToolsΒΆ

Postman CollectionΒΆ

# Import the provided collection
Spring-Security-Reference-APIs-Enhanced.postman_collection.json

VS Code REST ClientΒΆ

# Use the provided .http file
api-testing.http

cURL ExamplesΒΆ

Every endpoint includes ready-to-use cURL commands.

πŸš€ Next StepsΒΆ


🌐 The API Reference provides complete documentation for integrating with our Spring Security demonstration endpoints. Each section includes practical examples and educational insights.