Katkat
Back

Implement a REST GET Endpoint and Evolve Its Contract Safely

GeneralmotorsSoftware Engineer · Technical Screen
MediumSoftware EngineerTechnical ScreenSoftware Engineering Fundamentals

Last updated

Tests understanding of RESTful API design principles, HTTP semantics, robust error handling, and strategies for backwards-compatible contract evolution.

Scenario

You are building a backend service for a connected vehicle fleet management platform. Mobile apps, partner integrations, and internal dashboards need to retrieve the latest operational state of an individual vehicle (e.g., fuel level, odometer, battery state of charge, tire pressures, and location).

Design the GET endpoint for vehicle telemetry and walk through how you would evolve the API contract over time without breaking existing clients.

Requirements

1. Endpoint Design and HTTP Semantics

  • Define the URI path, query parameters, headers, and response structure (JSON).
  • Explain what makes GET both safe and idempotent, and how your implementation guarantees these properties.
  • Specify cache control headers (ETag, Cache-Control, Last-Modified) to prevent unnecessary database hits for polling clients.

2. Error Handling & Edge Cases

  • Define the HTTP status codes and structured error payload returned for:
    • Invalid vehicle identifier format (e.g., malformed VIN).
    • Non-existent vehicle.
    • Unauthorized/unauthenticated requests.
    • Vehicle exists, but no telemetry has ever been recorded.
    • Downstream telemetry datastore timeout.
  • Follow RFC 7807 (Problem Details for HTTP APIs) or a consistent error envelope.

3. Contract Evolution & Compatibility

Suppose the vehicle platform introduces electric vehicles (EVs) alongside combustion engine vehicles. The contract needs to evolve:

  • Replace the scalar fuel_level_percent with a polymorphic energy_source object supporting both battery state-of-charge and liquid fuel tank volume.
  • Add a required user-facing unit preference (e.g., metric vs. imperial).

Detail how you would introduce these changes safely:

  • Which versioning strategy would you choose (URI path, query parameter, or custom header/media type) and why?
  • How do you support older client versions during the transition window?
  • What deprecation schedule and headers (e.g., Sunset, Deprecation) would you use to communicate impending deprecation to external API consumers?

Hints

Hint 1

A safe method must not alter server state observable to clients, while idempotency ensures multiple identical requests yield the same outcome.

Hint 2

For evolving response schemas without breaking older mobile clients, prefer additive non-breaking changes first, such as serving both legacy and new fields in parallel before initiating formal version transitions.

Hint 3

Leverage standard headers like ETag with 304 Not Modified responses to optimize high-frequency polling from mobile dashboards.

Follow-up questions

  • How would you handle partial responses or field filtering (e.g., `?fields=odometer,battery`) to reduce network payload over cellular links?
  • If clients poll this endpoint every 5 seconds, how would you protect your backend using rate limiting and conditional requests?
  • How does your database read model support this endpoint if raw telemetry events are streaming into an append-only event log (e.g., Kafka)?