> ## Documentation Index
> Fetch the complete documentation index at: https://dos.dzaleka.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Complete guide to the Dzaleka Online Services API

## Introduction

The Dzaleka Online Services API provides programmatic access to community data including services, events, news, jobs, resources, and more. The API is built on Astro and uses a RESTful architecture with JSON responses.

<Info>
  The API is currently **public and free to use** with rate limiting to ensure fair usage.
</Info>

## Base URL

All API requests should be made to:

```text theme={null}
https://services.dzaleka.com/api
```

## Available Endpoints

The API provides access to the following collections:

<CardGroup cols={2}>
  <Card icon="briefcase" href="/api/services" title="Services">
    Community services and organizations
  </Card>

  <Card icon="calendar" href="/api/events" title="Events">
    Upcoming and past community events
  </Card>

  <Card icon="newspaper" href="/api/news" title="News">
    Latest news and announcements
  </Card>

  <Card icon="user-tie" href="/api/jobs" title="Jobs">
    Job opportunities and listings
  </Card>

  <Card icon="book" href="/api/resources" title="Resources">
    Educational and community resources
  </Card>

  <Card icon="image" href="/api/photos" title="Photos">
    Community photo gallery
  </Card>

  <Card icon="user" href="/api/profiles" title="Profiles">
    Community member profiles
  </Card>

  <Card icon="star" href="/api/talents" title="Talents">
    Showcase of community talents
  </Card>

  <Card icon="cloud" href="/api/weather" title="Weather">
    Local weather forecast for Dowa district
  </Card>

  <Card icon="magnifying-glass" href="/api/search" title="Search">
    Search across all collections
  </Card>
</CardGroup>

## API Architecture

### Collection Endpoints

Most endpoints follow a standardized pattern using shared utility functions from `src/utils/api-utils.ts:118-159`:

* **GET** requests fetch all items in a collection
* **POST** requests fetch items with optional filters and metadata
* **OPTIONS** requests handle CORS preflight

### Standard Response Format

All successful API responses follow this structure:

```json theme={null}
{
  "status": "success",
  "count": 25,
  "data": {
    "services": [
      {
        "id": "example-service",
        "collection": "services",
        "title": "Example Service",
        "description": "Service description",
        "category": "Healthcare",
        "...": "..."
      }
    ]
  }
}
```

<Note>
  The exact fields in each data object depend on the collection type. All items include `id` and `collection` fields.
</Note>

## Making Requests

### GET Request Example

Fetch all services:

```bash theme={null}
curl https://services.dzaleka.com/api/services
```

Response:

```json theme={null}
{
  "status": "success",
  "count": 15,
  "data": {
    "services": [
      {
        "id": "healthcare-center",
        "collection": "services",
        "title": "Dzaleka Health Center",
        "description": "Primary healthcare services",
        "category": "Healthcare"
      }
    ]
  }
}
```

### POST Request Example

Fetch services with metadata:

```bash theme={null}
curl -X POST https://services.dzaleka.com/api/services \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
      "includeMetadata": true,
      "includeStats": true
    }
  }'
```

Response:

```json theme={null}
{
  "status": "success",
  "count": 15,
  "data": {
    "services": [...]
  },
  "metadata": {
    "exportDate": "2026-03-09T10:30:00.000Z",
    "collection": "services"
  },
  "stats": {
    "totalItems": 15,
    "collection": "services"
  }
}
```

### Search Request Example

Search across multiple collections:

```bash theme={null}
curl "https://services.dzaleka.com/api/search?q=education&collections=services,resources&limit=5"
```

Response:

```json theme={null}
{
  "status": "success",
  "query": "education",
  "totalResults": 8,
  "results": {
    "services": [
      {
        "slug": "education-center",
        "title": "Community Education Center",
        "description": "Adult education programs",
        "collection": "services",
        "url": "/services/education-center"
      }
    ],
    "resources": [...]
  },
  "cached": false
}
```

<Tip>
  Search results are cached for 5 minutes to improve performance. Check the `cached` field and `X-Cache` header.
</Tip>

## Error Handling

The API uses standard HTTP status codes and returns errors in a consistent format:

### Error Response Format

```json theme={null}
{
  "status": "error",
  "message": "Descriptive error message",
  "error": "Technical error details"
}
```

### Common HTTP Status Codes

<ResponseField name="200" type="Success">
  Request completed successfully
</ResponseField>

<ResponseField name="400" type="Bad Request">
  Invalid request parameters (e.g., search query too short)
</ResponseField>

<ResponseField name="429" type="Rate Limit Exceeded">
  Too many requests. See [Rate Limits](/api/rate-limits) for details
</ResponseField>

<ResponseField name="500" type="Internal Server Error">
  Server error while processing the request
</ResponseField>

### Error Handling Example

```bash theme={null}
curl "https://services.dzaleka.com/api/search?q=a"
```

Response (400 Bad Request):

```json theme={null}
{
  "status": "error",
  "message": "Search query must be at least 2 characters long"
}
```

## Response Headers

All API responses include standard headers for CORS and caching:

```http theme={null}
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type
```

Some endpoints include additional headers:

* `X-Cache`: `HIT` or `MISS` (for cached responses)
* `Cache-Control`: Caching directives for client-side caching
* `X-RateLimit-*`: Rate limit information (see [Rate Limits](/api/rate-limits))

## Best Practices

<AccordionGroup>
  <Accordion title="Respect Rate Limits">
    Stay within the 60 requests per minute limit. Implement exponential backoff when receiving 429 responses.
  </Accordion>

  <Accordion title="Cache Responses">
    Many endpoints include `Cache-Control` headers. Implement client-side caching to reduce API calls.
  </Accordion>

  <Accordion title="Handle Errors Gracefully">
    Always check the `status` field in responses and handle errors appropriately.
  </Accordion>

  <Accordion title="Use POST for Complex Queries">
    When you need metadata or statistics, use POST requests with the `options` parameter.
  </Accordion>

  <Accordion title="Specify Search Collections">
    When using the search endpoint, specify only the collections you need to improve performance.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card icon="lock" href="/api/authentication" title="Authentication">
    Learn about CORS and required headers
  </Card>

  <Card icon="gauge" href="/api/rate-limits" title="Rate Limits">
    Understand rate limiting and how to handle it
  </Card>
</CardGroup>