Readthedocs.org: api v3 is missing add a subproject

[Aricg]

Details

Adding a project as a Subproject of another project is still a manual operation.

From the docs:
In the admin dashboard for your project, select “Subprojects” from the menu. From this page you can add a subproject by typing in the project slug.

The API v3 Only has the method for: "Subprojects listing"

Expected Result

In order to take advantage of subprojects we will need an API method, so that new projects that are added can be properly placed under their parent project

Actual Result

Currently an admin would need to monitor new projects as they add their first docs and add them as a subproject by hand.

[humitos]

Thanks for your feedback.

I'm thinking this can be implemented in this way:

• Make a Project _subproject_ of another one by a POST at /api/v3/projects/<superproject>/subprojects/ with the body:

{
  "child": "subproject-slug",
  "alias": "subproject-alias",
}

• Remove a _subproject_ from a Project by DELETE at /api/v3/projects/<superproject>/subprojects/subproject-alias/

Both endpoint works similarly than the web UI: to create a subproject relationship the subproject should already exist. When removing the subproject relationship the subproject itself is not deleted.

I was thinking that GET on /api/v3/projects/<superproject>/subprojects/subproject-alias/ could show a detail view of the ProjectRelationship but I'm not sure it adds value.

Regarding permissions, the user should be maintainer of both Projects (super- and sub-).

@readthedocs/core what do you think?

[stsewd]

I would change the post request from /api/v3/projects/<superproject>/ to /api/v3/projects/<superproject>/subprojects/ It follows the convention for APIs (post to resource to create one)

I was thinking that GET on /api/v3/projects//subprojects/subproject-alias/ could show a detail view of the ProjectRelationship but I'm not sure it adds value.

I think it does, we don't have other way to show the alias/original slug

[humitos]

I would change the post request from /api/v3/projects/<superproject>/ to /api/v3/projects/<superproject>/subprojects/ It follows the convention for APIs (post to resource to create one)

Thanks. I made a mistake when writing the URL. I edited my comment.

I think it does, we don't have other way to show the alias/original slug

Under /api/v3/projects/slug/subprojects/ we are showing Project details instead of ProjectRelationship details. Do you think we should change that as well?

[lfdwt]

I think that the top-level project slug in the endpoint is enough to understand where we are. I think anything under subprojects should reflect only the particular subproject.

[stsewd]

@humitos I think we need to show the alias somehow, currently you can only see the slug, but we use the alias to make requests.

I'm +1 on something like

{
  "child": <project object>,
  "alias": "alias"
}

That can allow us to put more information if needed (like creation date). BTW, I don't think we are showing that information for normal projects currently.

[humitos]

Under /api/v3/projects/slug/subprojects/ we are showing Project details instead of ProjectRelationship details. Do you think we should change that as well?

Listing ProjectRelationship for this, will look like this:

// inside "results"
{
  "alias": "myalias",
  "child": "subproject-slug",
  "parent": "superproject-slug",
  "_links": {
    "parent": "", // URL to details endpoint
    "child": "", // URL to details endpoint
    "_self": "",
    // ... 
}

This way we don't loose the "discover-ability" of the API and we still can navigate over it. We will still have all the data needed (without too many details as a Project detail) without loosing functionality, I guess.

There is a similar case for translations (/api/v3/projects/slug/translations/). Although, it's implemented in a different way where there is no "relationship" object to track this, but a ForeignKey to the Project itself (under main_language_project).

I'm not convinced about what's the best solution here.

[humitos]

This way we don't loose the "discover-ability" of the API and we still can navigate over it. We will still have all the data needed (without too many details as a Project detail) without loosing functionality, I guess.

Instead of showing just the slug for child and parent we could render the whole Project there, I think, and we will have the best of the two worlds: listing the relationships with all the details.

[stsewd]

Closed by https://github.com/readthedocs/readthedocs.org/pull/6176