Skip to main content

API v3 Best Practices

When building an integration with the Bookingkit API, it's important to consider how you retrieve and synchronize data. Following these best practices will help you build a robust and performant application while minimizing resource usage for both you and bookingkit.

Integration strategies​

Following these integration strategies will lead to a more efficient and reliable integration. By synchronizing data smartly, using webhooks, and managing tokens correctly, you will reduce resource usage on both your and Bookingkit's systems, improve your application's performance, and ensure higher data quality.

Avoid Real-Time Data Retrieval​

Continuously fetching data in real-time can negatively impact your application's performance and may lead to hitting API rate limits. A better approach is to synchronize data and store it on your side, especially for data that does not change frequently.

  • Good Practice: Synchronize static or infrequently changing data, such as experiences (events), and refresh it periodically.
  • When to use Real-Time: Fetch data in real-time only when it's absolutely necessary, for example, checking date availability right before creating a booking.

Example: Synchronizing Events​

Periodically fetch all events and store them in your local database.

# Fetch all events to store locally
curl -X GET "https://api.bookingkit.de/v3/events" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example: Checking Availability in Real-Time​

When a user is ready to book, check the availability for a specific event in real-time to ensure the data is current.

# Check availability for a specific event before booking
curl -X GET "https://api.bookingkit.de/v3/events/b589292a6b11eadff27b903f0f639065/dates?from=YYYY-MM-DD&to=YYYY-MM-DD" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Synchronize Deltas​

Instead of fetching the entire dataset every time, use the delta_since parameter to retrieve only the resources that have changed since your last synchronization. This significantly reduces the amount of data transferred and the number of requests needed.

This parameter is available on endpoints that return a list of resources, such as /orders and /events.

Example: Fetching Recently Changed Orders​

Use delta_since with a URL-encoded ISO 8601 timestamp to get orders that have been created or updated since that time.

# Fetch orders updated since a specific timestamp
curl -X GET "https://api.bookingkit.de/v3/orders?delta_since=2023-10-17T10:00:00Z" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Use Webhooks for Push Notifications​

Instead of continuously polling for changes (pulling), you can use webhooks to receive notifications whenever a specific event occurs. For example, you can configure an "order update" webhook to be notified whenever an order is created or modified. Your application would expose an endpoint that Bookingkit sends a POST request to with the relevant data.

This "push" model is far more efficient than constant polling.

You can find more details on webhooks here.

Reuse Authentication Tokens​

Generating a new authentication token for every API call is inefficient and can lead to rate limiting. Instead, you should request a token once and reuse it until it expires. Access tokens are valid for one hour.

You can find more information about authentication and token management here.

Example: Reusing a Token​

  1. Get the token:

    curl -X POST https://api.bookingkit.de/oauth/token \
      -d "grant_type=client_credentials" \
      -d "client_id=YOUR_CLIENT_ID" \
      -d "client_secret=YOUR_CLIENT_SECRET"

  2. Store the access_token and reuse it for subsequent calls:

    # First call
    curl -X GET "https://api.bookingkit.de/v3/events" \
      -H "Authorization: Bearer YOUR_STORED_ACCESS_TOKEN"

    # Second call, a few minutes later
    curl -X GET "https://api.bookingkit.de/v3/products" \
      -H "Authorization: Bearer YOUR_STORED_ACCESS_TOKEN"

Performance​

To achieve shorter response times and ensure efficient integration, it's crucial to follow these performance hints. We recommend checking response times during your implementation and adjusting request parameters as needed to optimize performance.

Avoid Using the with_count Parameter​

The with_count query parameter provides the total count of resources matching your filter. While useful, it significantly reduces query performance because it requires an additional, often expensive, database operation to count all matching items.

  • Why it's slow: It triggers a separate count query on the database, which can be slow for large datasets.
  • Recommendation: Avoid using with_count unless it is absolutely necessary for your application's logic, for example, for building pagination.

Example​

Bad Practice: Requesting the total count when you only need the first page of events.

# This request is slower because of with_count=true
curl -X GET "https://api.bookingkit.de/v3/events?limit=10&with_count=true" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Good Practice: Fetching the data without the total count.

# This request is faster as it only fetches the data
curl -X GET "https://api.bookingkit.de/v3/events?limit=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Avoid Too Many Filter Fields​

While filters are essential for narrowing down results, using an excessive number of them in a single request can lead to complex and slow database queries. Each additional filter adds another condition to the query, increasing its execution time.

  • Why it's slow: Complex queries with many conditions are harder for the database to optimize.
  • Recommendation: Use only the necessary filters to get the data you need. Instead of combining many filters, try to make more specific, targeted requests.

Example​

Bad Practice: Using an excessive number of filters.

# This query might be slow due to multiple filters
curl -X GET "https://api.bookingkit.de/v3/events?category=123&type=BOOKING&min_price=50&available_from=2025-11-01T00:00:00Z&geolocation=52.5,13.4,52.6,13.5" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Good Practice: Using fewer, more specific filters. If you need to apply many criteria, consider if it can be done in separate, more targeted queries.

# A more targeted query is generally faster
curl -X GET "https://api.bookingkit.de/v3/events?category=123&available_from=2025-11-01T00:00:00Z" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Avoid Sorting with Paging (offset)​

Combining sorting with the offset parameter for pagination can be inefficient for large datasets. The database needs to sort the entire result set before it can skip to the specified offset, which becomes increasingly slow as the offset value grows.

  • Why it's slow: The database must process and sort all rows up to the offset on every request, which is resource-intensive.
  • Recommendation: Instead of using offset to page through large, sorted lists, use other filter parameters to retrieve smaller, more manageable chunks of data. For synchronization, the delta_since parameter is the most efficient method.

Example​

Bad Practice: Paging deep into a large result set using offset.

# This can be very slow for a large offset
curl -X GET "https://api.bookingkit.de/v3/orders?offset=10000&limit=100" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Good Practice: Use time-based filtering to get manageable chunks. This is much more efficient than using offset.

# Fetch orders in a specific date range instead of using offset
curl -X GET "https://api.bookingkit.de/v3/orders?start_event_date=2025-11-01T00:00:00Z&end_event_date=2025-11-07T23:59:59Z" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Avoid Using match Query Parameters​

The match parameter performs a full-text search across multiple fields, which is significantly slower than filtering on specific, indexed fields. This type of search often prevents the database from using indexes effectively, leading to slow query performance.

  • Why it's slow: Full-text search is one of the most resource-intensive types of queries.
  • Recommendation: Whenever possible, filter by specific fields (e.g., category, accept_vendors) instead of using match.

Example​

Bad Practice: Using match for a broad search.

# This performs a slow, full-text search
curl -X GET "https://api.bookingkit.de/v3/events?match=Berlin" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Good Practice: Use specific filters for more efficient querying. For example, if you are looking for events in a specific area, using geolocation or a dedicated category is much faster.

# Use a specific filter like geolocation for better performance
curl -X GET "https://api.bookingkit.de/v3/events?geolocation=52.5,13.4,52.6,13.5" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Last updated: February 23, 2026 at 08:18 AM UTC