DI‐Portal‐PKGVER‐005: Download Operations Group (reduced source specifications)

Design Item ID: DI-Portal-PKGVER-005
Design Item Name: Download Operations Group (reduced source specifications)
Related Design Items:
Related API:

Revision History:

Date	Description

---

Description

User can download operations included into operations group (with API type = REST) and in the result receive OpenAPI specification with these operations. There are two options of downloading operations group - reduced source specifications and combined specification (see info about combined specification in Download Operations Group (combined specification)).
Reduced source specifications option allows the user to obtain the source specifications, which contain only those operations that are included in the exported group.
For example, package version contains two OpenAPI specifications:

• specification A contains 3 operations: GET /pets, POST /pet, Delete /pet/{Id}  
• specification B contains 2 operations: GET /users, GET /users/{username}

User creates a group where includes the following operations: GET /pets, POST /pet, GET /users. If user exports this operations group with reduced source specifications option in the result there will be two files: specification A - that contains only GET /pets and POST /pet, and specification B - that contains only GET /users.

Start Point

User navigates to APIHUB Portal → workspace → group → package version → Groups tab

Execution

1. In Groups tab, the user hovers over groups with REST API type, clicks [Export] button and selects needed format (YAML, JSON, HTML) of the specification under 'Download reduced source specifications'.
2. The system:
   • checks if cache exists with reduced source specifications for the operations from operations group
     • API: GET /api/v3/packages/{packageId}/versions/{version}/{apiType}/export/groups/{groupName}/buildType/{buildType} (response 200 - cache exists; responses 404 cache does not exists)
       • apiType = rest
       • buildType = reducedSourceSpecifications
       • groupName = <name of the exported group/>
       • format = <exported file format selected by the user/>
   • if cache exists, the system exports specification in the required format.
   • if cache does not exists, the system executes async build task to transform document
     • API: POST /api/v3/packages/{packageId}/versions/{version}/{apiType}/build/groups/{groupName}/buildType/{buildType}
       • apiType = rest
       • buildType = reducedSourceSpecifications
       • groupName = <name of the exported group/>
       • format = <exported file format selected by the user/>
   • the system gets source documents for all operations from the operations group to transform them
     • API: GET /api/v3/packages/{packageId}/versions/{version}/{apiType}/groups/{groupName}/documents
       • groupName = <name of the exported group/>
   • in the source documents the system finds operations that are not included info operations group and removes them.
   • if some shared objects (i.e. object from components section) was used only in the operations that were removed from the source documents, the system removes such objects.
   • the system exports documents in the required format.
     • API: GET /api/v3/packages/{packageId}/versions/{version}/{apiType}/export/groups/{groupName}/buildType/{buildType}
       • apiType = rest
       • buildType = reducedSourceSpecifications
       • groupName = <name of the exported group/>
       • format = <exported file format selected by the user/>

Client side build:

sequenceDiagram
    participant portal
    participant api-processor
    participant backend

    portal ->> backend: GET /api/v3/packages/{packageId}/versions/{version}/{apiType}/export/groups/{groupName}/buildType/{buildType} (buildType = reducedSourceSpecifications)
    backend -->> portal: 404 response (cache does not exist)

    portal ->> backend: POST /api/v3/packages/{packageId}/versions/{version}/{apiType}/groups/{groupName}/documents
    backend -->> portal: buldConfig

    portal ->> api-processor: dispatch buildConfig

    api-processor ->> backend: GET /api/v3/packages/{packageId}/versions/{version}/{apiType}/groups/{groupName}/documents
    backend -->> api-processor: 200 response (list of documents)

    api-processor ->> api-processor: build

    api-processor -->> portal: buildResult

    portal -> backend: POST /api/v3/packages/{packageId}/publish/{publishId}/status (save buildResult)
    backend --> portal: 204 response
    
    portal ->> backend: GET /api/v3/packages/{packageId}/versions/{version}/{apiType}/export/groups/{groupName}/buildType/{buildType} (buildType = reducedSourceSpecifications)
    backend -->> portal: 200 response

Loading

Server side build:

sequenceDiagram
    participant portal
    participant api-processor
    participant backend
    
    portal ->> backend: GET /api/v3/packages/{packageId}/versions/{version}/{apiType}/export/groups/{groupName}/buildType/{buildType} (buildType = reducedSourceSpecifications)
    backend -->> portal: 404 response (cache does not exist)

    portal ->> backend: POST /api/v3/packages/{packageId}/versions/{version}/{apiType}/build/groups/{groupName}/buildType/{buildType} 

   api-processor ->> backend: get free build
   backend -->> api-processor: free build

   api-processor ->> backend: GET /api/v3/packages/{packageId}/versions/{version}/{apiType}/groups/{groupName}/documents
   backend -->> api-processor: 200 response (list of documents)
   
   api-processor ->> api-processor: build

   api-processor ->> backend: POST /api/v3/packages/{packageId}/publish/{publishId}/status (save buildResult)
   backend -->> api-processor: 204 response

   api-processor ->> backend: GET /api/v2/packages/{packageId}/publish/{publishId}/status
   backend -->> api-processor: return status

    portal ->> backend: GET /api/v3/packages/{packageId}/versions/{version}/{apiType}/export/groups/{groupName}/buildType/{buildType} (buildType = reducedSourceSpecifications)
    backend -->> portal: 200 response

Loading

Screen View

tbd