From 7e1a0ac66a072bb1a9d6b45c831121fd51df7c66 Mon Sep 17 00:00:00 2001 From: Maxime Delporte Date: Fri, 10 Oct 2025 15:35:05 +0200 Subject: [PATCH] README.md : Adding API versioning section. --- README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/README.md b/README.md index 892d75e..7062b43 100644 --- a/README.md +++ b/README.md @@ -35,3 +35,11 @@ Content-Type: text/plain; charset=utf-8 status: available environment: development version: 1.0.0 + +## API Versioning + +There are two comon approaches to doing this : +1. By prefixing all URLs with your API version, like **/v1/healthcheck** or **/v2/healthcheck** +2. By using custom **Accept** and **Content-Type** headers on requests and responses to convey the API version, like **Accept: application/vnd.greenlight-v1** + +From a HTTP semantics point of view, using headers to convey the API version is the 'purer' approach. But from a user-experience point of view, using a URL prefix is arguably better. It makes it possible for developers to see which version of the API is being used at a glance, and it also means that the API can still be explored using a regular web browser (which is hearder if custom headers are required). \ No newline at end of file