Skip to main content

Advanced Features

The API supports optional HTTP features that allow you to reduce bandwidth and build more efficient clients.

Conditional Requests (ETags)​

ETags allow you to avoid downloading a full response if the data has not changed since your last request. The API supports two conditional request headers:

If-None-Match​

The most common pattern. Send the ETag from a previous response; the server will return 304 Not Modified (with no body) if the data is unchanged, or a fresh 200 OK with the new data if it has changed.

GET /v1/cache/users/dymerz HTTP/1.1
Host: api.starcitizen-api.com
x-api-key: 0d32404d021613ba948ba0aeef324ef5
If-None-Match: "a1b2c3d4e5f6"
ScenarioResponse
Data unchanged304 Not Modified — no body, use your cached copy
Data changed200 OK — full response with updated ETag

If-Match​

Sends data only if the current ETag matches the one you provide. Returns 412 Precondition Failed if it does not match.

GET /v1/cache/users/dymerz HTTP/1.1
Host: api.starcitizen-api.com
x-api-key: 0d32404d021613ba948ba0aeef324ef5
If-Match: "a1b2c3d4e5f6"
tip

Store the ETag response header alongside your cached data. On the next request, send it back via If-None-Match. This is especially useful for polling endpoints like stats or versions.

JSON Path Filtering​

You can extract a specific field from the response data object using the json_path query parameter. This reduces the size of the response and simplifies client-side processing.

The $ root refers to the data field of the response — not the full envelope.

Basic example — return only the user's display name:

GET /v1/cache/users/dymerz?json_path=$.profile.display HTTP/1.1
Host: api.starcitizen-api.com
x-api-key: 0d32404d021613ba948ba0aeef324ef5
{
  "message": "ok",
  "success": 1,
  "source": "cache",
  "data": "[ΩP] Dymerz"
}

Advanced example — filter roadmap cards where completed = 0:

?json_path=$[*].cards[?(completed=0)]
warning

Special characters in JSON path expressions must be URL-encoded. For example:

  • $ → %24
  • [ → %5B
  • ] → %5D
  • * → %2A

Most HTTP clients and libraries handle this automatically.

JSON Path uses the python-jsonpath-rw-ext syntax. Refer to its documentation for the full expression reference.