Mercurial > p > roundup > code
comparison doc/rest.txt @ 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 | 5a8a41a2e3c8 |
| children | 3eca3462ba0c |
comparison
equal
deleted
inserted
replaced
| 7635:0f6b7a70bc43 | 7636:c5307dc0e8c6 |
|---|---|
| 220 Versioning | 220 Versioning |
| 221 ---------- | 221 ---------- |
| 222 | 222 |
| 223 Currently there is only one version of the API. Versions are simple | 223 Currently there is only one version of the API. Versions are simple |
| 224 integers. The current version is ``1``. Version selection is | 224 integers. The current version is ``1``. Version selection is |
| 225 implemented in the server using one of three methods: | 225 implemented in the server using one of four methods (in priority |
| 226 order, highest first): | |
| 226 | 227 |
| 227 1. Explicit version param in accept header: | 228 1. Explicit version param in accept header: |
| 228 ``application/json; version=1`` | 229 ``application/json; version=1`` |
| 229 | 230 |
| 230 2. Version suffix in vendor accept header: | 231 2. Version suffix in vendor accept header: |
| 231 ``application/vnd.json.test-v1+json`` | 232 ``application/vnd.json.test-v1+json`` |
| 232 | 233 |
| 233 3. Adding version specifier in query string: ``@apiver=1`` | 234 3. Adding ``@apiver: 1`` in the input data wrapper (for POST, PUT) |
| 235 | |
| 236 4. Adding version specifier in query string: ``@apiver=1`` (for GET). | |
| 237 | |
| 238 The highest priority version method will be used if multiple | |
| 239 methods are used. | |
| 234 | 240 |
| 235 If an explicit version is not provided, the server default is used. | 241 If an explicit version is not provided, the server default is used. |
| 236 The server default is reported by querying the ``/rest/`` endpoint as | 242 The server default is reported by querying the ``/rest/`` endpoint as |
| 237 described above. | 243 described above. |
| 238 | 244 |