Implement Phase 10: REST API Endpoints (v0.10.0)
All checks were successful
Create Release Package / build-release (push) Successful in 1m10s
All checks were successful
Create Release Package / build-release (push) Successful in 1m10s
- Add complete REST API infrastructure under src/Api/ - ResponseFormatter for standardized responses - RateLimiter with tiered limits (public 60/min, availability 30/min, booking 10/min, admin 120/min) - AbstractController base class with common functionality - BuildingsController: list, get, rooms endpoints - RoomsController: list, get, availability, calendar, search endpoints - BookingsController: CRUD + confirm/check-in/check-out status transitions - GuestsController: list, get, search, booking history (admin only) - ServicesController: list, get, calculate endpoints - PricingController: calculate, seasons endpoints - API settings tab with enable/disable toggles - Comprehensive API documentation in README Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
198
README.md
198
README.md
@@ -444,6 +444,204 @@ The dashboard includes:
|
||||
- Today's check-ins/check-outs
|
||||
- Trend indicators
|
||||
|
||||
## REST API
|
||||
|
||||
The plugin provides a comprehensive REST API for integration with external applications, mobile apps, and third-party services.
|
||||
|
||||
### Enabling the API
|
||||
|
||||
1. Navigate to **WP BnB → Settings → API**
|
||||
2. Enable "Enable REST API"
|
||||
3. Optionally enable rate limiting for protection against abuse
|
||||
|
||||
### Base URL
|
||||
|
||||
All API endpoints are prefixed with:
|
||||
|
||||
```txt
|
||||
https://your-site.com/wp-json/wp-bnb/v1/
|
||||
```
|
||||
|
||||
### Authentication
|
||||
|
||||
**Public endpoints** (room listings, availability checks) require no authentication.
|
||||
|
||||
**Admin endpoints** (booking management, guest data) require authentication via:
|
||||
|
||||
- **Cookie + Nonce**: For same-domain JavaScript requests
|
||||
- **Application Passwords**: For external applications (WordPress 5.6+, recommended)
|
||||
|
||||
To create an Application Password:
|
||||
|
||||
1. Go to **Users → Profile**
|
||||
2. Scroll to "Application Passwords"
|
||||
3. Enter a name and click "Add New Application Password"
|
||||
4. Use the generated password with HTTP Basic Auth
|
||||
|
||||
```bash
|
||||
curl -u "username:app-password" https://site.com/wp-json/wp-bnb/v1/bookings
|
||||
```
|
||||
|
||||
### Public Endpoints
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
| ------ | -------- | ----------- |
|
||||
| GET | `/buildings` | List all buildings |
|
||||
| GET | `/buildings/{id}` | Get building details |
|
||||
| GET | `/buildings/{id}/rooms` | Get rooms in a building |
|
||||
| GET | `/rooms` | List/search rooms |
|
||||
| GET | `/rooms/{id}` | Get room details |
|
||||
| GET | `/rooms/{id}/availability` | Check room availability |
|
||||
| GET | `/rooms/{id}/calendar` | Get monthly calendar data |
|
||||
| POST | `/availability/search` | Search available rooms |
|
||||
| GET | `/services` | List all services |
|
||||
| GET | `/services/{id}` | Get service details |
|
||||
| POST | `/pricing/calculate` | Calculate booking price |
|
||||
| POST | `/bookings` | Create a new booking (pending status) |
|
||||
|
||||
### Admin Endpoints
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
| ------ | -------- | ----------- |
|
||||
| GET | `/bookings` | List all bookings |
|
||||
| GET | `/bookings/{id}` | Get booking details |
|
||||
| PATCH | `/bookings/{id}` | Update a booking |
|
||||
| DELETE | `/bookings/{id}` | Cancel a booking |
|
||||
| POST | `/bookings/{id}/confirm` | Confirm a pending booking |
|
||||
| POST | `/bookings/{id}/check-in` | Check in a guest |
|
||||
| POST | `/bookings/{id}/check-out` | Check out a guest |
|
||||
| GET | `/guests` | List all guests |
|
||||
| GET | `/guests/{id}` | Get guest details |
|
||||
| GET | `/guests/search` | Search guests |
|
||||
| GET | `/guests/{id}/bookings` | Get guest's booking history |
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
When enabled, rate limits are applied per client (by user ID or IP address):
|
||||
|
||||
| Type | Limit | Applies To |
|
||||
| ---- | ----- | ---------- |
|
||||
| Public | 60/min | Room/building listings |
|
||||
| Availability | 30/min | Availability and calendar endpoints |
|
||||
| Booking | 10/min | Booking creation |
|
||||
| Admin | 120/min | All admin endpoints |
|
||||
|
||||
Rate limit headers are included in responses:
|
||||
|
||||
- `X-RateLimit-Limit`: Maximum requests allowed
|
||||
- `X-RateLimit-Remaining`: Requests remaining in window
|
||||
- `X-RateLimit-Reset`: Unix timestamp when limit resets
|
||||
|
||||
### Example: Check Room Availability
|
||||
|
||||
```bash
|
||||
curl "https://site.com/wp-json/wp-bnb/v1/rooms/42/availability?check_in=2026-03-15&check_out=2026-03-20"
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"available": true,
|
||||
"room_id": 42,
|
||||
"check_in": "2026-03-15",
|
||||
"check_out": "2026-03-20",
|
||||
"nights": 5,
|
||||
"pricing": {
|
||||
"base_price": 500.00,
|
||||
"seasonal_modifier": 1.0,
|
||||
"weekend_surcharge": 40.00,
|
||||
"total": 540.00,
|
||||
"currency": "CHF"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Example: Create a Booking
|
||||
|
||||
```bash
|
||||
curl -X POST https://site.com/wp-json/wp-bnb/v1/bookings \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"room_id": 42,
|
||||
"check_in": "2026-03-15",
|
||||
"check_out": "2026-03-20",
|
||||
"guests": 2,
|
||||
"guest_info": {
|
||||
"first_name": "John",
|
||||
"last_name": "Doe",
|
||||
"email": "john@example.com",
|
||||
"phone": "+41 79 123 4567"
|
||||
},
|
||||
"services": [
|
||||
{"service_id": 5, "quantity": 1}
|
||||
],
|
||||
"notes": "Late arrival expected"
|
||||
}'
|
||||
```
|
||||
|
||||
Response:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 123,
|
||||
"reference": "BNB-2026-00042",
|
||||
"status": "pending",
|
||||
"room": {
|
||||
"id": 42,
|
||||
"title": "Deluxe Suite"
|
||||
},
|
||||
"check_in": "2026-03-15",
|
||||
"check_out": "2026-03-20",
|
||||
"nights": 5,
|
||||
"guests": 2,
|
||||
"pricing": {
|
||||
"room_total": 540.00,
|
||||
"services_total": 50.00,
|
||||
"grand_total": 590.00,
|
||||
"currency": "CHF"
|
||||
},
|
||||
"_links": {
|
||||
"self": [{"href": "https://site.com/wp-json/wp-bnb/v1/bookings/123"}]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Example: Search Available Rooms
|
||||
|
||||
```bash
|
||||
curl -X POST https://site.com/wp-json/wp-bnb/v1/availability/search \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"check_in": "2026-03-15",
|
||||
"check_out": "2026-03-20",
|
||||
"guests": 2,
|
||||
"amenities": ["wifi", "parking"]
|
||||
}'
|
||||
```
|
||||
|
||||
### Error Responses
|
||||
|
||||
Errors follow WordPress REST API conventions:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "rest_not_found",
|
||||
"message": "Room not found.",
|
||||
"data": {
|
||||
"status": 404
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Common error codes:
|
||||
|
||||
- `rest_invalid_param` (400): Invalid request parameters
|
||||
- `rest_forbidden` (403): Insufficient permissions
|
||||
- `rest_not_found` (404): Resource not found
|
||||
- `rest_conflict` (409): Booking conflict
|
||||
- `rest_rate_limit_exceeded` (429): Rate limit exceeded
|
||||
|
||||
## Frequently Asked Questions
|
||||
|
||||
### Do I need a license to use this plugin?
|
||||
|
||||
Reference in New Issue
Block a user