search

HumanCellAtlas / data-store

Design specs and prototypes for the HCA Data Storage System (DSS, "blue box")
https://dss.staging.data.humancellatlas.org/
Other
40 stars 6 forks source link

Add operationId for all HCA DSS endpoints #2720

Open dvantwisk opened 4 years ago

dvantwisk commented 4 years ago

Hello,

I am using the swagger-generator api generator to access the HCA DCP DSS API. This creates a series of functions that can be easily generated in R and the list of functions looks as follows:

hca$Create_a_bundle
hca$Create_a_collection.
hca$Create_a_new_version_of_a_file
hca$Create_an_event_subscription.
hca$Delete_a_bundle_or_a_specific_bundle_version
hca$Delete_a_collection.
hca$Delete_an_event_subscription.
hca$dss.api.bundles.checkout.get
hca$dss.api.bundles.checkout.post
hca$dss.api.bundles.enumerate
hca$dss.api.collections.list_collections
hca$dss.api.events.list_events
hca$dss.api.subscriptions.find
hca$Find_bundles_by_searching_their_metadata_with_an_Elasticsearch_query
hca$Retrieve_a_bundle_given_a_UUID_and_optionally_a_version.
hca$Retrieve_a_bundle_metadata_document_given_a_UUID_and_version.
hca$Retrieve_a_collection_given_a_UUID.
hca$Retrieve_a_file's_metadata_given_an_UUID_and_optionally_a_version.
hca$Retrieve_a_file_given_a_UUID_and_optionally_a_version.
hca$Retrieve_an_event_subscription_given_a_UUID.
hca$Update_a_bundle.
hca$Update_a_collection.

Here the hca object has these functions created by the api generator available. It can be seen that some names are long and unwieldy like Find_bundles_by_searching_their_metadata_with_an_Elasticsearch_query. Others make a lot more sense such as dss.api.bundles.checkout.get. This is because the api generator names for functions first after the operationId tag in the https://dss.data.humancellatlas.org/v1/swagger.json document. If the tag is not present for an endpoint, the name defaults to the summary tag. Some endpoints in the swagger.json document have these operationId tags while others do not, thus causing this issue.

I ask that appropriately named operationId tags be added to all endpoints in the document.

amarjandu commented 4 years ago

@dvantwisk this repository has been in a maintenance only mode for a couple of months (Nov 2019), it appears that the current DSS is getting depreciated, and replaced with something else. I'm not sure how long that processing is going to take, but if possible I'll make the changes to the swagger.json

amarjandu commented 4 years ago

@dvantwisk the changes have to propagate their way up.... see #2724; ill let you know when it lands to the production env: https://dss.data.humancellatlas.org/v1/swagger.json