Project

General

Profile

Bug #44013

Feature #40907: mgr/dashboard: REST API improvements

mgr/dashboard: current REST API flaws

Added by Ernesto Puerta over 1 year ago. Updated 28 days ago.

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

78%

Source:
Community (dev)
Tags:
Backport:
Regression:
No
Severity:
3 - minor
Reviewed:
Affected Versions:
ceph-qa-suite:
Pull request ID:
Crash signature (v1):
Crash signature (v2):

Description

Regardless the discussion on whether dashboard API should adhere more or less tightly to RESTful guidelines, it should at least try to keep internal consistency:
  • Most API Endpoints lie beneath /api/
  • However, a few are below /apiapi/, like Pools, Cephfs, ErasureCode, etc.
Currently we have some components with a REST API that diverges from the existing practices and general guidelines:
  • Verbs in endpoints:
    • GET /cephfs/{fs_id}/get_quotas vs. the existing GET /rgw/user/{uid}/quota. Same for CephFS set_quota.
  • Excess of endpoints and operations. REST APIs aim at being clear and concise interfaces.
    • We currently expose 191 different endpoints (only the /osd resource has 17, and that doesn't include the new ones for creating/deleting OSDs). This could be improved by aggregating endpoints (e.g.: /osd/{id}, body: {down, out, up, in, lost..} instead of /osd/{id}/mark_down, /osd/{id}/mark_out, /osd/{id}/mark_up, /osd/{id}/mark_in, /osd/{id}/mark_lost,...
    • That will also result in less redundant code to maintain and fix.
    • We should also hide what we call UI endpoints (helper endpoints for the front-end).
  • Resources hidden in query params: REST APIs are great for exposing hierarchical resources, but Dashboard CephFS API has missed the chance to expose the CephFS filesystem hierarchy:
    • for making a new dir it requires POST /cephfs/{fs_id}/mk_dirs, body: {path: '/dira/dirb/...}, when it'd be preferred the following POST /cephfs/{fs_id}/dira/dirb, body: {name: 'dirC', type: 'dir'}
  • HTTP Verbs are wrongly used (POST is used for everything):
    • POST /cephfs/{fs_id}/rm_dir vs DELETE /cephfs/{fs_id}/dirA/dirB/dir_to_delete.
The resources that seem best aligned to REST guidelines:
  • /cluster_conf
  • /host
  • /iscsi
  • /nfs-ganesha
  • /pool
  • /rgw
The ones that should be improved:
  • /cephfs
  • /osd/{id}/mark_{in,down,..}, uses POST and separate endpoints for setting individual flags, when that should be a single endpoint driven by a PUT /osd/{id}, body: {out: true|false|undefined, down:...}.
  • Perf-counters (/perf_counter/{mgr,mon,osd,...}/{id}) should be moved under their corresponding resources (/{mgr,mon,osd...}/{id}/perf_counter
  • POST /mgr/module/{module_name}/{enable,disable} should be PUT /mgr/module/{name}, {enable: true|false}
  • /prometheus/silence vs. /prometheus/silences
  • /block/mirroring/pool/... using POST instead of PUT.

Subtasks

Subtask #45957: Fix broken UiApi documentation endpoints and add warningResolved

Subtask #46160: Address API inconsistencies in cephfs endpointResolved

Subtask #46181: Consolidate OSD mark endpointsResolved

Subtask #46236: Move performance counters to their corresponding resourcesNew

History

#1 Updated by Ernesto Puerta over 1 year ago

  • Description updated (diff)

#2 Updated by Ernesto Puerta about 1 year ago

  • Parent task set to #40907

#3 Updated by Ernesto Puerta about 1 year ago

  • Description updated (diff)

#4 Updated by Ernesto Puerta about 1 year ago

  • Description updated (diff)

#5 Updated by Ernesto Puerta about 1 year ago

  • Description updated (diff)

#6 Updated by Alfonso Martínez 11 months ago

Regarding /apiapi/ issue and after daily standup conversation,
there is agreement on the following:

1) Fix the issue: in the API documentation these endpoints should appear correctly.
2) Ensure that every /ui-api/ endpoint has its /api/ counterpart.
3) Add a clear warning/notification that /ui-api/ endpoints are not part of public API.
They exist for UI (Dashboard) only purposes. See:
https://github.com/ceph/ceph/blob/master/src/pybind/mgr/dashboard/HACKING.rst#how-to-create-a-dedicated-ui-endpoint-which-uses-the-public-api

After that we should discuss if there is a more consistent approach than having different base_url API endpoints.

#7 Updated by Ernesto Puerta 28 days ago

  • Project changed from mgr to Dashboard
  • Category changed from dashboard/backend to Back-end

Also available in: Atom PDF