Event Type Sync

Recommendations for synchronizing event types for offline use. Aimed at mobile clients that want to minimize downloads and the number of checks to detect changes.

Version 1 Event Type Sync

Recommended: One list, one ETag

Use the event types list API as the single source for both the event type catalog and (optionally) schemas. The response ETag reflects any change to the list or to any event type’s metadata and rendered schema (including choice lists). Use it to avoid re-downloading when nothing has changed.

Endpoint

GET /api/v1.0/activity/events/eventtypes

Query parameters

Parameter	Description
include_schema	If true, each event type in the list includes its rendered JSON schema (with choices). Prefer this for offline sync so one request gives list + schemas.
include_inactive	Include inactive event types.
updated_since	ISO date/time. Return only event types whose updated_at is on or after this time. Use for incremental sync. Note: Only event type record updates are reflected; changes to choice lists referenced in schemas do not change updated_at, so updated_since alone does not signal choice-list changes. Rely on the list ETag for that.

Optimizing “do I need to download?”

1. Store the ETag from the last successful list response (header ETag).

2. On the next sync, send a conditional request: same URL with header If-None-Match: <stored-etag>.

3. If the server responds 304 Not Modified, nothing changed — skip downloading the body and keep your cached event types.

4. If the server responds 200 OK, replace your cache with the new response and store the new ETag.

This minimizes both checks (one conditional GET) and downloads (no body when unchanged).

Optimizing full and incremental downloads

• Initial / full sync: Call the list with include_schema=true (and include_inactive if needed). You get all event types and their schemas in one response; one ETag covers the whole set.

• Incremental sync: Call the list with updated_since=<last_sync_iso>. You get only event types that changed (by updated_at). If you need to be sure choice lists are up to date, still do a conditional GET on the full list (with If-None-Match) periodically or when you suspect schema/choice changes; use 304 to avoid re-downloading when unchanged.

Example list response (with include_schema=false)

{
  "data": [
    {
      "id": "6c90e5f5-ae8e-4e7f-a8dd-26e5d2909a74",
      "has_events_assigned": true,
      "icon": "accident_rep",
      "value": "accident_rep",
      "display": "Accident",
      "ordernum": 1,
      "is_collection": false,
      "category": {
        "id": "007a45d3-2aba-4ed1-b3fc-e09fc0ad41f8",
        "value": "security",
        "display": "Security",
        "is_active": true,
        "ordernum": 1,
        "flag": "user",
        "permissions": [
          "read",
          "create",
          "delete",
          "update"
        ]
      },
      "icon_id": "accident_rep",
      "is_active": true,
      "default_priority": 300,
      "default_state": "new",
      "geometry_type": "Point",
      "resolve_time": null,
      "auto_resolve": false,
      "url": "https://easterisland.pamdas.org/api/v1.0/activity/events/eventtypes/6c90e5f5-ae8e-4e7f-a8dd-26e5d2909a74"
    }
  ]
}

Single event type (no schema)

GET /api/v1.0/activity/events/eventtypes/<eventtype_id>

Supports conditional GET (ETag). Does not support include_schema; use the list with include_schema=true or the schema endpoints below if you need schemas.

Per–event-type schema (no ETag)

GET /api/v1.0/activity/events/schema/eventtype/<eventtype_value>

Returns the full schema for one event type (by value). There is no ETag on this endpoint; prefer the list with include_schema=true for offline sync so a single ETag covers all types and schemas.

General event schema (not detailed per-type schemas)

GET /api/v1.0/activity/events/schema?format=json

Returns a general event schema — not the detailed, per-event-type schemas. Mobile developers typically call this endpoint to get the reported_by list, which is optionally collected for all event types. Use it when you need that shared list; for full per-type form definitions use the event types list with include_schema=true or the per-type schema endpoint. This endpoint has an ETag.

Example general schema (fragment)

{
  "data": {
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "required": false,
        "title": "Id"
      },
      "location": {
        "type": "string",
        "required": false,
        "title": "Location"
      }
    }
  }
}

Summary for mobile clients

Goal	Recommendation
Fewest “has anything changed?” checks	Conditional GET on GET .../events/eventtypes with If-None-Match; treat 304 as “no download needed”.
Fewest full downloads	Use the list ETag as above; only download when you get 200.
One-shot full sync	GET .../events/eventtypes?include_schema=true (and include_inactive if needed).
Incremental sync by time	GET .../events/eventtypes?updated_since=<iso>; remember updated_since does not reflect choice-list changes — use the list ETag when you need to detect those.
Where to get schemas	Detailed per-type schemas: list with include_schema=true or per-type .../events/schema/eventtype/<value>. General schema / reported_by list: .../events/schema?format=json.

---

Version 2 Event Type Sync

The v2 API exposes event types (version 2 only) under a different base path and with a resource keyed by event type value (slug) rather than UUID. Use it when your app targets v2 event types for offline sync.

