diff --git a/src/pds_doi_service/api/swagger/swagger.yaml b/src/pds_doi_service/api/swagger/swagger.yaml index 4c55fb5a..647f478f 100644 --- a/src/pds_doi_service/api/swagger/swagger.yaml +++ b/src/pds_doi_service/api/swagger/swagger.yaml @@ -1,110 +1,102 @@ openapi: 3.0.0 + info: title: Planetary Data System DOI Service API description: PDS API for managing DOI registration with a DOI service provider (OSTI, DataCite, etc.). - version: "0.2" + version: '0.2' + +# Added by API Auto Mocking Plugin servers: -- url: http://localhost:8080/PDS_APIs/pds_doi_api/0.2 - description: Local host -- url: https://virtserver.swaggerhub.com/PDS_APIs/pds_doi_api/0.2 - description: SwaggerHub API Auto Mocking + - description: Local host + url : http://localhost:8080/PDS_APIs/pds_doi_api/0.2 + - description: SwaggerHub API Auto Mocking + url: https://virtserver.swaggerhub.com/PDS_APIs/pds_doi_api/0.2 + tags: -- name: dois - description: PDS DOI Core function restFull API + - name: dois + description: PDS DOI Core function restFull API + paths: /dois: get: tags: - - dois + - dois description: List the DOI requests within the transaction database operationId: get_dois parameters: - - name: doi - in: query - description: List of DOIs to fetch from transaction database. - required: false - style: form - explode: true - schema: - type: array - items: - type: string - example: 10.17189/21734 - - name: submitter - in: query - description: List of submitter email addresses to filter DOIs by. - required: false - style: form - explode: true - schema: - type: array - items: - type: string - example: my.email@node.gov - - name: node - in: query - description: List of PDS node names cited as contributor of the DOI to filter - by. Each identifier must be one of the valid PDS steward IDs, see https://pds.nasa.gov/datastandards/documents/dd/current/PDS4_PDS_DD_1D00.html#d5e72146 - required: false - style: form - explode: true - schema: - type: array - items: - type: string - example: eng - - name: status - in: query - description: List of DOI workflow status values to filter results by. Status - must be one of the following - "unknown", "draft", "review", or "findable". - required: false - style: form - explode: true - schema: - type: array - items: + - name: doi + in: query + description: 'List of DOIs to fetch from transaction database.' + required: false + schema: + type: array + items: + type: string + example: '10.17189/21734' + - name: submitter + in: query + description: 'List of submitter email addresses to filter DOIs by.' + required: false + schema: + type: array + items: + type: string + example: 'my.email@node.gov' + - name: node + in: query + description: >- + List of PDS node names cited as contributor of the DOI to filter by. + Each identifier must be one of the valid PDS steward IDs, see + https://pds.nasa.gov/datastandards/documents/dd/current/PDS4_PDS_DD_1D00.html#d5e72146 + required: false + schema: + type: array + items: + type: string + example: 'eng' + - name: status + in: query + description: >- + List of DOI workflow status values to filter results by. Status must + be one of the following - "unknown", "draft", "review", or "findable". + required: false + schema: + type: array + items: + type: string + example: 'review' + - name: ids + in: query + description: >- + List of PDS identifiers to filter DOIs by. Each identifier may contain one or more Unix-style wildcards (*) to pattern match against. + required: false + schema: + type: array + items: + type: string + examples: + pds4: + value: 'urn:nasa:pds:lab_shocked_feldspars::1.0' + pds3: + value: 'LRO-L-MRFLRO-2/3/5-BISTATIC-V3.0' + - name: start_date + in: query + description: >- + A start date to filter resulting DOI records by. Only records with an update time after this date will be returned. Value must be a valid isoformat string of the form \-\-\[T\:\:\.\] + required: false + schema: type: string - example: review - - name: ids - in: query - description: List of PDS identifiers to filter DOIs by. Each identifier may - contain one or more Unix-style wildcards (*) to pattern match against. - required: false - style: form - explode: true - schema: - type: array - items: + example: '2020-01-01T00:00:00.00' + - name: end_date + in: query + description: >- + An end date to filter resulting DOI records by. Only records with an update time prior to this date will be returned. Value must be a valid isoformat string of the form \-\-\[T\:\.\] + required: false + schema: type: string - examples: - pds4: - value: 'urn:nasa:pds:lab_shocked_feldspars::1.0' - pds3: - value: 'LRO-L-MRFLRO-2/3/5-BISTATIC-V3.0' - - name: start_date - in: query - description: A start date to filter resulting DOI records by. Only records - with an update time after this date will be returned. Value must be a - valid isoformat string of the form \-\-\[T\:\:\.\] - required: false - style: form - explode: true - schema: - type: string - example: 2020-01-01T00:00:00.00 - - name: end_date - in: query - description: An end date to filter resulting DOI records by. Only records - with an update time prior to this date will be returned. Value must be a - valid isoformat string of the form \-\-\[T\:\.\] - required: false - style: form - explode: true - schema: - type: string - example: 2020-12-31T23:59:00.00 + example: '2020-12-31T23:59:00.00' responses: - "200": + '200': description: Success content: application/json: @@ -112,361 +104,314 @@ paths: type: array items: $ref: '#/components/schemas/doi_summary' - x-content-type: application/json - "400": + '400': description: Invalid Argument - "500": + '500': description: Internal error - x-openapi-router-controller: pds_doi_service.api.controllers.dois_controller + post: tags: - - dois - description: Submit a DOI to reserve or update. The payload includes URLs - for one or more records to be submitted. Record URLs must resolve to PDS4 - label files (xml). + - dois + description: >- + Submit a DOI to reserve or update. The payload includes URLs for one or more + records to be submitted. Record URLs must resolve to PDS4 label files (xml). operationId: post_dois parameters: - - name: action - in: query - description: The submission action to perform. Must be one of "reserve", - "draft" or "update". "draft" is an alias for "update". - required: true - style: form - explode: true - schema: - type: string - example: reserve - - name: submitter - in: query - description: Email address of the submission requester. - required: true - style: form - explode: true - schema: - type: string - example: my.email@node.gov - - name: node - in: query - description: The PDS node name to cite as contributor of the DOI. Must be - one of the valid PDS steward IDs, see https://pds.nasa.gov/datastandards/documents/dd/current/PDS4_PDS_DD_1D00.html#d5e72146 - required: true - style: form - explode: true - schema: - type: string - example: eng - - name: url - in: query - description: URL to provide as the record to register a DOI for. URL must - start with either "http://" or "https://" and resolve to a valid PDS4 label - in XML format. This value is only utilized when request is set to "update". - required: false - style: form - explode: true - schema: - type: string - - name: force - in: query - description: If true, forces a reserve request to completion, ignoring any - warnings encountered. Has no effect for update requests. - required: false - style: form - explode: true - schema: - type: boolean - default: false + - name: action + in: query + description: The submission action to perform. Must be one of "reserve", + "draft" or "update". "draft" is an alias for "update". + required: true + schema: + type: string + example: 'reserve' + - name: submitter + in: query + description: 'Email address of the submission requester.' + required: true + schema: + type: string + example: 'my.email@node.gov' + - name: node + in: query + description: >- + The PDS node name to cite as contributor of the DOI. + Must be one of the valid PDS steward IDs, see + https://pds.nasa.gov/datastandards/documents/dd/current/PDS4_PDS_DD_1D00.html#d5e72146 + required: true + schema: + type: string + example: 'eng' + - name: url + in: query + description: >- + URL to provide as the record to register a DOI for. URL must start with either + "http://" or "https://" and resolve to a valid PDS4 label in XML format. This value is only utilized when request is set to "update". + required: false + schema: + type: string + - name: force + in: query + description: >- + If true, forces a reserve request to completion, ignoring any warnings encountered. Has no effect for update requests. + required: false + schema: + type: boolean + default: false requestBody: - description: Payload containing one or more labels in JSON or XML (PDS4) format. + description: >- + Payload containing one or more labels in JSON or XML (PDS4) format. Required for reserve requests, but optional for update. content: application/json: schema: $ref: '#/components/schemas/labels_payload' example: - labels: - - status: Reserved - title: Laboratory Shocked Feldspars Bundle - publication_date: 2020-03-11 - product_type_specific: PDS4 Collection - author_last_name: Johnson - author_first_name: J. R. - related_resource: urn:nasa:pds:lab_shocked_feldspars + labels: + - status: "Reserved" + title: "Laboratory Shocked Feldspars Bundle" + publication_date: "2020-03-11" + product_type_specific: "PDS4 Collection" + author_last_name: "Johnson" + author_first_name: "J. R." + related_resource: "urn:nasa:pds:lab_shocked_feldspars" application/xml: schema: type: string responses: - "200": + '200': description: Success content: application/json: schema: $ref: '#/components/schemas/doi_record' - example: - - creation_date: 2021-03-09T00:00:00Z - doi: 10.17189/29476 - identifier: urn:nasa:pds:lab_shocked_feldspars::1.0 - node: eng - record: | - - - - 29476 - Laboratory Shocked Feldspars Bundle - 10.17189/29476 - ... - PDS Operator - PDS - pds-operator@jpl.nasa.gov - 818.393.7165 - - - status: reserved - submitter: my.email@node.gov - "201": + example: + - creation_date: '2021-03-09T00:00:00Z' + doi: 10.17189/29476 + identifier: 'urn:nasa:pds:lab_shocked_feldspars::1.0' + node: eng + record: | + + + + 29476 + Laboratory Shocked Feldspars Bundle + 10.17189/29476 + ... + PDS Operator + PDS + pds-operator@jpl.nasa.gov + 818.393.7165 + + + status: reserved + submitter: my.email@node.gov + '201': description: Success - "400": + '400': description: Invalid Argument - "500": + '500': description: Internal error - x-openapi-router-controller: pds_doi_service.api.controllers.dois_controller + /doi: - description: >- - Endpoint for submitting or fetching a single DOI record. - This endpoint corresponds to the /dois/{lidvid} endpoint of v0.1 of the API. - However, since certain lidvids were observed to contain forward slashes ('/'), - this version now expects the lidvid (now called identifier) as part of the query. - get: - tags: - - dois - description: Get the status of a DOI from the transaction database. - operationId: get_doi_from_id - parameters: + parameters: - name: identifier in: query - description: The PDS identifier associated with the record to fetch. + description: 'The PDS identifier associated with the record to fetch.' required: true - style: form - explode: true schema: type: string example: 'urn:nasa:pds:lab_shocked_feldspars::1.0' + get: + tags: + - dois + description: 'Get the status of a DOI from the transaction database.' + operationId: get_doi_from_id responses: - "200": + '200': description: Success content: application/json: schema: $ref: '#/components/schemas/doi_record' - example: - - creation_date: 2021-03-09T00:00:00Z - doi: 10.17189/29476 - identifier: urn:nasa:pds:lab_shocked_feldspars::1.0 - node: eng - record: | - - - - 29476 - Laboratory Shocked Feldspars Bundle - 10.17189/29476 - ... - PDS Operator - PDS - pds-operator@jpl.nasa.gov - 818.393.7165 - - - status: reserved - submitter: my.email@node.gov - "404": + example: + - creation_date: '2021-03-09T00:00:00Z' + doi: 10.17189/29476 + identifier: 'urn:nasa:pds:lab_shocked_feldspars::1.0' + node: eng + record: | + + + + 29476 + Laboratory Shocked Feldspars Bundle + 10.17189/29476 + ... + PDS Operator + PDS + pds-operator@jpl.nasa.gov + 818.393.7165 + + + status: reserved + submitter: my.email@node.gov + '404': description: Not existing - "500": + '500': description: Internal error - x-openapi-router-controller: pds_doi_service.api.controllers.dois_controller put: tags: - - dois - description: Update the record associated with an existing DOI. + - dois + description: 'Update the record associated with an existing DOI.' operationId: put_doi_from_id parameters: + - name: submitter + in: query + description: 'Email address of the DOI update requester.' + required: false + schema: + type: string + example: 'my.email@node.gov' + - name: node + in: query + description: >- + The PDS node name to cite as contributor of the DOI. + Must be one of the valid PDS steward IDs, see + https://pds.nasa.gov/datastandards/documents/dd/current/PDS4_PDS_DD_1D00.html#d5e72146 + required: false + schema: + type: string + example: 'eng' + - name: url + in: query + description: >- + URL to provide as the record to update the DOI with. URL must start with either "http://" or "https://" and resolve to a valid PDS4 label in XML format. + required: false + schema: + type: string + responses: + '501': + description: Not implemented + + /doi/submit: + parameters: - name: identifier in: query - description: The PDS identifier associated with the record to update. + description: 'The PDS identifier associated with the record to submit for review.' required: true - style: form - explode: true schema: type: string example: 'urn:nasa:pds:lab_shocked_feldspars::1.0' - - name: submitter - in: query - description: Email address of the DOI update requester. - required: false - style: form - explode: true - schema: - type: string - example: my.email@node.gov - - name: node - in: query - description: The PDS node name to cite as contributor of the DOI. Must be - one of the valid PDS steward IDs, see https://pds.nasa.gov/datastandards/documents/dd/current/PDS4_PDS_DD_1D00.html#d5e72146 - required: false - style: form - explode: true - schema: - type: string - example: eng - - name: url - in: query - description: URL to provide as the record to update the DOI with. URL must - start with either "http://" or "https://" and resolve to a valid PDS4 label - in XML format. - required: false - style: form - explode: true - schema: - type: string - responses: - "501": - description: Not implemented - x-openapi-router-controller: pds_doi_service.api.controllers.dois_controller - /doi/submit: - description: >- - Endpoint for submitting a DOI record for review by the Engineering Node. - This endpoint corresponds to the /dois/{lidvid}/submit endpoint of v0.1 of the API. - However, since certain lidvids were observed to contain forward slashes ('/'), - this version now expects the lidvid (now called identifier) as part of the query. post: tags: - - dois - description: Move a DOI record from draft status to "review". + - dois + description: 'Move a DOI record from draft status to "review".' operationId: post_submit_doi parameters: - - name: identifier - in: query - description: The PDS identifier associated with the record to submit for review. - required: true - style: form - explode: true - schema: - type: string - example: urn:nasa:pds:lab_shocked_feldspars::1.0 - - name: force - in: query - description: If true, forces a submit request to completion, ignoring any - warnings encountered. - required: false - style: form - explode: true - schema: - type: boolean - default: false + - name: force + in: query + description: >- + If true, forces a submit request to completion, ignoring any warnings encountered. + required: false + schema: + type: boolean + default: false responses: - "200": + '200': description: Success content: application/json: schema: $ref: '#/components/schemas/doi_record' - "400": + '400': description: Can not be released - "404": + '404': description: No entry found for identifier - "500": + '500': description: Internal error - x-openapi-router-controller: pds_doi_service.api.controllers.dois_controller # TODO: This routing endpoint has been commented out to effectively block access # to the API's release endpoint until an authentication scheme can # be incorporated to ensure only the Engineering node has access. # /doi/release: -# post: -# tags: -# - dois -# description: Move a DOI record from draft/reserve/review status to "release". -# operationId: post_release_doi -# parameters: +# parameters: # - name: identifier -# in: path -# description: The PDS identifier associated with the record to release. +# in: query +# description: 'The PDS identifier associated with the record to release.' # required: true -# style: form -# explode: true # schema: # type: string # example: 'urn:nasa:pds:lab_shocked_feldspars::1.0' -# - name: force -# in: query -# description: If true, forces a release request to completion, ignoring any -# warnings encountered. -# required: false -# style: form -# explode: true -# schema: -# type: boolean -# default: false +# post: +# tags: +# - dois +# description: 'Move a DOI record from draft/reserve/review status to "release".' +# operationId: post_release_doi +# parameters: +# - name: force +# in: query +# description: >- +# If true, forces a release request to completion, ignoring any warnings encountered. +# required: false +# schema: +# type: boolean +# default: false # responses: -# "200": +# '200': # description: Success # content: # application/json: # schema: # $ref: '#/components/schemas/doi_record' -# "400": +# '400': # description: Can not be released -# "404": +# '404': # description: No entry found for identifier -# "500": +# '500': # description: Internal error -# x-openapi-router-controller: pds_doi_service.api.controllers.dois_controller + /dois/check: get: - tags: - - dois - description: Check submission status of all records pending release. + tags: + - dois + description: 'Check submission status of all records pending release.' operationId: get_check_dois parameters: - - name: email - in: query - description: If true, the check action sends results to the default recipients - and pending DOI submitters. - required: false - style: form - explode: true - schema: - type: boolean - default: false - - name: attachment - in: query - description: If true, the check action sends results as an email attachment. - Has no effect if the email flag is not set to true. - required: false - style: form - explode: true - schema: - type: boolean - default: false - - name: submitter - in: query - description: The email address of the user to register as author of the check - action. This address is also included in the list of recipients. - required: true - style: form - explode: true - schema: - type: string + - name: email + in: query + description: >- + If true, the check action sends results to the default recipients and pending DOI submitters. + required: false + schema: + type: boolean + default: false + - name: attachment + in: query + description: >- + If true, the check action sends results as an email attachment. Has no effect if the email flag is not set to true. + required: false + schema: + type: boolean + default: false + - name: submitter + in: query + description: >- + The email address of the user to register as author of the check action. This address is also included in the list of recipients. + required: true + schema: + type: string responses: - "200": + '200': description: Success content: application/json: schema: $ref: '#/components/schemas/doi_record' - "400": - description: OSTI service cannot be reached - "500": + '400': + description: DOI service provider cannot be reached + '500': description: Internal error - x-openapi-router-controller: pds_doi_service.api.controllers.dois_controller + + components: schemas: label_payload: @@ -493,7 +438,6 @@ components: items: $ref: '#/components/schemas/label_payload' doi_summary: - type: object properties: doi: type: string @@ -510,25 +454,18 @@ components: update_date: type: string format: date-time - example: - node: eng - submitter: my.email@node.gov - identifier: urn:nasa:pds:lab_shocked_feldspars::1.0 - title: Laboratory Shocked Feldspars Collection - update_date: 2001-01-23T04:56:07.000+00:00 - doi: 10.17189/21734 - status: Pending + type: object doi_record: allOf: - - $ref: '#/components/schemas/doi_summary' - - type: object - properties: - record: - type: string - description: full OSTI XML label - creation_date: - type: string - description: Creation date of the DOI record in iso8601 format - format: date-time - message: - type: string + - $ref: '#/components/schemas/doi_summary' + - properties: + record: + type: string + description: full DOI label + creation_date: + type: string + format: date-time + description: Creation date of the DOI record in iso8601 format + message: + type: string + type: object \ No newline at end of file