From 275a30ffc6a2649051d5cef65469a4d4eed6a7ae Mon Sep 17 00:00:00 2001 From: John Rouillard Date: Mon, 18 Sep 2023 01:57:50 -0400 Subject: [PATCH] docs: clarify Api version method priority; payload @apiver Define how version is determined when multiple conflicting methods are used. Add doc on use of @apiver in data payload for PUT/POST (and maybe PATCH). Now that this is defined, sent email to devel list to see if the order should be changed. The url parameter is the lowest priorty setting and will be ignored if any of the 3 higher priority methods are used. However using the url setting is the easiest for testing. --- doc/rest.txt | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/doc/rest.txt b/doc/rest.txt index c14b7952..8d34607d 100644 --- a/doc/rest.txt +++ b/doc/rest.txt @@ -222,7 +222,8 @@ Versioning Currently there is only one version of the API. Versions are simple integers. The current version is ``1``. Version selection is -implemented in the server using one of three methods: +implemented in the server using one of four methods (in priority +order, highest first): 1. Explicit version param in accept header: ``application/json; version=1`` @@ -230,7 +231,12 @@ implemented in the server using one of three methods: 2. Version suffix in vendor accept header: ``application/vnd.json.test-v1+json`` - 3. Adding version specifier in query string: ``@apiver=1`` + 3. Adding ``@apiver: 1`` in the input data wrapper (for POST, PUT) + + 4. Adding version specifier in query string: ``@apiver=1`` (for GET). + +The highest priority version method will be used if multiple +methods are used. If an explicit version is not provided, the server default is used. The server default is reported by querying the ``/rest/`` endpoint as