Skip to content

headers

headers #

HTTP header names and codecs for the CaptureGraph captured-data file API.

The API's governing convention: when a message body carries raw file bytes, its accompanying metadata travels in HTTP headers; otherwise it travels in the JSON body. The raw-body routes are the single-file transfers:

  • GET files/{path} response: the bytes' extension in X-CG-File-Extension and content version in the standard ETag (a matching If-None-Match yields 304 Not Modified).
  • PUT files/{path} request: the bytes are the body; the claimed extension rides in X-CG-File-Extension.

Orthogonally, every request carries its optional caller profile — X-CG-User-Id and X-CG-Location — so identity and place stay out of file identity entirely. All custom headers are CG-namespaced. Shared by capturegraph-server (sets/reads them) and capturegraph-sync (reads them); the iOS client mirrors them in CGHTTPHeader.

decode_location(value) #

Decode an X-CG-Location header value; raise ValueError if malformed.

Source code in capturegraph-lib/capturegraph/api_models/headers.py 
47
48
49
50
51
52
53
54
55
56
57
58
def decode_location(value: str) -> LocationModel:
    """Decode an ``X-CG-Location`` header value; raise ``ValueError`` if malformed."""
    parts = value.split(",")
    if len(parts) != 4:
        raise ValueError(f"X-CG-Location needs 4 comma-separated decimals, got {value!r}")
    latitude, longitude, altitude_meters, heading_degrees = (float(part) for part in parts)
    return LocationModel(
        latitude=latitude,
        longitude=longitude,
        altitude_meters=altitude_meters,
        heading_degrees=heading_degrees,
    )

encode_location(location) #

Encode a caller location as the X-CG-Location header value.

Four comma-separated decimals in a fixed order, "{latitude},{longitude},{altitude_meters},{heading_degrees}" — the WGS84 fields of the edu.cornell.location value.

Source code in capturegraph-lib/capturegraph/api_models/headers.py 
34
35
36
37
38
39
40
41
42
43
44
def encode_location(location: LocationModel) -> str:
    """Encode a caller location as the ``X-CG-Location`` header value.

    Four comma-separated decimals in a fixed order,
    ``"{latitude},{longitude},{altitude_meters},{heading_degrees}"`` — the WGS84
    fields of the ``edu.cornell.location`` value.
    """
    return (
        f"{location.latitude},{location.longitude},"
        f"{location.altitude_meters},{location.heading_degrees}"
    )