search

medizininformatik-initiative / feasibility-backend

Backend of the feasibility-gui.
Apache License 2.0
2 stars 5 forks source link

Rename Terminology Endpoints #190

Closed michael-82 closed 11 months ago

michael-82 commented 12 months ago

The terminology endpoints are named slightly confusing (imho).

Thus I suggest changing

/api/v2/terminology/selectable-entries -> /api/v2/terminology/search /api/v2/terminology/root-entries -> /api/v2/terminology/entries/categories

I would also remove the /api/v1/... equivalents completely. @thkoehler11 @Shayan1375 - this would obviously affect the GUI - please let me know if this causes any issues

alexanderkiel commented 12 months ago

In /api/v2/terminology/search search is a verb. However REST URL's should designate resources. Often it's better to use noun's for resource names.

After looking in the code, I would suggest:

/api/v2/terminology/selectable-entries -> /api/v3/terminology/entries
/api/v2/terminology/root-entries -> /api/v3/terminology/categories

because the first resource is the resource of all entries that can be constraint by a query and the second is the resource of all categories. If I understand it correctly, categories are different from entries. We also have /api/v2/terminology/entries/{id} which would nicely work together with /api/v3/terminology/entries.

Please also note that the old API should be still available in order to allow an update of the backend without an update of the UI.

michael-82 commented 12 months ago

Changing the wording is no problem. Concerning the versioning, I have 2 questions:

  1. One of the terminology endpoints will not be working any more due to the ontology changes (requesting ui profile without context) - how should this be handled then?
  2. There are no changes in the query api. Currently, both are under /api/v2/... . If we change terminology, the query api should be duplicated to v3 as well, correct? Would it be better to change the whole paths to /api/query/v2 and /api/terminology/v3 so we can individually change versions? (Of course we can do this as it is now as well, but it feels a bit off imo)
alexanderkiel commented 12 months ago
  1. The old endpoint must not change at all including the payload and query params. The question would be whether we can provide the old API on top of the new ontology.
  2. As the client has to be updated anyway for v3, I would be ok if the client has to use v3 URL's for the terminology part and v2 URL for the query part. Also it's not really important at which position the version number appears inside the URL. For the client it could be simpler to have one URL prefix for the whole API version, but using two different prefixes for the different parts of the API should not be a big burden for the client.