API Reference Overview

Y3NKO uses a combination of Next.js API Routes and Server Actions for data operations.

API Design Principles

RESTful conventions where practical
Server Actions for mutations from React components
API Routes for webhooks and external integrations
Consistent error handling with proper status codes
Type-safe with Zod validation

When to Use What

Use Case	Solution
Reading data in Server Components	Direct Prisma queries
Mutations from forms	Server Actions
Webhooks (Paystack, etc.)	API Routes
External integrations	API Routes
Client-side data fetching	API Routes + fetch

Base URL

Development: http://localhost:3000/api
Production:  https://y3nko.travel/api

Request Format

All POST/PATCH/PUT requests expect JSON:

POST /api/bookings
Content-Type: application/json
 
{
  "listingId": "clx123...",
  "checkIn": "2024-03-15",
  "checkOut": "2024-03-18"
}

Response Format

Success Response

{
  "data": {
    "id": "clx123...",
    "reference": "Y3K-ABC123",
    "status": "PENDING"
  }
}

List Response with Pagination

{
  "data": [
    { "id": "clx1...", "title": "Beach Villa" },
    { "id": "clx2...", "title": "Mountain Lodge" }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 156,
    "totalPages": 8,
    "hasMore": true
  }
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Check-out date must be after check-in date",
    "details": {
      "field": "checkOut",
      "constraint": "date_after"
    }
  }
}

Authentication

Most endpoints require authentication. Include the session cookie (automatically handled by the browser) or pass the access token:

GET /api/bookings
Cookie: sb-access-token=eyJ...

For API-to-API calls:

GET /api/bookings
Authorization: Bearer eyJ...

Rate Limiting

Endpoint Type	Limit
Public GET	100/minute
Authenticated GET	200/minute
POST/PATCH/DELETE	30/minute
Auth endpoints	10/minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1709912345

Validation

All inputs are validated server-side using Zod schemas:

// lib/validators.ts
import { z } from 'zod'
 
export const createBookingSchema = z.object({
  listingId: z.string().cuid(),
  checkIn: z.string().datetime(),
  checkOut: z.string().datetime(),
  adults: z.number().int().min(1).max(20),
  children: z.number().int().min(0).max(10).default(0),
  guestName: z.string().min(2).max(100),
  guestEmail: z.string().email(),
  guestPhone: z.string().regex(/^\+233[0-9]{9}$/),
}).refine(
  data => new Date(data.checkOut) > new Date(data.checkIn),
  { message: "Check-out must be after check-in" }
)

Common Parameters

Pagination

Parameter	Type	Default	Description
`page`	number	1	Page number
`limit`	number	20	Items per page (max 50)

Sorting

Parameter	Type	Options	Description
`sort`	string	`price_asc`, `price_desc`, `newest`, `popular`	Sort order

Date Ranges

Parameter	Type	Format	Description
`checkIn`	string	ISO 8601	Start date
`checkOut`	string	ISO 8601	End date

API Endpoints Summary

Public Endpoints

Method	Endpoint	Description
GET	`/api/listings`	List accommodations
GET	`/api/listings/[slug]`	Get listing details
GET	`/api/listings/featured`	Get featured listings
GET	`/api/destinations`	List destinations

Authenticated Endpoints

Method	Endpoint	Description
GET	`/api/bookings`	List user’s bookings
POST	`/api/bookings`	Create booking
GET	`/api/bookings/[ref]`	Get booking details
POST	`/api/bookings/[ref]/cancel`	Cancel booking
GET	`/api/favorites`	List favorites
POST	`/api/favorites/toggle`	Toggle favorite

Payment Endpoints

Method	Endpoint	Description
POST	`/api/payments/initialize`	Initialize payment
GET	`/api/payments/[ref]/status`	Check payment status
POST	`/api/webhooks/paystack`	Paystack webhook

Admin Endpoints

Method	Endpoint	Description
GET	`/api/admin/bookings`	List all bookings
POST	`/api/admin/listings`	Create listing
PATCH	`/api/admin/listings/[id]`	Update listing
DELETE	`/api/admin/listings/[id]`	Delete listing

Server Actions are preferred for mutations in React components. API routes are used for webhooks and external integrations.

Payment Integration Authentication