Jotihunt API Documentation

Welcome to the Jotihunt API documentation. This API provides access to data for the Jotihunt scouting game in the Netherlands, including team subscriptions, area statuses, and game articles. For example:

​

API Overview

The Jotihunt API follows RESTful principles and provides data in JSON format. The base URL for all API requests is:

https://jotihunt.nl/api/2.0

The API is organized around three main resources:

​

Website Infrastructure

Jotihunt.net is hosted on DigitalOcean’s cloud infrastructure and managed through Laravel Forge for seamless deployment and server management.

​

Technology Stack

​

Hosting Architecture

• Server: DigitalOcean Droplet running Ubuntu LTS
• Deployment: Automated via Laravel Forge
• SSL: Let’s Encrypt auto-renewal
• CDN: DigitalOcean Edge Network
• Database: MySQL (version unknown)

​

Authentication

The public endpoints listed in this documentation (Subscriptions, Areas, Articles) are available without authentication.

If you are a scouting group admin needing to access these restricted endpoints, please contact the Jotihunt organization for access credentials and documentation.

​

Response Format

All API responses follow a standard format:

​

Single Resource Collections

Most endpoints return a collection of resources in a data array:

{
  "data": [
    {
      // Resource objects
    }
  ]
}

​

Paginated Resources

For the /articles endpoint, responses include pagination information:

{
  "data": [
    {
      // Article objects
    }
  ],
  "links": {
    "first": "https://jotihunt.nl/api/2.0/articles?page=1",
    "last": "https://jotihunt.nl/api/2.0/articles?page=5",
    "prev": null,
    "next": "https://jotihunt.nl/api/2.0/articles?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "links": [
      // Pagination links
    ],
    "path": "https://jotihunt.nl/api/2.0/articles",
    "per_page": 15,
    "to": 15,
    "total": 75
  }
}

​

OpenAPI Specification

Our API is documented using the OpenAPI 3.1.0 specification format. You can view or download the complete specification file for integration with API tools.

​

Rate Limiting

The API implements rate limiting to ensure fair usage. Each client is limited to 30 requests per minute. If you exceed this limit, you’ll receive a 429 Too Many Requests response.

​

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

• 200 OK: Request succeeded
• 400 Bad Request: Invalid request parameters
• 401 Unauthorized: Missing or invalid authentication
• 403 Forbidden: Valid authentication but insufficient permissions
• 404 Not Found: Resource not found
• 429 Too Many Requests: Rate limit exceeded
• 500 Server Error: Unexpected server error

Error responses include additional details:

{
  "error": 400,
  "message": "Invalid request parameters"
}

​

Test Data with Wayback Machine

Need historical data for development or testing? The Internet Archive’s Wayback Machine provides access to archived versions of the Jotihunt API. This allows you to work with real-world data without affecting the production environment.

https://archive.org/wayback/available?url=jotihunt.nl/api/2.0

{
  "archived_snapshots": {
    "closest": {
      "available": true,
      "url": "http://web.archive.org/web/20221010123456/https://jotihunt.nl/api/2.0",
      "timestamp": "20221010123456",
      "status": "200"
    }
  }
}

​

Example API Usage with Wayback

Here are some additional examples of how to interact with historical versions of the Jotihunt API using the Wayback Machine:

// Using async/await with the Wayback Machine API
async function fetchHistoricalData() {
  try {
    // First, find available snapshots
    const waybackResponse = await fetch(
      'https://archive.org/wayback/available?url=jotihunt.nl/api/2.0'
    );
    const waybackData = await waybackResponse.json();
    
    if (waybackData.archived_snapshots && waybackData.archived_snapshots.closest) {
      const archivedUrl = waybackData.archived_snapshots.closest.url;
      console.log(`Found archived version: ${archivedUrl}`);
      
      // Now fetch data from the archived API
      const apiResponse = await fetch(`${archivedUrl}/articles`);
      const apiData = await apiResponse.json();
      
      return apiData;
    } else {
      console.error('No archived snapshots found');
      return null;
    }
  } catch (error) {
    console.error('Error fetching historical data:', error);
    return null;
  }
}

// Call the function
fetchHistoricalData().then(data => console.log(data));

​

API Endpoints

Let’s explore the available endpoints in more detail: