Ga naar hoofdinhoud

API Reference Overview

The Ever Works provides a comprehensive REST API built with Next.js API routes. This section documents all available endpoints, authentication methods, and usage examples.

Base URL​

Development: http://localhost:3000/api
Production: https://yourdomain.com/api

Authentication​

The API supports multiple authentication methods:

1. Session-based Authentication​

Used for web application requests:

// Automatic for browser requests with valid session
fetch('/api/items', {
  credentials: 'include'
})

2. API Key Authentication​

For server-to-server requests:

fetch('/api/items', {
  headers: {
    'Authorization': 'Bearer your-api-key'
  }
})

3. JWT Token Authentication​

For mobile or SPA applications:

fetch('/api/items', {
  headers: {
    'Authorization': 'Bearer your-jwt-token'
  }
})

Response Format​

All API responses follow a consistent format:

Success Response​

{
  "success": true,
  "data": {
    // Response data
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "version": "1.0.0"
  }
}

Error Response​

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": {
      "field": "email",
      "issue": "Invalid email format"
    }
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "version": "1.0.0"
  }
}

Paginated Response​

{
  "success": true,
  "data": [
    // Array of items
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8,
    "hasNext": true,
    "hasPrev": false
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "version": "1.0.0"
  }
}

HTTP Status Codes​

CodeDescription
200OK - Request successful
201Created - Resource created successfully
400Bad Request - Invalid request data
401Unauthorized - Authentication required
403Forbidden - Insufficient permissions
404Not Found - Resource not found
409Conflict - Resource already exists
422Unprocessable Entity - Validation error
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Server error

Rate Limiting​

API endpoints are rate-limited to prevent abuse:

Endpoint TypeLimitWindow
Public endpoints100 requests15 minutes
Authenticated endpoints1000 requests15 minutes
Admin endpoints5000 requests15 minutes
Webhook endpoints10000 requests15 minutes

Rate limit headers are included in responses:

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

API Endpoints Overview​

Public Endpoints​

Items​

  • GET /api/items - List items with filtering
  • GET /api/items/[id] - Get item details
  • GET /api/items/[slug] - Get item by slug

Categories​

  • GET /api/categories - List all categories
  • GET /api/categories/[slug] - Get category details

Tags​

  • GET /api/tags - List all tags
  • GET /api/tags/[slug] - Get tag details
  • GET /api/search - Search items, categories, and tags

Authentication Endpoints​

Auth​

  • POST /api/auth/signin - Sign in user
  • POST /api/auth/signout - Sign out user
  • GET /api/auth/session - Get current session
  • POST /api/auth/signup - Register new user

User Management​

  • GET /api/user/profile - Get user profile
  • PUT /api/user/profile - Update user profile
  • POST /api/user/change-password - Change password

Protected Endpoints​

Favorites​

  • GET /api/favorites - Get user favorites
  • POST /api/favorites - Add item to favorites
  • DELETE /api/favorites/[slug] - Remove from favorites

Submissions​

  • POST /api/submit - Submit new item
  • GET /api/submissions - Get user submissions
  • PUT /api/submissions/[id] - Update submission

Admin Endpoints​

Admin Items​

  • GET /api/admin/items - List all items (admin view)
  • POST /api/admin/items - Create new item
  • PUT /api/admin/items/[id] - Update item
  • DELETE /api/admin/items/[id] - Delete item
  • POST /api/admin/items/[id]/approve - Approve item
  • POST /api/admin/items/[id]/reject - Reject item

Admin Users​

  • GET /api/admin/users - List all users
  • GET /api/admin/users/[id] - Get user details
  • PUT /api/admin/users/[id] - Update user
  • DELETE /api/admin/users/[id] - Delete user
  • POST /api/admin/users/[id]/ban - Ban user

Admin Analytics​

  • GET /api/admin/stats - Get dashboard statistics
  • GET /api/admin/analytics - Get detailed analytics
  • GET /api/admin/export - Export data

Payment Endpoints​

Stripe​

  • POST /api/stripe/checkout - Create checkout session
  • POST /api/stripe/webhook - Handle Stripe webhooks
  • GET /api/stripe/subscription - Get subscription details
  • POST /api/stripe/cancel - Cancel subscription

LemonSqueezy​

  • POST /api/lemonsqueezy/checkout - Create checkout
  • POST /api/lemonsqueezy/webhook - Handle webhooks
  • GET /api/lemonsqueezy/subscription - Get subscription

Utility Endpoints​

System​

  • GET /api/version - Get API version
  • GET /api/health - Health check
  • POST /api/verify-recaptcha - Verify reCAPTCHA

Content Sync​

  • POST /api/sync - Trigger content sync
  • GET /api/sync/status - Get sync status

Query Parameters​

Common Parameters​

Pagination​

?page=1&limit=20

Sorting​

?sortBy=name&sortOrder=asc

Filtering​

?category=productivity&tags=tools,apps

Search​

?search=awesome%20tool

Items Endpoint Parameters​

ParameterTypeDescriptionDefault
pagenumberPage number1
limitnumberItems per page20
sortBystringSort fieldupdated_at
sortOrderstringSort directiondesc
categorystringFilter by category-
tagsstringFilter by tags (comma-separated)-
searchstringSearch query-
featuredbooleanShow only featured items-
statusstringFilter by statusapproved

Example Requests​

curl "https://yourdomain.com/api/items?featured=true&limit=10"

Search Items​

curl "https://yourdomain.com/api/items?search=productivity&category=tools"

Get Items by Category​

curl "https://yourdomain.com/api/items?category=development&sortBy=name"

Error Codes​

Common Error Codes​

CodeDescription
VALIDATION_ERRORRequest validation failed
AUTHENTICATION_REQUIREDUser must be authenticated
INSUFFICIENT_PERMISSIONSUser lacks required permissions
RESOURCE_NOT_FOUNDRequested resource doesn't exist
RESOURCE_CONFLICTResource already exists
RATE_LIMIT_EXCEEDEDToo many requests
INTERNAL_ERRORServer error occurred

Validation Errors​

Validation errors include detailed field information:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "fields": {
        "email": "Invalid email format",
        "password": "Password must be at least 8 characters"
      }
    }
  }
}

SDK and Client Libraries​

JavaScript/TypeScript Client​

import { ApiClient } from '@ever-works/api-client';

const client = new ApiClient({
  baseUrl: 'https://yourdomain.com/api',
  apiKey: 'your-api-key'
});

// Get items
const items = await client.items.list({
  category: 'productivity',
  limit: 10
});

// Submit item
const submission = await client.items.submit({
  name: 'Awesome Tool',
  description: 'An amazing productivity tool',
  sourceUrl: 'https://example.com'
});

React Hooks​

import { useItems, useSubmitItem } from '@ever-works/react-hooks';

function ItemsList() {
  const { data: items, loading, error } = useItems({
    category: 'productivity'
  });

  const { submitItem, loading: submitting } = useSubmitItem();

  // Component implementation
}

Webhooks​

The API supports webhooks for real-time notifications:

Supported Events​

  • item.created - New item submitted
  • item.approved - Item approved by admin
  • item.rejected - Item rejected by admin
  • user.registered - New user registered
  • payment.completed - Payment processed

Webhook Format​

{
  "event": "item.created",
  "data": {
    "id": "item-123",
    "name": "New Tool",
    "submittedBy": "user-456"
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "signature": "sha256=..."
}

Next Steps​