Bug #44013

Updated by Ernesto Puerta 11 months ago

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/@ @/api@
* However, a few are below @/apiapi/@, @/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.