Skip to main content

​
Authentication

The Dzaleka Online Services API is currently a public API and does not require authentication keys or tokens.
All endpoints are publicly accessible without API keys. Rate limiting is applied based on IP address.

​
Future Authentication

While the API is currently public, future versions may introduce optional API keys for:
  • Higher rate limits
  • Access to advanced features
  • Usage analytics
  • Priority support
Any future authentication changes will be announced with ample notice and backward compatibility.

​
CORS Configuration

The API is configured to accept requests from any origin, making it easy to use in web applications.

​
CORS Headers

All API responses include the following CORS headers from src/utils/api-utils.ts:4-10: 
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type
Content-Type: application/json

​
What This Means

Requests are accepted from any domain. You can call the API from:
  • Frontend JavaScript applications
  • Mobile apps
  • Server-side applications
  • Command-line tools
The API supports three HTTP methods:
  • GET - Fetch data from collections
  • POST - Fetch data with additional options
  • OPTIONS - CORS preflight requests
Only the Content-Type header is required for POST requests with JSON payloads.

​
Required Headers

​
GET Requests

No special headers required: 
curl https://services.dzaleka.com/api/services

​
POST Requests

Include Content-Type: application/json when sending JSON data: 
curl -X POST https://services.dzaleka.com/api/services \
  -H "Content-Type: application/json" \
  -d '{"options": {"includeMetadata": true}}'

​
OPTIONS Requests

OPTIONS requests are handled automatically by browsers for CORS preflight. The server responds with a 204 No Content status and appropriate CORS headers. 
curl -X OPTIONS https://services.dzaleka.com/api/services \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: Content-Type"
Response: 
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type

​
Client IP Detection

For rate limiting purposes, the API detects your client IP from various headers to support different proxy configurations (see src/utils/api-utils.ts:24-29):
  1. x-forwarded-for (standard proxy header)
  2. x-real-ip (nginx)
  3. cf-connecting-ip (Cloudflare)
  4. Direct connection IP
If you’re behind a proxy or CDN, ensure these headers are properly configured to avoid shared rate limits.

​
Usage Examples

​
JavaScript (Fetch API)

// GET request
fetch('https://services.dzaleka.com/api/services')
  .then(response => response.json())
  .then(data => {
    console.log('Services:', data.data.services);
  })
  .catch(error => console.error('Error:', error));

// POST request with options
fetch('https://dzaleka.com/api/services', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    options: {
      includeMetadata: true,
      includeStats: true
    }
  })
})
  .then(response => response.json())
  .then(data => {
    console.log('Services:', data.data.services);
    console.log('Metadata:', data.metadata);
  });

​
JavaScript (Axios)

import axios from 'axios';

// GET request
const getServices = async () => {
  try {
    const response = await axios.get('https://services.dzaleka.com/api/services');
    console.log('Services:', response.data.data.services);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
};

// POST request
const getServicesWithMetadata = async () => {
  try {
    const response = await axios.post('https://services.dzaleka.com/api/services', {
      options: {
        includeMetadata: true,
        includeStats: true
      }
    });
    console.log('Services:', response.data.data.services);
    console.log('Stats:', response.data.stats);
  } catch (error) {
    console.error('Error:', error.response?.data || error.message);
  }
};

​
Python (requests)

import requests

# GET request
response = requests.get('https://services.dzaleka.com/api/services')
if response.status_code == 200:
    data = response.json()
    print(f"Found {data['count']} services")
    print(data['data']['services'])
else:
    print(f"Error: {response.status_code}")
    print(response.json())

# POST request with options
response = requests.post(
    'https://dzaleka.com/api/services',
    json={
        'options': {
            'includeMetadata': True,
            'includeStats': True
        }
    },
    headers={'Content-Type': 'application/json'}
)

if response.status_code == 200:
    data = response.json()
    print(f"Export date: {data['metadata']['exportDate']}")
    print(f"Total items: {data['stats']['totalItems']}")

​
cURL

# GET request
curl -X GET https://services.dzaleka.com/api/services

# POST request with JSON payload
curl -X POST https://services.dzaleka.com/api/services \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
      "includeMetadata": true,
      "includeStats": true
    }
  }'

# Search with query parameters
curl -X GET "https://services.dzaleka.com/api/search?q=education&limit=10"

​
CORS in Different Environments

​
Browser Applications

Browsers automatically handle CORS preflight requests. No special configuration needed: 
// This works in any browser
fetch('https://services.dzaleka.com/api/services')
  .then(response => response.json())
  .then(data => console.log(data));

​
Node.js Applications

Node.js doesn’t enforce CORS, so requests work without additional configuration: 
import fetch from 'node-fetch';

const response = await fetch('https://services.dzaleka.com/api/services');
const data = await response.json();

​
Mobile Applications

Mobile apps (React Native, Flutter, etc.) typically don’t have CORS restrictions: 
// React Native
fetch('https://services.dzaleka.com/api/services')
  .then(response => response.json())
  .then(data => console.log(data));

​
Security Considerations

While the API is public, please respect fair usage policies and rate limits.

​
Best Practices

  1. Don’t abuse the open CORS policy - Use the API responsibly
  2. Implement client-side rate limiting - Don’t wait for 429 errors
  3. Cache responses - Reduce unnecessary API calls
  4. Handle errors gracefully - Always check response status
  5. Monitor your usage - Track API calls in your application

​
Troubleshooting

​
Common CORS Issues

If you see CORS errors despite the permissive configuration:
  • Ensure you’re using HTTPS in production
  • Check that your request method is GET, POST, or OPTIONS
  • Verify the Content-Type header is set correctly for POST requests
OPTIONS requests should return 204. If failing:
  • Check network connectivity
  • Verify the endpoint URL is correct
  • Ensure no proxy is blocking OPTIONS requests
If multiple users share an IP:
  • Rate limits apply per IP address
  • Consider implementing request queuing
  • Contact support for enterprise solutions (future)

​
Next Steps

API Overview

Learn about available endpoints and response formats

Rate Limits

Understand rate limiting and best practices