REST API Overview

Orbem Studio exposes a REST API for game state management, player interactions, and developer tools. All endpoints are namespaced under /wp-json/orbemorder/v1/.

Table of Contents

API Architecture

graph TB
    Frontend[Game Frontend] --> REST[REST API /orbemorder/v1/]
    REST --> Explore[Explore Class]
    REST --> DevMode[Developer Mode Class]

    Explore --> Player[Player State]
    Explore --> Missions[Mission System]
    Explore --> Inventory[Inventory System]

    DevMode --> Position[Object Positioning]
    DevMode --> Creation[Object Creation]

    Player --> Meta[User Meta]
    Missions --> Meta
    Inventory --> Meta

Design Principles

REST-Based: Standard WordPress REST API infrastructure
Stateless: Each request is self-contained
Permission-Aware: Endpoints check user capabilities
JSON Communication: All data exchanged as JSON

Authentication

For Gameplay Endpoints

Most gameplay endpoints require authentication with the read capability (standard WordPress user).

Authentication Methods:

Nonce Usage:

// Nonce is provided in localized script data
const response = await fetch('/wp-json/orbemorder/v1/area/', {
  method: 'POST',
  headers: {
    'X-WP-Nonce': OrbemOrder.orbemNonce,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({area: 'level-1'})
});

For Developer Mode Endpoints

Developer Mode endpoints require the manage_options capability (Administrator role).

Endpoint Categories

Gameplay Endpoints

17 endpoints for player-facing game functionality:

See Gameplay Endpoints for complete documentation.

Developer Mode Endpoints

4 endpoints for admin-only in-game editing:

See Developer Mode Endpoints for complete documentation.

Response Format

Success Response

{
  "success": true,
  "data": {
    // Response data varies by endpoint
  }
}

Error Response

{
  "success": false,
  "data": "Error message describing what went wrong"
}

Common Response Patterns

Simple Success:

{
  "success": true,
  "data": "success"
}

Data Return:

{
  "success": true,
  "data": {
    "posts": [...],
    "meta": {...}
  }
}

Error:

{
  "success": false,
  "data": "User not authenticated"
}

Error Handling

Common Error Responses

Authentication Failure:

{
  "success": false,
  "data": "User not authenticated"
}

Permission Denied:

{
  "success": false,
  "data": "Insufficient permissions"
}

Invalid Data:

{
  "success": false,
  "data": "Invalid data point"
}

Missing Object:

{
  "success": false,
  "data": "Invalid item ID"
}

HTTP Status Codes

The API uses standard WordPress REST API status codes:

Making API Requests

From Frontend JavaScript

// Example: Save player coordinates
async function savePosition(area, top, left) {
  const response = await fetch('/wp-json/orbemorder/v1/coordinates/', {
    method: 'POST',
    headers: {
      'X-WP-Nonce': OrbemOrder.orbemNonce,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      area: area,
      top: top,
      left: left
    })
  });

  const result = await response.json();
  return result;
}

From External Applications

# Using WordPress Application Password
curl -X POST \
  -H "Authorization: Basic $(echo -n 'username:application_password' | base64)" \
  -H "Content-Type: application/json" \
  -d '{"area":"level-1"}' \
  https://yoursite.com/wp-json/orbemorder/v1/area/

Rate Limiting

WordPress does not implement rate limiting by default. Consider implementing rate limiting if exposing the API publicly.

API Versioning

Current version: v1

The API is namespaced at /orbemorder/v1/ to allow future versioning without breaking existing integrations.

Security Considerations

Nonce Verification:

Capability Checks:

Input Sanitization:

Meta Key Restrictions:

Next Steps