@W-23307229 Sync api-designer-experience OAS spec with vcs-xapi RAML changes - #162
@W-23307229 Sync api-designer-experience OAS spec with vcs-xapi RAML changes#162iamerico wants to merge 7 commits into
Conversation
…changes (PR #1207) Add ~19 new endpoints and mark 2 operations as deprecated in the api-designer-experience OpenAPI spec to match the internal RAML spec changes made in api-designer-vcs-xapi PR #1207: readiness/config/feature flag endpoints, new project and branch sub-resources (files, rename, clone, settings, changes, events, import, archive, dependency job status), the full Github OAuth flow, global Exchange asset search, and organization identities lookup. Bump exchange.json version to 1.2.0.
lbauret
left a comment
lbauret
left a comment
There was a problem hiding this comment.
Sync of api-designer-experience OAS against the vcs-xapi RAML from #1207 — all #1207-scoped additions are propagated faithfully, no published endpoint removed, and the SemVer minor bump matches the additive-only shape of the change. Two small fidelity drifts against the RAML source worth catching before this ships, plus three pre-existing patterns worth calling out.
AI-assisted review
Should fix
1. EventPayload schema drops RAML-required flags on id and payload — apis/api-designer-experience/api.yaml:2878 (consumer at L1002)
Source RAML types/eventPayload.raml declares id: type: string / payload: type: object with no ? suffix — under RAML 1.0 both are required. OAS omits required: [id, payload], so contract-driven clients infer both as optional. Direct fidelity break on a brand-new endpoint for a published MDH spec.
EventPayload:
type: object
required:
- id
- payload
properties:
id:
type: string
payload:
type: object2. GET /github token and origin query params marked optional; RAML treats them as required — apis/api-designer-experience/api.yaml:2195-2204
RAML token: type: string / origin: type: string lack required: false; RAML 1.0 defaults query params to required. Both carry descriptions ("Token used to authenticate against github" / "Origin of the request being made in order to build the redirect URL") that only make sense as required. OAS advertises them as optional. Fix: add required: true to each - name: token / - name: origin entry.
Consider
3. Pre-existing verb drift on POST /projects/{projectId}/branches/{branch}/open not corrected — apis/api-designer-experience/api.yaml:1010-1062
Post-#1207 RAML defines this as GET /open (api.raml:361); OAS keeps post from the pre-PR baseline. Not introduced by this PR, but the PR title says "sync with vcs-xapi RAML changes," so a fresh reader will assume OAS matches — it doesn't. Either fix here or file a follow-up.
4. Several RAML endpoints outside #1207's scope remain unpublished — RAML at HEAD still contains PUT /projects/{projectId}/branches/{branch} (rename branch), …/conformance, /conformance/plan, …/commits, …/merge, …/keepAlive, …/exchange GET + POST, /projects/credentials, /projects/access/permissions, /external/*, /exchange/assets/{groupId}/{assetId}/{version}, and org-level settings/access/permissions/exchange/facets. All pre-existing gaps (not regressions). If the intent is complete parity, follow-up PR; if not, worth calling out in the PR description.
5. /organizations/{orgId}/identities orgId path param lacks UUID pattern that peers carry — apis/api-designer-experience/api.yaml:181-186
Not required by RAML, but every other x-owner-id/x-organization-id in this file uses the UUID regex ^[0-9a-fA-F]{8}\-…\-[0-9a-fA-F]{12}$. For a published MDH spec, consistent UUID validation matches downstream expectations.
Summary
2 Should fix, 3 Consider — verdict COMMENT. Top ask: land the two Should-fix fidelity nits (EventPayload required flags + /github query-param required flags) before this merges so the derived contracts don't ship advertising the wrong shape.
| type: string | ||
| result: | ||
| type: string | ||
| EventPayload: |
There was a problem hiding this comment.
Should fix — Source RAML types/eventPayload.raml declares id: type: string / payload: type: object with no ? suffix, so both are required under RAML 1.0. This OAS block omits required: [id, payload], and contract-driven clients will infer both as optional. Suggest:
EventPayload:
type: object
required:
- id
- payload
properties:
id:
type: string
payload:
type: object| type: string | ||
| - name: origin | ||
| description: Origin of the request being made in order to build the redirect URL | ||
| in: query |
There was a problem hiding this comment.
Should fix — RAML source has token: type: string and origin: type: string with no required: false — RAML 1.0 defaults query params to required. Both descriptions ("Token used to authenticate against github" / "Origin of the request being made in order to build the redirect URL") only make sense as required. Please add required: true to each - name: token / - name: origin entry.
| '200': | ||
| description: Successful operation. | ||
| operationId: createProjectsByProjectidBranchesByBranchEvents | ||
| /projects/{projectId}/branches/{branch}/open: |
There was a problem hiding this comment.
Consider — Post-#1207 RAML defines this as GET /open (api.raml:361); the OAS still describes it as post from the pre-PR baseline. Not introduced by this PR, but since the title says "sync with vcs-xapi RAML changes," a fresh reader will assume the two are aligned — they aren't. Fix here or file a follow-up.
…params, required schema fields
- Fix .../branches/{branch}/open method (post -> get) to match current RAML
- Add required: true to GET /github's token and origin query parameters
- Add required: [id, payload] to the EventPayload schema
Propagates the 6 RAML/routes.js parity fixes from api-designer-vcs-xapi
PR #1207 into this OAS translation, keeping both specs consistent:
- Add PATCH and GET .../exchange/dependencies
- Fix .../branches/{branch}/status method (get -> post)
- Add GET .../access/permissions/share (new SharedWithIdentities schema)
- Add /health as a documented alias of /ping and /status
lbauret
left a comment
lbauret
left a comment
There was a problem hiding this comment.
Follow-up on the delta since my COMMENT at ff4e05c — the three round-1 fixes are in and untouched; this delta is a net expansion (5 new endpoints, 1 verb flip, 1 query param, 1 new component schema) translating the RAML additions from mulesoft-emu/api-designer-vcs-xapi#1207. One naming drift on the /status GET→POST switch worth catching before the next publish.
Should fix
/projects/{projectId}/branches/{branch}/statusoperationIdis stale after the verb switch (apis/api-designer-experience/api.yaml:1108-1143). Verb flipped topost, butoperationId: getProjectsByProjectidBranchesByBranchStatusstill saysget. Every neighboring POST on this collection uses thecreate*prefix (createProjectsByProjectidBranchesByBranchClean,createProjectsByProjectidBranchesByBranchSave) — the mismatch will leak into generated SDK method names. RecommendcreateProjectsByProjectidBranchesByBranchStatus.
Summary
1 Should fix — verdict COMMENT. Top ask is the stale operationId after the /status GET→POST switch.
| description: Successful operation. | ||
| '401': | ||
| description: Authorization failed | ||
| operationId: getProjectsByProjectidBranchesByBranchStatus |
There was a problem hiding this comment.
Should fix — the verb flipped get → post here, but operationId still carries the get* prefix. Every neighboring POST in this file uses the create* prefix (createProjectsByProjectidBranchesByBranchClean, createProjectsByProjectidBranchesByBranchSave). Since generated SDK method names key off operationId, this will surface as a naming inconsistency in every downstream client. Suggest:
operationId: createProjectsByProjectidBranchesByBranchStatus…ts from OAS
Removes GET /configuration (PKCE migration flags) and the deprecated
endpoints (.../publish/platform, GET .../api/{name}, POST
.../api/{name}/{version}, POST /github/session), matching the same
removal just applied to the source RAML in api-designer-vcs-xapi#1207.
Closes the remaining gap between this OAS translation and the internal
RAML spec (api-designer-vcs-xapi#1207), verified field-by-field against
the RAML types and the real route/service code, then independently
re-verified by an adversarial review pass.
New endpoints (17):
- GET/POST /organizations/{orgId}/settings (+ x-all-settings header)
- GET /organizations/{orgId}/access/permissions
- GET /organizations/{orgId}/exchange/facets
- GET /projects/access/permissions
- GET/DELETE /projects/credentials
- PUT /projects/{projectId}/branches/{branch} (rename)
- GET .../branches/{branch}/commits
- POST .../branches/{branch}/merge
- GET .../branches/{branch}/conformance and /conformance/plan
- POST .../branches/{branch}/keepAlive
- GET .../branches/{branch}/exchange
- POST .../branches/{branch}/exchange/assets
- GET /external/check_access, /external/repositories(/{repositoryId}), /external/organizations
Schema fixes:
- Project: vcsType -> vcsStorageType, add lastUpdatedDate/defaultBranch/deleted/initialWorkingDirectory
- ProjectCreate/ProjectImport: classifier enum (6 values) replacing narrow type enum
- ProjectSync: was a copy-paste of ProjectImport; now the real domain/domainType/repositoryName shape
- ProjectPermissions: add canPublish/canShare/canOwn
- SharedWith/SharedWithResult: revoke -> revoked, drop nonexistent previousSharedWith, add type/role/result enums
- PublishExchange/PublishResponse invented fields replaced with the real ProjectPublish schema on
POST .../exchange/assets; /publish/exchange itself correctly left with no typed body
- createBranch: add baseBranch; misc missing query params/headers on branches, save/v2, files/v2
Bump exchange.json version to 1.3.0 (additive, backward-compatible).
| in: query | ||
| schema: | ||
| type: boolean | ||
| - name: searchTerm |
There was a problem hiding this comment.
[BLOCKER] Query parameter 'searchTerm' must have a description
Parameter 'searchTerm' on GET /exchange/assets has no description field. This is a governance-rule violation (input-types-described) — make validate-all-governed fails for this API. All endpoint input parameters (query, path, header) must be documented with a description.
| in: query | ||
| schema: | ||
| type: string | ||
| - name: businessId |
There was a problem hiding this comment.
[BLOCKER] Query parameter 'businessId' must have a description
Same input-types-described violation as 'searchTerm' above — this new query parameter on GET /exchange/assets has no description.
| in: query | ||
| schema: | ||
| type: string | ||
| - name: pageOffset |
There was a problem hiding this comment.
[BLOCKER] Query parameter 'pageOffset' must have a description
Same input-types-described violation — this new query parameter on GET /exchange/assets has no description.
| in: query | ||
| schema: | ||
| type: number | ||
| - name: status |
There was a problem hiding this comment.
[BLOCKER] Query parameter 'status' must have a description
Same input-types-described violation — this new query parameter on GET /exchange/assets has no description.
| get: | ||
| description: Redirects the response received from Github (code and state query params) back to the Design Center UI | ||
| parameters: | ||
| - name: code |
There was a problem hiding this comment.
[BLOCKER] Query parameter 'code' must have a description
On GET /github/oauth/callback, the 'code' query parameter has no description. input-types-described governance rule violation.
| in: query | ||
| schema: | ||
| type: string | ||
| - name: state |
There was a problem hiding this comment.
[BLOCKER] Query parameter 'state' must have a description
On GET /github/oauth/callback, the 'state' query parameter has no description. input-types-described governance rule violation.
| '302': | ||
| description: Redirection response | ||
| headers: | ||
| Location: |
There was a problem hiding this comment.
[BLOCKER] 'Location' response header must have a description
The 302 response header on GET /github/oauth/callback has no description. input-types-described governance rule violation — applies to headers too.
| '302': | ||
| description: Redirection response | ||
| headers: | ||
| Location: |
There was a problem hiding this comment.
[BLOCKER] 'Location' response header must have a description
The 302 response header on GET /github has no description. Same input-types-described violation as the /github/oauth/callback Location header.
| get: | ||
| description: Retrieves identities (users/teams) belonging to the given organization, optionally filtered by search term | ||
| parameters: | ||
| - name: orgId |
There was a problem hiding this comment.
[BLOCKER] Path parameter must be named 'organizationId', not 'orgId'
GET /organizations/{orgId}/identities uses 'orgId' as the path parameter name. Repo convention (path-organization-identifier governance rule) requires 'organizationId' for the organization context. Rename the path template and parameter.
| content: | ||
| application/zip: | ||
| schema: {} | ||
| operationId: getProjectsByProjectidBranchesByBranchArchive |
There was a problem hiding this comment.
[BLOCKER] Operation must have at least one response example
GET /projects/{projectId}/branches/{branch}/archive (200 response, application/zip) has no example. operation-examples governance rule violation — every endpoint must provide at least one example so consumers understand the response shape.
Inline the requestBody schema for acquireLock/releaseLock/keepAlive/publish-exchange instead of pairing a $ref with a sibling description (invalid in OAS 3.0), and drop the now-unreferenced Generated requestBody component. Replace patternProperties in FilesForm with additionalProperties, since patternProperties is not part of OAS 3.0.
|
Hi team. Could you please review this PR (API Designer Experience API / api-designer-xapi)? Already approved by someone on the team, and the requested changes have been incorporated. I also validated the specification and the portal locally with: |
3 participants
Summary
Updates the published
apis/api-designer-experience/api.yamlspec to reflect the internal RAML changes made to theapi-designer-vcs-xapiservice in api-designer-vcs-xapi#1207 (currently under teammate review)./ready,/configuration,/config,/features), project sub-resources (files,rename,clone,settings,changes+ variants), branch sub-resources (events,import,archive,exchange/dependencies/job), the full Github OAuth flow (/github,/github/callback,/github/oauth,/github/oauth/callback,/github/session), global Exchange asset search (/exchange/assets), and organization identities lookup (/organizations,/organizations/{orgId}/identities).POST .../publish/platformandGET .../api/{name}as(Deprecated)in their descriptions, matching the file's existing text-only deprecation convention.EventPayloadschema for the new/eventsendpoint.exchange.jsonversion from1.1.5to1.2.0(minor — new backward-compatible functionality).Note:
api-designer-vcs-xapiPR #1207 is still under review. If reviewers request RAML changes there, this PR will get a follow-up joint revision to stay in sync.Test plan
python3 -c "import yaml/json")operationIds across 60 total operationspython3 scripts/build/validate_xorigin.py— no violationspython3 scripts/build/validate_descriptions.py— no violations