🧩 API Requirements for Event Synchronization

During the development of the MesseApp request workflow, I assumed that functionalities such as authorization
would work as described in this document.
If any of the requested functionalities do not exist or behave differently than expected,
please feel free to implement the systems as intended and notify Maurice
so that the MesseApp services can be adjusted accordingly.

1️⃣ Authentication Endpoint

Request

  • Method: GET /api/auth
  • Headers:
    • x-api-key: API key defined in the microservice configuration (ChefsInspirationEventImportOptions.ApiKey)

Expected Behavior

  • Response Code: 200 OK
  • Content Type: application/json
  • Response Body: 
      {
      "token": "abcdef12345..."
  }
  • The field token
    • must not be null or empty
    • must contain a valid Bearer token string

Error Handling

  • Any non-2xx status → the microservice logs
    Requesting authorisation at '{requestUri}'. Response: ...
    and returns null.
  • Invalid or missing token field → log entry
    Parsing response into AuthToken. and return null.

2️⃣ Event Synchronization Endpoint

Request

  • Method: GET /api/events/sync
  • Headers:
    • Authorization: Bearer {token}
  • Query Parameters:
    • since={ISO-8601-DateTime}
      • 2025-10-08T12:45:00Z
      • Retrieved from eventService.GetLastUpdateAsync()
    • cutoffYears={int} (optional) — only included when CutoffInYears ≥ 1

Expected Behavior

  • Response Code: 200 OK
  • Content Type: application/json
    • Response Body: 
      {
    "existingIds": [1, 2, 3, 4],
    "modifiedEvents": [
        {
            "id": 1,
            "name": "Example Event",
            "description": "Details ...",
            "dateStart": "2025-03-15T09:00:00Z",
            "dateEnd": "2025-03-17T17:00:00Z",
            "media": {
                "name": "banner.jpg",
                "path": "https://example.com/media/banner.jpg",
                "ext": ".jpg",
                "hash": "ABC123..."
            }
        }
    ],
    "cutoffTimestamp": "2025-10-08T00:00:00Z"
}

DTO Validation Rules

  • existingIds
    • Must not be null (empty list allowed).
    • Contains all IDs that exist in the target system (both unchanged and modified).
    • Does not contain newly created IDs.
    • Missing IDs are considered safe to delete locally.
  • modifiedEvents
    • May be empty if no new or updated events exist.
    • Must contain fully defined ImportEventDto objects.
  • cutoffTimestamp
    • Must be a valid ISO 8601 / RFC 3339 UTC timestamp (yyyy-MM-dd'T'HH:mm:ssZ).

Error Handling

  • Any non-2xx response → logged as
    Requesting EventSyncData at '{requestUri}'. Response: ...
    and returns null.
  • JSON parsing error → logged as
    Unable to Parse '{content}' from Endpoint '{url}' into type EventSyncResponseDto
    and returns null.

3️⃣ General Requirements

  • All timestamps must be in UTC, formatted as ISO 8601 / RFC 3339 (yyyy-MM-dd'T'HH:mm:ssZ).
  • All responses use application/json (UTF-8).
  • No empty or incomplete 200 responses (e.g. {} without required fields).
  • The authentication token must remain valid during the synchronization process.

✅ 4️⃣ Test Objectives (Happy Path)

A test is considered successful if:

  1. /api/auth returns 200 OK with a valid JSON object containing a token.
  2. /api/events/sync?since={ISO-8601-DateTime} — optionally with cutoffYears={int} — when called with that token:
    • Returns 200 OK
    • Deserializes correctly into an EventSyncResponseDto
    • Contains at least one existingId
    • Provides all date fields in the format yyyy-MM-dd'T'HH:mm:ssZ (ISO 8601 / RFC 3339, UTC)
    • Returns no empty required fields
    • Returns the full dataset if the cutoffYears parameter is omitted
  3. When tested in a live environment, the microservice does not log any errors or warnings containing
    “Unable to Parse” or “Requesting EventSyncData”.