---
title: "Tinder API Style Guide — Part 1"
description: "Tinder’s rapid growth and expansion into domain-centric teams produced inconsistent API practices across services, including mixed error conventions, fragmented schemas, uneven versioning, unclear URIs, and weak API contracts. Part 1 presents standards for the RESTful APIs used across the platform, beginning with the URI pattern https://service-mesh-host-name/[version]/[service-name]/[resource]/[sub-resource] and guidance on concise, plural, kebab-cased paths. It defines path-prefix versioning, retaining the previous version until clients migrate and creating new versions only for breaking changes such as removing fields, changing types, or renaming fields. The guide also covers HTTP methods, standard and custom request headers, the X-Tinder- naming convention, and request tracing through MDC-populated identifiers and centralized logging. Request and response bodies, status codes, and enforcement tools are reserved for Part 2."
---

# Tinder API Style Guide — Part 1

[Tinder](https://yomu.fyi/company/tinder) · Tinder · Sep 6, 2024

**Type:** Explainer

## Summary

Tinder’s rapid growth and expansion into domain-centric teams produced inconsistent API practices across services, including mixed error conventions, fragmented schemas, uneven versioning, unclear URIs, and weak API contracts. Part 1 presents standards for the RESTful APIs used across the platform, beginning with the URI pattern https://service-mesh-host-name/\[version\]/\[service-name\]/\[resource\]/\[sub-resource\] and guidance on concise, plural, kebab-cased paths. It defines path-prefix versioning, retaining the previous version until clients migrate and creating new versions only for breaking changes such as removing fields, changing types, or renaming fields. The guide also covers HTTP methods, standard and custom request headers, the X-Tinder- naming convention, and request tracing through MDC-populated identifiers and centralized logging. Request and response bodies, status codes, and enforcement tools are reserved for Part 2.

## Context

Tinder’s growth and organizational shift to specialized, domain-centric teams led groups to develop different API practices. The resulting inconsistencies included custom error codes returned within HTTP 200 responses, fragmented client and backend schemas, inconsistent versioning, vague URI designs, and poorly designed API contracts.

## Approach / What changed

The guide documents standards for RESTful API development and states that adoption will be supported through manual and systematic audits. Part 1 defines URI patterns and naming conventions, path-prefix versioning rules, HTTP method guidance, standard and custom request-header practices, the X-Tinder- prefix, and request tracing using MDC and centralized logging.

## Takeaways

- New API versions are reserved for breaking changes, such as removing a required field, changing a field type, or renaming a field; adding fields, methods, or endpoints does not require incrementing an existing version.
- Tinder versions endpoints independently rather than tying endpoint versions to a service version or to other endpoints under the same service.
- Custom Tinder headers use the X-Tinder- prefix, while request tracing uses unique identifiers populated through Mapped Diagnostic Context and captured by the in-house logging library.

**Tags:** [Architecture](https://yomu.fyi/topic/architecture), [Observability](https://yomu.fyi/topic/observability), [REST APIs](https://yomu.fyi/topic/rest-api)

- Source: [Tinder](https://medium.com/tinder/tinder-api-style-guide-part-1-081804a7ef40)
- Source URL: https://medium.com/tinder/tinder-api-style-guide-part-1-081804a7ef40
- Ingested by Yomu: 2026-08-27T14:37:05.229Z

[Read original post](https://medium.com/tinder/tinder-api-style-guide-part-1-081804a7ef40)