From 4e796189b23190967c0cd6010628fe4b328833dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= Date: Mon, 5 Nov 2018 12:28:30 +0200 Subject: [PATCH] Document REST API policies Added the API versioning guarantees that are currently promised. --- Documentation/REST-API/API.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/Documentation/REST-API/API.md b/Documentation/REST-API/API.md index c383b9e61..ddb0e2aac 100644 --- a/Documentation/REST-API/API.md +++ b/Documentation/REST-API/API.md @@ -55,15 +55,25 @@ the [JSON API](http://jsonapi.org/format/) specification. - [sessions](Resources-Session.md) - [users](Resources-User.md) -All of the current resources are in the `/v1/` namespace of the MaxScale REST -API. Further additions to the namespace can be added that do not break backwards -compatibility of any existing resources. - In addition to the named resources, the REST API will respond with a HTTP 200 OK response to GET requests on the root resource (`/`) as well as the namespace root resource (`/v1/`). These can be used for HTTP health checks to determine whether MaxScale is running. +## API Versioning + +All of the current resources are in the `/v1/` namespace of the MaxScale REST +API. Further additions to the namespace can be added that do not break backwards +compatibility of any existing resources. What this means in practice is that: + +* No resources or URLs will be removed +* The API will be JSON API compliant + +Note that this means that the contents of individual resources can change. New +fields can be added, old ones can be removed and the meaning of existing fields +can change. The aim is to be as backwards compatible as reasonably possible +without sacrificing the clarity and functionality of the API. + ### Resource Relationships All resources return complete JSON objects. The returned objects can have a