# NodeHive Public API

Base URL: `https://your-site.com/nodehive-api/v1`

All endpoints require the `access nodehive public api` permission.

Language is selected via URL prefix: `/de/nodehive-api/v1/...` or `/en/nodehive-api/v1/...`

## Response Envelope

Every response uses the same envelope:

```json
// Success
{ "status": "ok", "data": { ... } }

// Error
{ "status": "error", "error": { "code": 404, "message": "Not found." } }
```

---

## Endpoints

### 1. Index — `GET /nodehive-api/v1`

Returns available languages, spaces, and all API endpoints with URLs.

**Response:**

```json
{
  "status": "ok",
  "data": {
    "name": "NodeHive Public API",
    "version": "1.0",
    "available_languages": ["de", "en"],
    "available_spaces": [
      { "id": "1", "name": "mysite.com" }
    ],
    "endpoints": [
      { "name": "Menu API", "method": "GET", "available_menus": [...] },
      { "name": "Spaces API", "method": "GET", "available_spaces": [...] }
    ]
  }
}
```

---

### 2. Menu — `GET /nodehive-api/v1/menu/{menu_id}`

Returns the full menu tree.

**Response:**

```json
{
  "status": "ok",
  "data": {
    "menu_id": "main",
    "language": "de",
    "items": [
      {
        "title": "Home",
        "url": "/",
        "description": "",
        "expanded": false,
        "weight": 0,
        "children": []
      }
    ]
  }
}
```

**Errors:**
- `403` — Excluded system menu
- `404` — Menu not found

---

### 3. Space — `GET /nodehive-api/v1/space/{space_id}`

Returns the space context: metadata, menus, content types with counts.

**Response:**

```json
{
  "status": "ok",
  "data": {
    "id": "1",
    "name": "mysite.com",
    "language": "de",
    "space_url": "https://mysite.com",
    "space_type": "website",
    "status": true,
    "created": "2024-01-15T10:30:00+01:00",
    "changed": "2024-02-20T14:22:15+01:00",
    "tags": [{ "id": "5", "name": "Production" }],
    "frontpage_node": { "id": "10", "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "title": "Home", "type": "page" },
    "menus": [
      { "id": "main", "label": "Main Navigation", "url": "https://.../menu/main" }
    ],
    "content_types": [
      { "id": "article", "label": "Article", "description": "...", "count": 42 }
    ]
  }
}
```

**Errors:**
- `404` — Space not found

---

## Typical Frontend Workflow

```
1. GET /nodehive-api/v1                          → Discover spaces and endpoints
2. GET /nodehive-api/v1/space/1                   → Get space context, menus, content types
3. GET /nodehive-api/v1/menu/main                 → Load navigation
```

For node/content access, use **JSON:API** instead of this module.

## Caching

All responses are cacheable. Cache varies by:
- `user.permissions` — anonymous vs authenticated
- `languages:language_interface` — language prefix
Cache is invalidated automatically when menus or spaces change.
