Mercurial > p > roundup > code
changeset 7636:c5307dc0e8c6
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.
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Mon, 18 Sep 2023 01:57:50 -0400 |
| parents | 0f6b7a70bc43 |
| children | d745a6eb0604 |
| files | doc/rest.txt |
| diffstat | 1 files changed, 8 insertions(+), 2 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/rest.txt Mon Sep 18 01:06:24 2023 -0400 +++ b/doc/rest.txt Mon Sep 18 01:57:50 2023 -0400 @@ -222,7 +222,8 @@ 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 @@ 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