search

usnistgov / WIPP-backend

Web Image Processing Pipeline (WIPP) - backend
Other
5 stars 10 forks source link

Consistent naming conventions for plural collection objects #176

Open ktaletsk opened 2 years ago

ktaletsk commented 2 years ago

Description Currently, naming conventions endpoints and JSON keys for different collection types are slightly inconsistent when it comes to plural of the collection object (images, csvs, datas). To demonstrate the issue, take a look at the table below:

Collection type API endpoint Collection element endpoint JSON key containing elements of collection
Image Collections /api/imagesCollections /api/imagesCollections/{imagesCollectionId}/images _embedded -> images
CSV Collections /api/csvCollections /api/csvCollections/{csvCollectionId}/csv _embedded -> csvs
Generic Data Collections /api/genericDatas /api/genericDatas/{genericDataId}/genericFile _embedded -> genericFiles

So, you can see that the same word images is used in both the endpoint and JSON key in this case, but different words (csv and csvs, genericFile and genericFiles) are used in other cases.

Proposal Use the plural form for objects; use the same form in all places in the API. The following naming scheme would be more consistent: Collection type API endpoint Collection element endpoint JSON key containing elements of collection
Image Collections /api/imagesCollections /api/imagesCollections/{imagesCollectionId}/images _embedded -> images
CSV Collections /api/csvCollections /api/csvCollections/{csvCollectionId}/csvs _embedded -> csvs
Generic Data Collections /api/genericDataCollections /api/genericDatas/{genericDataId}/genericFiles _embedded -> genericFiles
MyleneSimon commented 2 years ago

That's a good point, it seems that it happening for the most recent additions to the API, I will fix the endpoints. Did you notice any other places besides CSVs and GenericData? GenericData could probably use another name as well...

ktaletsk commented 2 years ago

I'll probably look through the most of the API endpoints in the near future as I'm working on the Python client for the API (here: https://github.com/PolusAI/data-tools/pull/1). I will report any findings of the inconsistent names in this thread

mohamedOuladi commented 2 years ago

That's a good point, it seems that it happening for the most recent additions to the API, I will fix the endpoints. Did you notice any other places besides CSVs and GenericData? GenericData could probably use another name as well...

In this case, I should rename GenericData in my PR #184. Should we go for GenericDataCollection?

MyleneSimon commented 2 years ago

I am good with GenericDataCollection, this is how it is displayed in the UI for now so it would keep it consistent (and avoid dealing with singular/plural for the word data). If you are updating your PR could you check that all Swagger annotations are properly added/updated? (see #177, you also need to merge #178 in your branch). Thanks!

MyleneSimon commented 2 years ago

If anyone has an idea for a better name though, now is a good time to voice it :)

MyleneSimon commented 2 years ago

I think at some point someone floated the idea of introducing the word raw instead of generic, I would not be opposed to RawDataCollection for example. Another option could be UnstructuredDataCollection.

pbajcsy commented 2 years ago

Following the comment about using plurals, the names should be XXXCollections. I would vote for RawDataCollections (GenericDataCollections would be fine too) since UnstructuredDataCollections is used by text mining researchers for unstructured text.

mohamedOuladi commented 2 years ago

I am good with GenericDataCollection, this is how it is displayed in the UI for now so it would keep it consistent (and avoid dealing with singular/plural for the word data). If you are updating your PR could you check that all Swagger annotations are properly added/updated? (see #177, you also need to merge #178 in your branch). Thanks!

@MyleneSimon Yeah I will make sure that Swagger annotations are updated.

mohamedOuladi commented 2 years ago

I think at some point someone floated the idea of introducing the word raw instead of generic, I would not be opposed to RawDataCollection for example. Another option could be UnstructuredDataCollection.

I think @NHotaling was the one who suggested RawDataCollection. So, I thought I should include him in the conversation.

I have already renamed GenericData to GenericDataCollection in the WIPP-frontend Labshare fork (see https://github.com/LabShare/WIPP-frontend/commit/94fa379fcb74486e3a881caa02667ec71ef43ce4). The reason why I opted for GenericDataCollection and not RawDataCollection was because of the addition of image conversion options that @MyleneSimon was working on. Having a conversion option raw might confuse the user, especially if the raw tags are created for image collections.