Feature #40911
Updated by Ernesto Puerta over 4 years ago
Ensure that existing endpoints comply with ("reference":https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md):
* Resource endpoints are plurals (@/hosts@, @/osds@, @/mons@, etc).
* Resources map 1:1 to logical/physical entities (there are no "glue", "proxy" or "God" Resources)
* Resource name don't include verbs (@/get-notifications@ but @/notifications@).
* Resources include proper Media Types (Vendor-Specific: `application/vnd.ceph.dashboard.osd.v1+json`).
** If Content/Media-type versioning is used, when version is not supported server must return 415 (Unsupported Media Type).
* Resources support the default actions/HTTP verbs and return the expected HTTP codes "[ref]":https://tools.ietf.org/html/rfc7231#section-4.3.3 :
** @POST@ for adding a new @Resource@ to @ResourceCollection@.
*** 201 + @Location: <URI of the new resource>@ when OK.
*** 200/204 if no new resource was created.
*** 303 if the resource already existed (@Location: <URI of the matching resource>@).
*** 400 when Resource couldn't be created due to improper data.
** @GET@ for retrieving data from a single @Resource@ and listing @Resources@.
*** 200 if OK.
*** 404 if not found.
** @PUT@ for update an existing @Resource@ (partial updates allowed to avoid @PATCH@ method). For @Collections@, bulk update.
** @PATCH@ should be allowed for UPSERT additions (creating a new @Resource@/updating an existing one by specifying the key/ID).
** @DELETE@ for deleting a @Resource@ or all @Collection@ @Resources@.
*** 202 - Accepted but not immediately deleted (@Location: <URI of asynchonous task@).
*** 204 - No content if deleted.
** @OPTIONS@ should return the valid HTTP verbs for that endpoint.
* Only @POST@ and @PATCH@ are not idempotent.
* Asynchronous operations on Resources must return 202 and @Location: @ to the URI where the eventual status of the operation can be retrieved from.
** Asynchronous ops and associated Resources should support tombstones (the async op metadata remains queryable after the async op finished, according to a retention policy).
* Resources that can be moved/renamed must (additionally) have a canonical/stable name (unique and unchanging).
* Resources should provide a header @Link: <{help}>; rel="help"@ pointing to documentation.
* Default @charset@ is @UTF-8@
* Handle "@Prefer@":https://tools.ietf.org/html/rfc7240 Headers:
** @Prefer: respond-async, wait=10@: to specify that response should be asynchronously processed
** @Prefer: return=representation@ or @return=minimal@, to include representation or empty body on Resource creation.
** @Prefer: handling=strict@ and @handling=lenient@ to indicate the server to work on best-effort (some errors might be allowed) or strict way.
* @Collections@ are JSON arrays. The field used for the canonical/durable identified should be labeled as @id@.
Adhering to an standard/specification (some of them can be used together):
* "JSON:API 1.0":https://jsonapi.org/format/
* "OpenAPI 3.0":https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md
*
| Resource | POST | GET | PUT | DELETE |
| @/resource@ | ✔ | ✔ | ✔ | ✔ |