Copy page

Getting Started

HAL Response Format

The Cineamo API uses HAL (Hypertext Application Language) for all responses.

What is HAL?

HAL provides a consistent way to hyperlink between resources. It makes APIs self-documenting and discoverable.

Key Principles:

• Resources have their own URLs (_links.self)
• Related data is embedded (_embedded)
• Navigation is built-in (next, prev, first, last pages)
• Hypermedia-driven discoverability

Official Spec: HAL Specification

---

🎯 Why HAL?

Benefits:

1. Self-documenting - Links show what's possible
2. Consistency - Same structure everywhere
3. Built-in pagination
4. Each resource has a canonical URL
5. Easy API evolution without breaking clients

Comparison

Traditional JSON:

Code
{
  "data": [...],
  "total": 100,
  "page": 1
}

HAL:

Code
{
  "_embedded": { "cinemas": [...] },
  "_total_items": 100,
  "_page": 1,
  "_links": {
    "self": { "href": "/cinemas?page=1" },
    "next": { "href": "/cinemas?page=2" }
  }
}

---

🏗️ HAL Structure

Every HAL response has these elements:

1. Resource Properties

Direct properties (not prefixed with _):

Code
{
  "id": 123,
  "name": "Cineplex Berlin",
  "city": "Berlin"
}

2. _links - Hypermedia Links

Links to related resources and navigation:

Code
{
  "_links": {
    "self": { "href": "/cinemas/123" },
    "next": { "href": "/cinemas?page=2" }
  }
}

3. _embedded - Related Resources

Embedded collections or related data:

Code
{
  "_embedded": {
    "cinemas": [
      { "id": 1, "name": "Cinema 1" },
      { "id": 2, "name": "Cinema 2" }
    ]
  }
}

4. Pagination Metadata

Cineamo extends HAL with pagination fields:

Code
{
  "_total_items": 487,
  "_page": 1,
  "_page_count": 5
}

---

📦 Collection Response Example

Code
{
  "_total_items": 487,
  "_page": 1,
  "_page_count": 5,
  "_links": {
    "self": { "href": "/cinemas?per_page=100&page=1" },
    "next": { "href": "/cinemas?per_page=100&page=2" },
    "last": { "href": "/cinemas?per_page=100&page=5" }
  },
  "_embedded": {
    "cinemas": [
      {
        "id": 123,
        "name": "Cineplex Berlin",
        "city": "Berlin",
        "_links": {
          "self": { "href": "/cinemas/123" }
        }
      }
    ]
  }
}

Key Points:

• Collection name matches resource type: cinemas, showings
• Each item has its own _links.self
• Pagination links at root level
• Metadata at root: _total_items, _page, _page_count

---

🎬 Single Resource Example

Code
{
  "id": 123,
  "name": "Cineplex Berlin",
  "city": "Berlin",
  "_links": {
    "self": { "href": "/cinemas/123" }
  }
}

With Embedded Resources

When using embed[] parameters:

Code
{
  "id": 98765,
  "name": "Inception",
  "startDatetime": "2025-11-08T19:30:00Z",
  "_links": {
    "self": { "href": "/showings/98765" }
  },
  "_embedded": {
    "cinema": {
      "id": 123,
      "name": "Cineplex Berlin",
      "_links": {
        "self": { "href": "/cinemas/123" }
        }
      }
    },
    "content": {
      "id": 456,
      "title": "Inception",
      "_links": {
        "self": { "href": "/contents/456" }
      }
    }
  }
}

---

🧭 Accessing HAL Data

Accessing Collections

Code
const response = await fetch('https://api.cineamo.com/cinemas');
const data = await response.json();

// Access collection
const cinemas = data._embedded.cinemas;

// Access pagination
const totalItems = data._total_items;
const currentPage = data._page;
const totalPages = data._page_count;

// Check for next page
const hasNextPage = !!data._links.next;

Following Links

Code
// Get next page link
const nextPageUrl = data._links.next?.href;

if (nextPageUrl) {
  const nextResponse = await fetch(`https://api.cineamo.com${nextPageUrl}`);
}

Accessing Embedded Resources

Code
const showings = data._embedded.showings;

showings.forEach(showing => {
  const movieTitle = showing._embedded?.content?.title;
  const cinemaName = showing._embedded?.cinema?.name;
});

---

⚠️ Common Pitfalls

❌ Accessing Data Directly

Code
// Wrong
const cinemas = data.cinemas; // undefined

// Correct
const cinemas = data._embedded.cinemas;

❌ Assuming Flat Pagination

Code
// Wrong
const total = data.total; // undefined

// Correct
const total = data._total_items;

❌ Ignoring Links

Code
// Wrong - hardcoding
const nextUrl = `/cinemas?page=${currentPage + 1}`;

// Correct - follow HAL links
const nextUrl = data._links.next?.href;

---

🚀 Available Links

Common link relations in Cineamo API:

Link	Description
self	Current resource URL
next	Next page in pagination
prev	Previous page in pagination
first	First page in pagination
last	Last page in pagination

---

📚 See Also

• PHP Array Parameters - Understanding array syntax in URLs
• Authentication - How to authenticate API requests
• Fetching Showtimes - Practical HAL usage examples
• API Reference - Complete endpoint documentation

Further Reading:

• HAL Specification