[cryptalith]

What

The second of four stacked drafts for COMMS-5397. Its base is (a), #7758. It describes every member v3.0 operation, so member-v3.0.yaml lists each one with its success response, token scopes, tag and summary. Summaries are in sentence case ("Create an education", "Fetch all invited positions").

• Operation annotations on MemberV3ApiServiceImplV3_0. All 114 operations get @Operation (summary, tag, security) and @ApiResponse.
  • Source. They are ported from the 2023 Swagger 1.x annotations (git show 8179501c3a^). Every success response was checked against what its delegator returns; the table below links each one.
  • Where 2023 was wrong, the code wins:
    • createWorks answers 200 with a WorkBulk, not 201;
    • viewGroupIdRecords returns a GroupIdRecords page, or a single GroupIdRecord when group-id or name is given;
    • the permission-notification reads answer 200;
    • addPermissionNotification answers 201 with Location;
    • getRecordSummary takes either read token, like every other read.
  • Reads accept two tokens: /read-limited, or a member client's 2-legged /read-public. The second sees public items only, as OrcidSecurityManagerImpl.checkAndFilter allows (isMyToken lets client-credentials tokens through). Each read lists both as alternative security requirements.
  • Writes take the scope their delegator checks: /activities/update for every activity create, update and delete, /person/update for the person section. A review found that the pass adding the second read token had also widened seven creates (education, distinction, invited position, membership, qualification, service, research resource) to the read scopes; they say /activities/update again, as checkClientAccessAndScopes requires.
  • Group IDs. 409 when the group-id already exists (9025), which the create also answers for a new issn: group-id after creating it from the ISSN portal; 409 on delete while peer reviews use the group (9040); 400 when page or page-size is not a number (9020). (c) adds the 400 for an unknown put-code (9026).
  • Search parameters.
    • q is described on the argument that declares it.
    • start, rows and fl reach Solr through UriInfo, so they are declared on the method.
• Shared path parameters. OrcidOpenApiFilter describes orcid and putCode once, for the 100+ operations that take them. The orcid description carries the pattern of an ORCID iD (OrcidStringUtils.ORCID_STRING). The Registry does not match the path against it; an iD that doesn't fit just isn't found (404).
• Base file. openapi/base/member-v3.0.yaml gains:
  • the orcid_auth OAuth 2.0 scheme, with authorization-code and client-credentials flows and what each scope allows;
  • the tags, in navigation order, with descriptions.

Not in this PR:

• Error responses at this branch are the ones the 2023 annotations listed, carried over unchecked. (c) replaces them with the errors the contract suite (ORCID/orcid-api-contract-tests, private) observed against a running Registry.
• Webhooks are annotated in (c). At this branch their two operations still have no summary or security.

Runtime impact

None. The changes are annotations, a generator-only filter, and a YAML base file.

How it was checked

• Executed test counts. One run at the head of (c) (fe4042b), which contains this branch and its review fixes; this branch's own commits change annotations only.

  • orcid-api-common: 132 tests (26 of them come with (c));
  • orcid-pub-web: 390;
  • orcid-api-web: 1249.

  All with 0 failures.

• Generation:

  • two consecutive builds produce byte-identical YAML;
  • the spec has 116 operations, and every operation except the two webhooks has a 2xx, security, a tag and a summary;
  • no default response is left.

• Redocly CLI 1.34.5, recommended rules, at the head of (c):

  • 0 errors.
  • no-ambiguous-paths is off. /v3.0/client/{client_id} and /v3.0/{orcid}/email look ambiguous only to a linter that ignores the iD pattern; the server matches literal segments first.
  • 92 operation-4xx-response warnings remain until the common error responses land.

Per-operation table

Success responses and scopes as the generated spec states them, and the delegator method each was checked against.

