Project

General

Profile

Feature #40911

Feature #40907: mgr/dashboard: REST API improvements

mgr/dashboard: REST API: review endpoints and semantics

Added by Ernesto Puerta about 3 years ago. Updated over 1 year ago.

Status:
New
Priority:
Normal
Assignee:
-
Category:
General - Back-end
Target version:
-
% Done:

0%

Source:
Tags:
Backport:
Reviewed:
Affected Versions:
Pull request ID:

Description

Ensure that existing endpoints comply with (reference):
  • 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] :
    • 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 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):
Resource POST GET PUT DELETE
/resource

History

#1 Updated by Ernesto Puerta about 3 years ago

  • Category set to 146

#2 Updated by Ernesto Puerta about 3 years ago

  • Description updated (diff)

#3 Updated by Ernesto Puerta over 1 year ago

  • Project changed from mgr to Dashboard
  • Category changed from 146 to General - Back-end

Also available in: Atom PDF