Bug #44013
Feature #40907: mgr/dashboard: REST API improvements
mgr/dashboard: current REST API flaws
Status:
New
Priority:
Low
Assignee:
-
Category:
General - 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.
- Verbs in endpoints:
GET /cephfs/{fs_id}/get_quotas
vs. the existingGET /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).
- We currently expose 191 different endpoints (only the
- 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 followingPOST /cephfs/{fs_id}/dira/dirb, body: {name: 'dirC', type: 'dir'}
- for making a new dir it requires
- HTTP Verbs are wrongly used (POST is used for everything):
POST /cephfs/{fs_id}/rm_dir
vsDELETE /cephfs/{fs_id}/dirA/dirB/dir_to_delete
.
/cluster_conf
/host
/iscsi
/nfs-ganesha
/pool
/rgw
/cephfs
/osd/{id}/mark_{in,down,..}
, uses POST and separate endpoints for setting individual flags, when that should be a single endpoint driven by aPUT /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 bePUT /mgr/module/{name}, {enable: true|false}
/prometheus/silence
vs./prometheus/silences
/block/mirroring/pool/...
using POST instead of PUT.
Subtasks
History
#1 Updated by Ernesto Puerta about 4 years ago
- Description updated (diff)
#2 Updated by Ernesto Puerta almost 4 years ago
- Parent task set to #40907
#3 Updated by Ernesto Puerta almost 4 years ago
- Description updated (diff)
#4 Updated by Ernesto Puerta almost 4 years ago
- Description updated (diff)
#5 Updated by Ernesto Puerta almost 4 years ago
- Description updated (diff)
#6 Updated by Alfonso MartÃnez almost 4 years 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 almost 3 years ago
- Project changed from mgr to Dashboard
- Category changed from 146 to General - Back-end