From 825cb6348a8d3790ee1e25b34f5290f906030783 Mon Sep 17 00:00:00 2001 From: yuanzhou Date: Mon, 10 Mar 2025 21:41:50 -0400 Subject: [PATCH 1/6] Remove unused /entities/new/{entity_type} endpoint --- entity-api-spec.yaml | 40 ---------------------------------------- 1 file changed, 40 deletions(-) diff --git a/entity-api-spec.yaml b/entity-api-spec.yaml index 7a303fd3..26825267 100644 --- a/entity-api-spec.yaml +++ b/entity-api-spec.yaml @@ -1758,46 +1758,6 @@ paths: description: The target entity could not be found '500': description: Internal error - '/entities/new/{entity_type}': - post: - summary: Create a new entity of the target type - parameters: - - name: entity_type - in: path - description: 'One of the target entity types (case-insensitive since will be normalized): Donor, Sample, Dataset, Upload' - required: true - schema: - type: string - requestBody: - content: - application/json: - schema: - oneOf: - - $ref: '#/components/schemas/Donor' - - $ref: '#/components/schemas/Sample' - - $ref: '#/components/schemas/Dataset' - - $ref: '#/components/schemas/Upload' - responses: - '200': - description: The entity was successfully created and is returned - content: - application/json: - schema: - type: array - items: - anyOf: - - $ref: '#/components/schemas/Donor' - - $ref: '#/components/schemas/Sample' - - $ref: '#/components/schemas/Dataset' - - $ref: '#/components/schemas/Upload' - '400': - description: Invalid entity type provided - '401': - description: The user's token has expired or the user did not supply a valid token - '403': - description: The user is not authorized to create the entity - '500': - description: Internal error '/entities/multiple-samples/{count}': post: summary: "Create multiple samples from the same source entity. 'count' samples will be generated each with individual uuids, hubmap_ids and submission_ids." From b521f698528e648e5a195da343bafa36d0299358 Mon Sep 17 00:00:00 2001 From: yuanzhou Date: Mon, 10 Mar 2025 21:42:39 -0400 Subject: [PATCH 2/6] Upgrade to OpenAPI 3.0.3 --- entity-api-spec.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/entity-api-spec.yaml b/entity-api-spec.yaml index 26825267..d27eeaae 100644 --- a/entity-api-spec.yaml +++ b/entity-api-spec.yaml @@ -1,4 +1,4 @@ -openapi: 3.0.0 +openapi: 3.0.3 info: description: 'The HuBMAP Entity API is a standard RESTful web service with create, update and read operations for the standard HuBMAP provenance graph entities.' version: 2.4.3 From 557b8161cefd7afdf74b658dcb344a6415b5538b Mon Sep 17 00:00:00 2001 From: yuanzhou Date: Tue, 11 Mar 2025 00:51:20 -0400 Subject: [PATCH 3/6] Fix Upload field with single ref not array --- entity-api-spec.yaml | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/entity-api-spec.yaml b/entity-api-spec.yaml index d27eeaae..5aa9ccac 100644 --- a/entity-api-spec.yaml +++ b/entity-api-spec.yaml @@ -701,9 +701,7 @@ components: description: "A list of collections that this dataset belongs to." upload: readOnly: true - type: array - items: - $ref: '#/components/schemas/Upload' + $ref: '#/components/schemas/Upload' description: "The Data Upload that this dataset is associated with." contributors: readOnly: true @@ -1126,9 +1124,7 @@ components: description: "A list of collections that this dataset belongs to." upload: readOnly: true - type: array - items: - $ref: '#/components/schemas/Upload' + $ref: '#/components/schemas/Upload' description: "The Data Upload that this dataset is associated with." contributors: readOnly: true From 0653b91c01b71ba49c5016d116c192d89707adc5 Mon Sep 17 00:00:00 2001 From: yuanzhou Date: Tue, 11 Mar 2025 00:56:59 -0400 Subject: [PATCH 4/6] Use allOf for Upload single ref --- entity-api-spec.yaml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/entity-api-spec.yaml b/entity-api-spec.yaml index 5aa9ccac..a99339c4 100644 --- a/entity-api-spec.yaml +++ b/entity-api-spec.yaml @@ -701,7 +701,8 @@ components: description: "A list of collections that this dataset belongs to." upload: readOnly: true - $ref: '#/components/schemas/Upload' + allOf: + - $ref: '#/components/schemas/Upload' description: "The Data Upload that this dataset is associated with." contributors: readOnly: true @@ -1124,7 +1125,8 @@ components: description: "A list of collections that this dataset belongs to." upload: readOnly: true - $ref: '#/components/schemas/Upload' + allOf: + - $ref: '#/components/schemas/Upload' description: "The Data Upload that this dataset is associated with." contributors: readOnly: true From 27b888dec79fcc28c78b2b774ff513cd6946331c Mon Sep 17 00:00:00 2001 From: yuanzhou Date: Tue, 11 Mar 2025 01:01:54 -0400 Subject: [PATCH 5/6] Remove requestBody ref for `PUT /entities/{id}` --- entity-api-spec.yaml | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/entity-api-spec.yaml b/entity-api-spec.yaml index a99339c4..62e6dc40 100644 --- a/entity-api-spec.yaml +++ b/entity-api-spec.yaml @@ -1298,10 +1298,7 @@ paths: content: application/json: schema: - oneOf: - - $ref: '#/components/schemas/Donor' - - $ref: '#/components/schemas/Sample' - - $ref: '#/components/schemas/Dataset' + type: object responses: '200': description: The entity was successfully updated and is returned From a2a1a1e92109f23b57d4ebee65ab290e099e154e Mon Sep 17 00:00:00 2001 From: yuanzhou Date: Tue, 11 Mar 2025 01:20:01 -0400 Subject: [PATCH 6/6] Update entity-api-spec.yaml --- entity-api-spec.yaml | 245 ++++++++++++++++++++++++++++++------------- 1 file changed, 172 insertions(+), 73 deletions(-) diff --git a/entity-api-spec.yaml b/entity-api-spec.yaml index 62e6dc40..2026f363 100644 --- a/entity-api-spec.yaml +++ b/entity-api-spec.yaml @@ -1,7 +1,7 @@ openapi: 3.0.3 info: description: 'The HuBMAP Entity API is a standard RESTful web service with create, update and read operations for the standard HuBMAP provenance graph entities.' - version: 2.4.3 + version: 2.4.6 title: HuBMAP Entity API contact: name: HuBMAP Help Desk @@ -13,6 +13,7 @@ servers: - url: 'https://entity.api.hubmapconsortium.org' security: - bearerAuth: [] + - {} components: securitySchemes: @@ -226,6 +227,8 @@ components: description: "The HuBMAP unique identifier for the file." Donor: type: object + required: + - protocol_url properties: created_timestamp: type: integer @@ -268,9 +271,10 @@ components: readOnly: true description: "The name of the person or process which authenticated when the object was last modified." entity_type: + enum: ["Donor"] type: string readOnly: true - description: "One of the normalized entity types: Dataset, Collection, Sample, Donor, Upload" + description: "Entity type constant" registered_doi: type: string description: "The doi of a the registered entity. e.g. 10.35079/hbm289.pcbm.487. This is set during the publication process and currently available for certain Collections and Datasets." @@ -309,14 +313,13 @@ components: type: array items: type: string - format: temp_file_id description: 'List of temporary file ids with an optional description. Provide as a json array with an temp_file_id and description attribute for each element like {"files": [{"temp_file_id":"dzevgd6xjs4d5grmcp4n","description":"This is image file one"},{"temp_file_id":"yrahjadfhadf","description":"This is image file two"}]}' image_files_to_remove: writeOnly: true type: array items: type: string - format: file_uuid + format: uuid description: 'List of image files previously uploaded to delete. Provide as a json array of the file_uuids of the file like: ["232934234234234234234270c0ea6c51d604a850558ef2247d0b4", "230948203482234234234a57bfe9c056d08a0f8e6cd612baa3bfa"]' metadata: type: object @@ -354,6 +357,9 @@ components: description: "Lab provided, de-identified name for the donor" Sample: type: object + required: + - sample_category + - protocol_url properties: created_timestamp: type: integer @@ -396,9 +402,10 @@ components: readOnly: true description: "The name of the person or process which authenticated when the object was last modified." entity_type: + enum: ["Sample"] type: string readOnly: true - description: "One of the normalized entity types: Dataset, Collection, Sample, Donor" + description: "Entity type constant" registered_doi: type: string description: "The doi of a the registered entity. e.g. 10.35079/hbm289.pcbm.487. This is set during the publication process and currently available for certain Collections and Datasets." @@ -489,9 +496,7 @@ components: writeOnly: true description: "The uuid of source entity from which this new entity is derived from. Used on creation or edit to create an action and relationship to the ancestor. The direct ancestor must be a Donor or Sample. If the direct ancestor is a Donor, the sample must be of type organ." direct_ancestor: - readOnly: true - type: object - description: "The entitiy directly above this sample in the provenance graph (direct parent)." + $ref: '#/components/schemas/Donor' submission_id: type: string description: "The hubmap internal id with embedded semantic information e.g.: VAN0003-LK-1-10. This id is generated at creation time which tracks the lab, donor, organ and sample hierarchy per the following: https://docs.google.com/document/d/1DjHgmqWF1VA5-3mfzLFNfabbzmc8KLSG9xWx1DDLlzo/edit?usp=sharing" @@ -517,14 +522,13 @@ components: type: array items: type: string - format: temp_file_id description: 'List of temporary file ids with an optional description. Provide as a json array with an temp_file_id and description attribute for each element like {"files": [{"temp_file_id":"dzevgd6xjs4d5grmcp4n","description":"This is image file one"},{"temp_file_id":"yrahjadfhadf","description":"This is image file two"}]}' image_files_to_remove: writeOnly: true type: array items: type: string - format: file_uuid + format: uuid description: 'List of image files previously uploaded to delete. Provide as a json array of the file_uuids of the file like: ["232934234234234234234270c0ea6c51d604a850558ef2247d0b4", "230948203482234234234a57bfe9c056d08a0f8e6cd612baa3bfa"]' metadata_files: readOnly: true @@ -536,16 +540,18 @@ components: type: array items: type: string - format: temp_file_id description: 'List of temporary file ids with an optional description. Provide as a json array with an temp_file_id and description attribute for each element like {"files": [{"temp_file_id":"dzevgd6xjs4d5grmcp4n","description":"This is image file one"},{"temp_file_id":"yrahjadfhadf","description":"This is image file two"}]}' metadata_files_to_remove: type: array items: type: string - format: file_uuid + format: uuid description: 'List of image files previously uploaded to delete. Provide as a json array of the file_uuids of the file like: ["232934234234234234234270c0ea6c51d604a850558ef2247d0b4", "230948203482234234234a57bfe9c056d08a0f8e6cd612baa3bfa"]' Dataset: type: object + required: + - contains_human_genetic_sequences + - dataset_type properties: created_timestamp: type: integer @@ -592,9 +598,10 @@ components: readOnly: true description: "The name of the person or process which authenticated when the object was last modified." entity_type: + enum: ["Dataset"] type: string readOnly: true - description: "One of the normalized entity types: Dataset, Collection, Sample, Donor" + description: "Entity type constant" registered_doi: type: string description: "The doi of a the registered entity. e.g. 10.35079/hbm289.pcbm.487. This is set during the publication process and currently available for certain Collections and Datasets." @@ -779,16 +786,16 @@ components: description: "The uuids of next revision dataset" thumbnail_file: readOnly: true + type: object description: 'The dataset thumbnail file detail. Stored in db as a stringfied json, e.g., {"filename": "thumbnail.jpg", "file_uuid": "c35002f9c3d49f8b77e1e2cd4a01803d"}' thumbnail_file_to_add: writeOnly: true type: string - format: temp_file_id description: 'Just a temporary file id. Provide as a json object with an temp_file_id like {"temp_file_id":"dzevgd6xjs4d5grmcp4n"}' thumbnail_file_to_remove: writeOnly: true type: string - format: file_uuid + format: uuid description: 'The thumbnail image file previously uploaded to delete. Provide as a string of the file_uuid like: "c35002f9c3d49f8b77e1e2cd4a01803d"' sub_status: type: string @@ -813,6 +820,10 @@ components: description: 'The organ code representing the organ type that the data contained in the upload will be registered/associated with.' Upload: type: object + required: + - title + - intended_dataset_type + - intended_organ properties: created_timestamp: type: integer @@ -855,9 +866,10 @@ components: readOnly: true description: "The name of the person or process which authenticated when the object was last modified." entity_type: + enum: ["Upload"] type: string readOnly: true - description: "One of the normalized entity types: Dataset, Collection, Sample, Donor, Upload" + description: "Entity type constant" description: type: string description: "Free text description of the data being submitted." @@ -897,6 +909,9 @@ components: description: "The datasets that are contained in this Upload." Collection: type: object + required: + - title + - description properties: created_timestamp: type: integer @@ -939,9 +954,10 @@ components: readOnly: true description: "The name of the person or process which authenticated when the object was last modified." entity_type: + enum: ["Collection"] type: string readOnly: true - description: "One of the normalized entity types: Dataset, Collection, Sample, Donor" + description: "Entity type constant" registered_doi: type: string description: "The doi of a the registered entity. e.g. 10.35079/hbm289.pcbm.487. This is set during the publication process and currently available for certain Collections and Datasets." @@ -970,6 +986,12 @@ components: description: "The datasets that are contained in the Collection." Publication: type: object + required: + - title + - publication_date + - publication_url + - publication_venue + - publication_status properties: created_timestamp: type: integer @@ -1016,9 +1038,10 @@ components: readOnly: true description: "The name of the person or process which authenticated when the object was last modified." entity_type: + enum: ["Publication"] type: string readOnly: true - description: "One of the normalized entity types: Dataset, Collection, Sample, Donor" + description: "Entity type constant" registered_doi: type: string description: "The doi of a the registered entity. e.g. 10.35079/hbm289.pcbm.487. This is set during the publication process and currently available for certain Collections and Datasets." @@ -1124,7 +1147,6 @@ components: $ref: '#/components/schemas/Collection' description: "A list of collections that this dataset belongs to." upload: - readOnly: true allOf: - $ref: '#/components/schemas/Upload' description: "The Data Upload that this dataset is associated with." @@ -1192,16 +1214,16 @@ components: description: "The uuid of next revision dataset" thumbnail_file: readOnly: true + type: object description: 'The dataset thumbnail file detail. Stored in db as a stringfied json, e.g., {"filename": "thumbnail.jpg", "file_uuid": "c35002f9c3d49f8b77e1e2cd4a01803d"}' thumbnail_file_to_add: writeOnly: true type: string - format: temp_file_id description: 'Just a temporary file id. Provide as a json object with an temp_file_id like {"temp_file_id":"dzevgd6xjs4d5grmcp4n"}' thumbnail_file_to_remove: writeOnly: true type: string - format: file_uuid + format: uuid description: 'The thumbnail image file previously uploaded to delete. Provide as a string of the file_uuid like: "c35002f9c3d49f8b77e1e2cd4a01803d"' sub_status: type: string @@ -1246,13 +1268,83 @@ components: associated_collection: type: object description: 'The associated collection for a given publication' - Instanceof: + Epicollection: type: object - description: "Returned by entities/<id>/instanceof/<type>" + required: + - title + - description properties: - instanceof: - type: boolean - description: "True of False depending on whether the Entity id is an instance of the type" + created_timestamp: + type: integer + readOnly: true + description: "The timestamp of when the node was created. The format is an integer representing milliseconds since midnight Jan 1, 1970" + created_by_user_displayname: + type: string + readOnly: true + description: "The name of the person or process authenticated when creating the object" + created_by_user_email: + type: string + readOnly: true + description: "The email address of the person or process authenticated when creating the object." + created_by_user_sub: + type: string + readOnly: true + description: "The subject id as provided by the authorization mechanism for the person or process authenticated when creating the object." + uuid: + type: string + readOnly: true + description: "The HuBMAP unique identifier, intended for internal software use only. This is a 32 digit hexadecimal uuid e.g. 461bbfdc353a2673e381f632510b0f17" + hubmap_id: + type: string + readOnly: true + description: "A HuBMAP Consortium wide unique identifier randomly generated in the format HBM###.ABCD.### for every entity." + last_modified_timestamp: + type: integer + readOnly: true + description: "The timestamp of when the object was last modified. The format is an integer representing milliseconds since midnight, Jan 1, 1970" + last_modified_user_sub: + type: string + readOnly: true + description: "The subject id of the user who last modified the entity as provided by the authorization mechanism for the person or process authenticated when the object was modified." + last_modified_user_email: + type: string + readOnly: true + description: "The email address of the person or process which authenticated when the object was last modified." + last_modified_user_displayname: + type: string + readOnly: true + description: "The name of the person or process which authenticated when the object was last modified." + entity_type: + enum: ["Epicollection"] + type: string + readOnly: true + description: "Entity type constant" + registered_doi: + type: string + description: "The doi of a the registered entity. e.g. 10.35079/hbm289.pcbm.487. This is set during the publication process and currently available for certain Collections and Datasets." + doi_url: + type: string + readOnly: true + description: "The url from the doi registry for this entity. e.g. https://doi.org/10.35079/hbm289.pcbm.487" + contributors: + type: array + items: + $ref: '#/components/schemas/Person' + description: "A list of the people who created the entity with full name, email, ORCID iD, institution, etc.. This is analogus to the author list on a publication." + contacts: + type: array + items: + $ref: '#/components/schemas/Person' + description: "A list of the people who are the main contacts to get information about the entity." + title: + type: string + description: "The title of the Collection" + datasets: + type: array + readOnly: true + items: + $ref: '#/components/schemas/Dataset' + description: "The datasets that are contained in the Collection." paths: '/entities/{id}': @@ -1267,14 +1359,18 @@ paths: type: string responses: '200': - description: The json of the **[Donor](http://somewhere.org)**, **[Sample](http://somewhere.org)** or **[Dataset](http://somewhere.org)** + description: The entity details content: application/json: - schema: + schema: oneOf: - $ref: '#/components/schemas/Donor' - $ref: '#/components/schemas/Sample' - $ref: '#/components/schemas/Dataset' + - $ref: '#/components/schemas/Upload' + - $ref: '#/components/schemas/Collection' + - $ref: '#/components/schemas/Publication' + - $ref: '#/components/schemas/Epicollection' '400': description: Invalid or misformatted entity identifier was provided. '401': @@ -1297,18 +1393,11 @@ paths: requestBody: content: application/json: - schema: + schema: type: object responses: '200': - description: The entity was successfully updated and is returned - content: - application/json: - schema: - oneOf: - - $ref: '#/components/schemas/Donor' - - $ref: '#/components/schemas/Sample' - - $ref: '#/components/schemas/Dataset' + description: Message of the entity was successfully updated '400': description: Invalid or misformatted entity identifier '401': @@ -1350,13 +1439,15 @@ paths: description: An array of ancestors is returned content: application/json: - schema: - type: array - items: - anyOf: - - $ref: '#/components/schemas/Donor' - - $ref: '#/components/schemas/Sample' - - $ref: '#/components/schemas/Dataset' + schema: + oneOf: + - $ref: '#/components/schemas/Donor' + - $ref: '#/components/schemas/Sample' + - $ref: '#/components/schemas/Dataset' + - $ref: '#/components/schemas/Upload' + - $ref: '#/components/schemas/Collection' + - $ref: '#/components/schemas/Publication' + - $ref: '#/components/schemas/Epicollection' '400': description: Invalid or misformatted entity identifier @@ -1383,12 +1474,15 @@ paths: description: An array of descendants is returned content: application/json: - schema: - type: array - items: - anyOf: - - $ref: '#/components/schemas/Sample' - - $ref: '#/components/schemas/Dataset' + schema: + oneOf: + - $ref: '#/components/schemas/Donor' + - $ref: '#/components/schemas/Sample' + - $ref: '#/components/schemas/Dataset' + - $ref: '#/components/schemas/Upload' + - $ref: '#/components/schemas/Collection' + - $ref: '#/components/schemas/Publication' + - $ref: '#/components/schemas/Epicollection' '400': description: Invalid or misformatted entity identifier '401': @@ -1414,13 +1508,15 @@ paths: description: An array of parent entities is returned content: application/json: - schema: - type: array - items: - anyOf: - - $ref: '#/components/schemas/Donor' - - $ref: '#/components/schemas/Sample' - - $ref: '#/components/schemas/Dataset' + schema: + oneOf: + - $ref: '#/components/schemas/Donor' + - $ref: '#/components/schemas/Sample' + - $ref: '#/components/schemas/Dataset' + - $ref: '#/components/schemas/Upload' + - $ref: '#/components/schemas/Collection' + - $ref: '#/components/schemas/Publication' + - $ref: '#/components/schemas/Epicollection' '400': description: Invalid or misformatted entity identifier '401': @@ -1450,8 +1546,13 @@ paths: type: array items: anyOf: + - $ref: '#/components/schemas/Donor' - $ref: '#/components/schemas/Sample' - $ref: '#/components/schemas/Dataset' + - $ref: '#/components/schemas/Upload' + - $ref: '#/components/schemas/Collection' + - $ref: '#/components/schemas/Publication' + - $ref: '#/components/schemas/Epicollection' '400': description: Invalid or misformatted entity identifier '401': @@ -1502,8 +1603,13 @@ paths: type: array items: anyOf: + - $ref: '#/components/schemas/Donor' - $ref: '#/components/schemas/Sample' - $ref: '#/components/schemas/Dataset' + - $ref: '#/components/schemas/Upload' + - $ref: '#/components/schemas/Collection' + - $ref: '#/components/schemas/Publication' + - $ref: '#/components/schemas/Epicollection' '400': description: Invalid or misformatted entity identifier '401': @@ -1547,8 +1653,13 @@ paths: type: array items: anyOf: + - $ref: '#/components/schemas/Donor' - $ref: '#/components/schemas/Sample' - $ref: '#/components/schemas/Dataset' + - $ref: '#/components/schemas/Upload' + - $ref: '#/components/schemas/Collection' + - $ref: '#/components/schemas/Publication' + - $ref: '#/components/schemas/Epicollection' '400': description: Invalid or misformatted entity identifier '401': @@ -1584,8 +1695,7 @@ paths: schema: type: array items: - anyOf: - - $ref: '#/components/schemas/Collection' + $ref: '#/components/schemas/Collection' '400': description: Invalid or misformatted entity identifier '401': @@ -1621,8 +1731,7 @@ paths: schema: type: array items: - anyOf: - - $ref: '#/components/schemas/Upload' + $ref: '#/components/schemas/Upload' '400': description: Invalid or misformatted entity identifier '401': @@ -1677,10 +1786,6 @@ paths: responses: '200': description: An object with the attribute 'instanceof' that has a value of either 'true' of 'false' - content: - application/json: - schema: - $ref: '#/components/schemas/Instanceof' '400': description: Invalid or misformatted entity identifier '401': @@ -1710,10 +1815,6 @@ paths: responses: '200': description: An object with the attribute 'instanceof' that has a value of either 'true' of 'false' - content: - application/json: - schema: - $ref: '#/components/schemas/Instanceof' '400': description: Invalid or misformatted entity identifier '401': @@ -1819,7 +1920,6 @@ paths: text/plain: schema: type: string - format: url '400': description: Invalid or misformatted entity identifier '401': @@ -2244,7 +2344,7 @@ paths: items: type: string description: The HuBMAP ID of the donor associated to this dataset in the provenance chain - donor:submission_id: + donor_submission_id: type: array items: type: string @@ -2409,7 +2509,7 @@ paths: items: type: string description: The HuBMAP ID of the donor associated to this dataset in the provenance chain - donor:submission_id: + donor_submission_id: type: array items: type: string @@ -2739,4 +2839,3 @@ paths: description: The given dataset is unpublished and the user does not have the authorization to view it. '500': description: Internal error -