V2 list and detail ETags do not include rendered schemas or choices. Both are computed from metadata only (event type and category updated_at, or model fields). They do not include a hash of the rendered schema or choice lists, so if only choice-list data changes, the list/detail ETag may stay the same and a conditional GET can return 304 even though the response body (with include_schema=true) would have changed. The schema routes below are different: their ETags are content-derived, and with pre_render=true the ETag is a hash of the rendered body, so it does move when choice lists change. When you must be sure choice lists are up to date, revalidate .../schemas?pre_render=true (or the single-type .../schema?pre_render=true) with If-None-Match instead of re-downloading blindly.

Recommended: List with conditional GET

Use the v2 event types list as the main source for the catalog and, optionally, schemas. The response ETag is computed from event type and category updated_at values (metadata only; see above). Use If-None-Match to avoid re-downloading when the list is unchanged.

Endpoint

GET /api/v2.0/activity/eventtypes

Query parameters

Parameter	Description
include_schema	If true, each event type in the list includes its raw schema (as stored). This is not a rendered schema: choice lists and $ref are not expanded. For rendered schemas (with choices), use the schema endpoints with pre_render=true (see below).
include_inactive	Include inactive event types (default is active only).
updated_since	ISO date/time. Return only event types whose updated_at is on or after this time. Use for incremental sync. Note: As in v1, only event type record updates are reflected; choice-list changes do not update updated_at.
category	Filter by category value(s).
is_collection	Filter by is_collection (true/false).

Optimizing “do I need to download?”

1. Store the ETag from the last successful list response.

2. On the next sync, send If-None-Match: <stored-etag> with the same URL (and same query params).

3. 304 Not Modified → nothing changed; keep your cache.

4. 200 OK → replace your cache and store the new ETag.

Optimizing full and incremental downloads

• Initial / full sync: Call the list with include_schema=true (and include_inactive if needed).

• Incremental sync: Use updated_since=<last_sync_iso>. For certainty about schema/choice changes, revalidate .../eventtypes/schemas?pre_render=true with If-None-Match; the list ETag is metadata-only and cannot confirm choice freshness.

Note: The v2 list ETag is based on updated_at and category updated_at only (see the V2 ETag note at the start of this section). Conditional GET still minimizes full downloads when metadata or list membership change.

Single event type (detail)

GET /api/v2.0/activity/eventtypes/<eventtype_value>

Use event type value (slug), e.g. accident_rep. UUID is also accepted for compatibility. Supports conditional GET (ETag). Use query param include_schema=true to include the event type’s raw schema in the response (not rendered; no choice expansion). The detail ETag is based on the event type’s model fields only — it does not include the rendered schema or choices, so 304 can be returned even when only choice lists have changed.

List all schemas

GET /api/v2.0/activity/eventtypes/schemas

Returns a list of schemas for all v2 event types (one entry per type, with success/failure and optional errors). Query param pre_render=true returns rendered schemas (choices expanded, refs resolved); without it, schemas are raw. To get rendered schemas with choice lists, you must use this endpoint (or the single schema endpoint below) with pre_render=true — the list/detail include_schema option does not render. The response carries an ETag (no Last-Modified) and honours If-None-Match with 304 Not Modified. Without pre_render the ETag is a digest of the stored documents, computed in the database alongside the served rows, so the validator and the body always describe the same state; a 304 saves the bandwidth and the body build, not the database read. It is shareable across users. With pre_render=true it is a hash of the rendered body: it moves when choice lists or other $ref data change, and it is per-user (rendering follows the caller’s permissions), so cache it per authenticated identity. Only a 200 carries an ETag; a 207 batch has none. pre_render yields its own ETag, and so does s_format when pre_render=true.

Single event type schema

GET /api/v2.0/activity/eventtypes/<eventtype_value>/schema

Returns the schema for one event type. pre_render=true returns the rendered schema. The response carries an ETag — a hash of the served document, shareable without pre_render and per-user with it; 304 on an If-None-Match match; no validator on a 422.

Event type updates (revision history)

GET /api/v2.0/activity/eventtypes/<eventtype_value>/updates

Returns the revision history for the event type (paginated). Each page carries an ETag — a hash of the page as served — and honours If-None-Match with 304; each page / page_size combination has its own. Use when you need to show or sync change history; not required for basic offline catalog + schema sync.

Summary for mobile clients (v2)

Goal	Recommendation
Fewest “has anything changed?” checks	Conditional GET on GET .../eventtypes with If-None-Match. Remember the list/detail ETags do not include rendered schema/choices; the schema routes’ ETags do.
One-shot full sync	GET .../eventtypes?include_schema=true (and include_inactive if needed).
Incremental sync by time	GET .../eventtypes?updated_since=<iso>.
Where to get schemas	Raw schema (in list/detail): include_schema=true. Rendered schema (choices expanded): .../eventtypes/schemas?pre_render=true or .../eventtypes/<value>/schema?pre_render=true; both schema routes carry an ETag. List + conditional GET is best for minimizing requests when raw schema is enough.
Ensuring choice lists are current	Revalidate .../eventtypes/schemas?pre_render=true with If-None-Match: its ETag is a hash of the rendered body, so a 304 guarantees your cached choices are current. The list/detail ETags are metadata-only and cannot tell you this.