Tag	operationId	Method and path	Success	Token scopes	Checked against
Record	viewRecord	GET /v3.0/{orcid}	200: Record	/read-limited or /read-public	viewRecord
Record	viewRecordRecord	GET /v3.0/{orcid}/record	200: Record	/read-limited or /read-public	viewRecord
Record summary	getRecordSummary	GET /v3.0/{orcid}/summary	200: RecordSummary	/read-limited or /read-public	getRecordSummary
Person	viewPerson	GET /v3.0/{orcid}/person	200: Person	/read-limited or /read-public	viewPerson
Personal details	viewPersonalDetails	GET /v3.0/{orcid}/personal-details	200: PersonalDetails	/read-limited or /read-public	viewPersonalDetails
Biography	viewBiography	GET /v3.0/{orcid}/biography	200: Biography	/read-limited or /read-public	viewBiography
Other names	viewOtherNames	GET /v3.0/{orcid}/other-names	200: OtherNames	/read-limited or /read-public	viewOtherNames
Other names	createOtherName	POST /v3.0/{orcid}/other-names	201 + Location	/person/update	createOtherName
Other names	deleteOtherName	DELETE /v3.0/{orcid}/other-names/{putCode}	204	/person/update	deleteOtherName
Other names	viewOtherName	GET /v3.0/{orcid}/other-names/{putCode}	200: OtherName	/read-limited or /read-public	viewOtherName
Other names	editOtherName	PUT /v3.0/{orcid}/other-names/{putCode}	200: OtherName	/person/update	updateOtherName
Researcher URLs	viewResearcherUrls	GET /v3.0/{orcid}/researcher-urls	200: ResearcherUrls	/read-limited or /read-public	viewResearcherUrls
Researcher URLs	createResearcherUrl	POST /v3.0/{orcid}/researcher-urls	201 + Location	/person/update	createResearcherUrl
Researcher URLs	deleteResearcherUrl	DELETE /v3.0/{orcid}/researcher-urls/{putCode}	204	/person/update	deleteResearcherUrl
Researcher URLs	viewResearcherUrl	GET /v3.0/{orcid}/researcher-urls/{putCode}	200: ResearcherUrl	/read-limited or /read-public	viewResearcherUrl
Researcher URLs	editResearcherUrl	PUT /v3.0/{orcid}/researcher-urls/{putCode}	200: ResearcherUrl	/person/update	updateResearcherUrl
Keywords	viewKeywords	GET /v3.0/{orcid}/keywords	200: Keywords	/read-limited or /read-public	viewKeywords
Keywords	createKeyword	POST /v3.0/{orcid}/keywords	201 + Location	/person/update	createKeyword
Keywords	deleteKeyword	DELETE /v3.0/{orcid}/keywords/{putCode}	204	/person/update	deleteKeyword
Keywords	viewKeyword	GET /v3.0/{orcid}/keywords/{putCode}	200: Keyword	/read-limited or /read-public	viewKeyword
Keywords	editKeyword	PUT /v3.0/{orcid}/keywords/{putCode}	200: Keyword	/person/update	updateKeyword
Addresses	viewAddresses	GET /v3.0/{orcid}/address	200: Addresses	/read-limited or /read-public	viewAddresses
Addresses	createAddress	POST /v3.0/{orcid}/address	201 + Location	/person/update	createAddress
Addresses	deleteAddress	DELETE /v3.0/{orcid}/address/{putCode}	204	/person/update	deleteAddress
Addresses	viewAddress	GET /v3.0/{orcid}/address/{putCode}	200: Address	/read-limited or /read-public	viewAddress
Addresses	editAddress	PUT /v3.0/{orcid}/address/{putCode}	200: Address	/person/update	updateAddress
Emails	viewEmails	GET /v3.0/{orcid}/email	200: Emails	/read-limited or /read-public	viewEmails
External identifiers	viewExternalIdentifiers	GET /v3.0/{orcid}/external-identifiers	200: PersonExternalIdentifiers	/read-limited or /read-public	viewExternalIdentifiers
External identifiers	createExternalIdentifier	POST /v3.0/{orcid}/external-identifiers	201 + Location	/person/update	createExternalIdentifier
External identifiers	deleteExternalIdentifier	DELETE /v3.0/{orcid}/external-identifiers/{putCode}	204	/person/update	deleteExternalIdentifier
External identifiers	viewExternalIdentifier	GET /v3.0/{orcid}/external-identifiers/{putCode}	200: PersonExternalIdentifier	/read-limited or /read-public	viewExternalIdentifier
External identifiers	editExternalIdentifier	PUT /v3.0/{orcid}/external-identifiers/{putCode}	200: PersonExternalIdentifier	/person/update	updateExternalIdentifier
Activities	viewActivities	GET /v3.0/{orcid}/activities	200: ActivitiesSummary	/read-limited or /read-public	viewActivities
Works	createWork	POST /v3.0/{orcid}/work	201 + Location	/activities/update	createWork
Works	viewWorkSummary	GET /v3.0/{orcid}/work/summary/{putCode}	200: WorkSummary	/read-limited or /read-public	viewWorkSummary
Works	deleteWork	DELETE /v3.0/{orcid}/work/{putCode}	204	/activities/update	deleteWork
Works	viewWork	GET /v3.0/{orcid}/work/{putCode}	200: Work	/read-limited or /read-public	viewWork
Works	updateWork	PUT /v3.0/{orcid}/work/{putCode}	200: Work	/activities/update	updateWork
Works	viewWorks	GET /v3.0/{orcid}/works	200: WorksSummary	/read-limited or /read-public	viewWorks
Works	createWorks	POST /v3.0/{orcid}/works	200: WorkBulk	/activities/update	createWorks
Works	viewSpecifiedWorks	GET /v3.0/{orcid}/works/{putCodes}	200: WorkBulk	/read-limited or /read-public	viewBulkWorks
Fundings	createFunding	POST /v3.0/{orcid}/funding	201 + Location	/activities/update	createFunding
Fundings	viewFundingSummary	GET /v3.0/{orcid}/funding/summary/{putCode}	200: FundingSummary	/read-limited or /read-public	viewFundingSummary
Fundings	deleteFunding	DELETE /v3.0/{orcid}/funding/{putCode}	204	/activities/update	deleteFunding
Fundings	viewFunding	GET /v3.0/{orcid}/funding/{putCode}	200: Funding	/read-limited or /read-public	viewFunding
Fundings	updateFunding	PUT /v3.0/{orcid}/funding/{putCode}	200: Funding	/activities/update	updateFunding
Fundings	viewFundings	GET /v3.0/{orcid}/fundings	200: Fundings	/read-limited or /read-public	viewFundings
Education	createEducation	POST /v3.0/{orcid}/education	201 + Location	/activities/update	createEducation
Education	viewEducationSummary	GET /v3.0/{orcid}/education/summary/{putCode}	200: EducationSummary	/read-limited or /read-public	viewEducationSummary
Education	deleteEducation	DELETE /v3.0/{orcid}/education/{putCode}	204	/activities/update	deleteAffiliation
Education	viewEducation	GET /v3.0/{orcid}/education/{putCode}	200: Education	/read-limited or /read-public	viewEducation
Education	updateEducation	PUT /v3.0/{orcid}/education/{putCode}	200: Education	/activities/update	updateEducation
Education	viewEducations	GET /v3.0/{orcid}/educations	200: EducationsSummary	/read-limited or /read-public	viewEducations
Employment	createEmployment	POST /v3.0/{orcid}/employment	201 + Location	/activities/update	createEmployment
Employment	viewEmploymentSummary	GET /v3.0/{orcid}/employment/summary/{putCode}	200: EmploymentSummary	/read-limited or /read-public	viewEmploymentSummary
Employment	deleteEmployment	DELETE /v3.0/{orcid}/employment/{putCode}	204	/activities/update	deleteAffiliation
Employment	viewEmployment	GET /v3.0/{orcid}/employment/{putCode}	200: Employment	/read-limited or /read-public	viewEmployment
Employment	updateEmployment	PUT /v3.0/{orcid}/employment/{putCode}	200: Employment	/activities/update	updateEmployment
Employment	viewEmployments	GET /v3.0/{orcid}/employments	200: EmploymentsSummary	/read-limited or /read-public	viewEmployments
Qualification	createQualification	POST /v3.0/{orcid}/qualification	201 + Location	/activities/update	createQualification
Qualification	viewQualificationSummary	GET /v3.0/{orcid}/qualification/summary/{putCode}	200: QualificationSummary	/read-limited or /read-public	viewQualificationSummary
Qualification	deleteQualification	DELETE /v3.0/{orcid}/qualification/{putCode}	204	/activities/update	deleteAffiliation
Qualification	viewQualification	GET /v3.0/{orcid}/qualification/{putCode}	200: Qualification	/read-limited or /read-public	viewQualification
Qualification	updateQualification	PUT /v3.0/{orcid}/qualification/{putCode}	200: Qualification	/activities/update	updateQualification
Qualification	viewQualifications	GET /v3.0/{orcid}/qualifications	200: Qualifications	/read-limited or /read-public	viewQualifications
Invited position	createInvitedPosition	POST /v3.0/{orcid}/invited-position	201 + Location	/activities/update	createInvitedPosition
Invited position	viewInvitedPositionSummary	GET /v3.0/{orcid}/invited-position/summary/{putCode}	200: InvitedPositionSummary	/read-limited or /read-public	viewInvitedPositionSummary
Invited position	deleteInvitedPosition	DELETE /v3.0/{orcid}/invited-position/{putCode}	204	/activities/update	deleteAffiliation
Invited position	viewInvitedPosition	GET /v3.0/{orcid}/invited-position/{putCode}	200: InvitedPosition	/read-limited or /read-public	viewInvitedPosition
Invited position	updateInvitedPosition	PUT /v3.0/{orcid}/invited-position/{putCode}	200: InvitedPosition	/activities/update	updateInvitedPosition
Invited position	viewInvitedPositions	GET /v3.0/{orcid}/invited-positions	200: InvitedPositions	/read-limited or /read-public	viewInvitedPositions
Distinction	createDistinction	POST /v3.0/{orcid}/distinction	201 + Location	/activities/update	createDistinction
Distinction	viewDistinctionSummary	GET /v3.0/{orcid}/distinction/summary/{putCode}	200: DistinctionSummary	/read-limited or /read-public	viewDistinctionSummary
Distinction	deleteDistinction	DELETE /v3.0/{orcid}/distinction/{putCode}	204	/activities/update	deleteAffiliation
Distinction	viewDistinction	GET /v3.0/{orcid}/distinction/{putCode}	200: Distinction	/read-limited or /read-public	viewDistinction
Distinction	updateDistinction	PUT /v3.0/{orcid}/distinction/{putCode}	200: Distinction	/activities/update	updateDistinction
Distinction	viewDistinctions	GET /v3.0/{orcid}/distinctions	200: DistinctionsSummary	/read-limited or /read-public	viewDistinctions
Membership	createMembership	POST /v3.0/{orcid}/membership	201 + Location	/activities/update	createMembership
Membership	viewMembershipSummary	GET /v3.0/{orcid}/membership/summary/{putCode}	200: MembershipSummary	/read-limited or /read-public	viewMembershipSummary
Membership	deleteMembership	DELETE /v3.0/{orcid}/membership/{putCode}	204	/activities/update	deleteAffiliation
Membership	viewMembership	GET /v3.0/{orcid}/membership/{putCode}	200: Membership	/read-limited or /read-public	viewMembership
Membership	updateMembership	PUT /v3.0/{orcid}/membership/{putCode}	200: Membership	/activities/update	updateMembership
Membership	viewMemberships	GET /v3.0/{orcid}/memberships	200: Memberships	/read-limited or /read-public	viewMemberships
Service	createService	POST /v3.0/{orcid}/service	201 + Location	/activities/update	createService
Service	viewServiceSummary	GET /v3.0/{orcid}/service/summary/{putCode}	200: ServiceSummary	/read-limited or /read-public	viewServiceSummary
Service	deleteService	DELETE /v3.0/{orcid}/service/{putCode}	204	/activities/update	deleteAffiliation
Service	viewService	GET /v3.0/{orcid}/service/{putCode}	200: Service	/read-limited or /read-public	viewService
Service	updateService	PUT /v3.0/{orcid}/service/{putCode}	200: Service	/activities/update	updateService
Service	viewServices	GET /v3.0/{orcid}/services	200: Services	/read-limited or /read-public	viewServices
Peer reviews	createPeerReview	POST /v3.0/{orcid}/peer-review	201 + Location	/activities/update	createPeerReview
Peer reviews	viewPeerReviewSummary	GET /v3.0/{orcid}/peer-review/summary/{putCode}	200: PeerReviewSummary	/read-limited or /read-public	viewPeerReviewSummary
Peer reviews	deletePeerReview	DELETE /v3.0/{orcid}/peer-review/{putCode}	204	/activities/update	deletePeerReview
Peer reviews	viewPeerReview	GET /v3.0/{orcid}/peer-review/{putCode}	200: PeerReview	/read-limited or /read-public	viewPeerReview
Peer reviews	updatePeerReview	PUT /v3.0/{orcid}/peer-review/{putCode}	200: PeerReview	/activities/update	updatePeerReview
Peer reviews	viewPeerReviews	GET /v3.0/{orcid}/peer-reviews	200: PeerReviews	/read-limited or /read-public	viewPeerReviews
Research resources	createResearchResource	POST /v3.0/{orcid}/research-resource	201 + Location	/activities/update	createResearchResource
Research resources	viewResearchResourceSummary	GET /v3.0/{orcid}/research-resource/summary/{putCode}	200: ResearchResourceSummary	/read-limited or /read-public	viewResearchResourceSummary
Research resources	deleteResearchResource	DELETE /v3.0/{orcid}/research-resource/{putCode}	204	/activities/update	deleteResearchResource
Research resources	viewResearchResource	GET /v3.0/{orcid}/research-resource/{putCode}	200: ResearchResource	/read-limited or /read-public	viewResearchResource
Research resources	updateResearchResource	PUT /v3.0/{orcid}/research-resource/{putCode}	200: ResearchResource	/activities/update	updateResearchResource
Research resources	viewResearchResources	GET /v3.0/{orcid}/research-resources	200: ResearchResources	/read-limited or /read-public	viewResearchResources
Notifications	viewPermissionNotifications	GET /v3.0/{orcid}/notification-permission	200: NotificationPermissions	/premium-notification	findPermissionNotifications
Notifications	addPermissionNotification	POST /v3.0/{orcid}/notification-permission	201 + Location	/premium-notification	addPermissionNotification
Notifications	flagAsArchivedPermissionNotification	DELETE /v3.0/{orcid}/notification-permission/{id}	200: NotificationPermission	/premium-notification	flagNotificationAsArchived
Notifications	viewPermissionNotification	GET /v3.0/{orcid}/notification-permission/{id}	200: NotificationPermission	/premium-notification	findPermissionNotification
Group IDs	viewGroupIdRecords	GET /v3.0/group-id-record	200: GroupIdRecords or GroupIdRecord	/group-id-record/read	findGroupIdRecordByGroupId
Group IDs	createGroupIdRecord	POST /v3.0/group-id-record	201 + Location	/group-id-record/update	createGroupIdRecord
Group IDs	deleteGroupIdRecord	DELETE /v3.0/group-id-record/{putCode}	204	/group-id-record/update	deleteGroupIdRecord
Group IDs	viewGroupIdRecord	GET /v3.0/group-id-record/{putCode}	200: GroupIdRecord	/group-id-record/read	viewGroupIdRecord
Group IDs	updateGroupIdRecord	PUT /v3.0/group-id-record/{putCode}	200: GroupIdRecord	/group-id-record/update	updateGroupIdRecord
Clients	viewClient	GET /v3.0/client/{client_id}	200: ClientSummary	/read-public	viewClient
Search	searchByQueryCSV	GET /v3.0/csv-search	200: string (text/csv)	/read-public	searchByQueryCSV
Search	expandedSearchByQuery	GET /v3.0/expanded-search	200: ExpandedSearch	/read-public	expandedSearchByQuery
Search	searchByQuery	GET /v3.0/search	200: Search	/read-public	searchByQuery