Create a download-starter-project endpoint in the registry.

[schultzp2020]

Which area this feature is related to?
/area registry

Which functionality do you think we should add?

Create a download-starter-project endpoint in the registry.

Why is this needed? Is your feature request related to a problem?
Currently, we have this functionality in the registry-viewer; however, Next.js is limiting the body download size in future versions.

In addition, by creating this endpoint we can deploy the registry-viewer statically. The previous holdup was because any file in the /pages/api directory would create an api which requires a node server. If we could rip the download-starter-project functionality out of the api directory, the only other api in the directory, which is nonessential, is to make the registry-viewer dynamic. Therefore, by making this change it allows the registry-viewer to be static.

Describe the solution you'd like

An endpoint that takes a devfileName and a starterProjectName and downloads the starterProject when queried.

Describe alternatives you've considered

Keep this functionality inside of the registry-viewer; however, this has issues as stated above.

[michael-valdron]

This new feature introduces a new endpoint GET /devfiles/:devfileName/starterProjects/:starterProjectName which will handle the download trigger for the starter project template. The handler for this endpoint is currently called serveDevfileStarterProject.

[michael-valdron]

Part of the /devfiles/:devfileName/starterProjects/:starterProjectName endpoint this new feature introduces reuses source that already exists for the /devfiles/:name endpoint. As such, I am purposing one of the following implementations for a new function I am currently calling fetchDevfile.

Implementation 1

func fetchDevfile(devfileName string) ([]byte, error) {
	...
}

This implementation does not take the gin.Context entity as a parameter and relies on the error being returned for logging and setting the unsuccessful responses:

func serveDevfileStarterProject(c *gin.Context) {
	...

	devfileBytes, err := fetchDevfile(devfileName)

	if err != nil {
		log.Print(err.Error())
		c.JSON(http.StatusInternalServerError, gin.H{
			"error":  err.Error(),
			"status": fmt.Sprintf("failed to pull the devfile of %s", devfileName),
		})
		return
	} else if len(devfileBytes) == 0 {
		c.JSON(http.StatusNotFound, gin.H{
			"status": fmt.Sprintf("the devfile of %s didn't exist", devfileName),
		})
		return
	}

	...
}

This implementation makes the process simple but limits the status outcomes to as they are currently. If this poses a problem to future changes I have purposed Implementation 2 as an alternative. The devfile []byte result is empty if fetchDevfile is unsuccessful.

Implementation 2

func fetchDevfile(c *gin.Context, devfileName string) []byte {
	...
}

This implementation consists most of the source from /devfile/:name endpoint for fetching the devfile. It takes a pointer to the gin.Context as a parameter so unsuccessful responses tied to this are set in this function rather than endpoint's function. Due to this, we only need to return the devfile []byte result rather than additional error entity.

[michael-valdron]

Implementation 2 for fetchDevfile has been chosen with modified return type for returning the index schema for telemetry, current version below:

func fetchDevfile(c *gin.Context, devfileName string) ([]byte, indexSchema.Schema) {
	...
}

[michael-valdron]

Closed issue #750 provides the following for getting the selected starterproject download location from the devfile contents:

filterOptions := common.DevfileOptions{
    FilterByName: starterProjectName,
}
...
starterProjects, err = content.Data.GetStarterProjects(filterOptions)

[yangcao77]

@michael-valdron I want to raise up your attention that for the filter, if no such object fulfills all the filter conditions, it will just return an empty list, without any errors. The same behavior applies to name filter as well.
So if you want to alert on a non-existing starterProjectName being provided, you should check len(starterProjects) == 0 .

[michael-valdron]

@yangcao77 Perfect, thanks letting know. I will use this as one of the conditions which produces the Not Found response for the endpoint:

if len(starterProjects) == 0 {
    c.JSON(http.StatusNotFound, gin.H{
        "status": fmt.Sprintf("the starter project named %s does not exist in the devfile of %s", starterProjectName, devfileName),
    })
}

[yangcao77]

Since the index generated is with the new format, the starterProject endpoints need to look for a version, (version string or latest). If not version is provided, then pick the default.
As documented: https://docs.google.com/document/d/1_eXbAV1eKetKKu_FHGRw6kUUiUhcp7j1gB0uUrG0WF8/edit#heading=h.1pf53oes5yvw