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ΒΆ
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ΒΆ
π 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ΒΆ
HTTP Basic AuthenticationΒΆ
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ΒΆ
- REST Endpoints β - Explore all available API endpoints
- Authentication Flow β - Understand authentication patterns
- Error Handling β - Learn about API error responses
AdvancedΒΆ
- Security Configuration β - Deep dive into security setup
- Authentication Methods β - Multiple auth strategies
- Testing β - API testing patterns
π οΈ Development ToolsΒΆ
Postman CollectionΒΆ
VS Code REST ClientΒΆ
cURL ExamplesΒΆ
Every endpoint includes ready-to-use cURL commands.
π Next StepsΒΆ
- REST Endpoints β - Complete endpoint reference
- Authentication Flow β - Authentication sequence diagrams
- Error Handling β - Error response patterns
- Security Configuration β - Security implementation details
π The API Reference provides complete documentation for integrating with our Spring Security demonstration endpoints. Each section includes practical examples and educational insights.