# API V4

See the API spec here: https://petstore.swagger.io/?url=https://raw.githubusercontent.com/newswangerd/galaxy-api-v4/master/openapi%3A%20galaxy_ng_v4.yml#/

Contribute changes here: https://github.com/newswangerd/galaxy-api-v4

## Design Principles
- Data types are backwards compatible with version 3, to prevent any major client rewrites. This is a meant to mostly be a reorganization and recombination of our current v3 and \_ui apis.
- API roots are navigable. Example:

GET /api/v4/plugins/

{
    "sub_routes": [
        {
            "url": "/api/v4/plugins/ansible",
            "status": "production"
        },
        {
            "url": "/api/v4/plugins/execution-environments",
            "status": "tech_preview"
        }
    ]
}

- Summaries of related objects can be selected and embedded in api responses via API query parameters. Example:

GET /api/v4/plugin/ansible/namespaces/my_namespace/?include_related=my_permissions

{
    "name": "my_namespace"
    "related_fields": {
        "my_permissions": [
            "ansible.update_namespace"
        ]
    }
    [...]
}

- Extensible support for multiple content types such as collections, execution environments and potentially roles.
- Support multiple repositories. V3 had to be scoped to a single pulp ansible repository. V4 will allow clients to retrieve content from any repository via a single base url.
- Improved queryability. All fields that are returned by the API should be queryable using django filters such as `__startswith`, `__contains` `__icontains`, `__lte`, and `__gte`
- This will include any fields that can be included in `include_related`, but not related objects ommitted from `include_related`

## Changes from v3 and \_ui
Most APIs are identical to those found in the current v3 and \_ui endpoints. The biggest changes are updates to the routing in order to support multiple content types and repositories.

### ansible-galaxy CLI Considerations

The data types that the galaxy client uses from V3 are unchanged, however the routing has been updated and uploading/downloading content requires the user to specify a base path for a distribution they wish to interact with. Because of this, a new flag for selecting repo will have to be added to the ansible-galaxy client. The API will provide a default distribution at the [/configuration](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/newswangerd/galaxy-api-v4/master/openapi%3A%20galaxy_ng_v4.yml#/App%20Configuration/get-configuration) endpoint that clients can read if users don't specify which repository they wish to use.

Because different repos are no long treated as different API servers, users will only have to configure the URL for automation hub once.

The new collection search endpoints will also allow the CLI to lookup collections by content name and find which distributions a collection is in.

### Pulp Ansible Sync Considerations
When syncing from v4 of the api, a remotes will have to be configured witha base path to pull content from, since that information is no longer encapsulated in the URL.

### Tower Considerations
Tower will have to be updated to accept a distrbution base path as well.

### New APIs

#### Collection version search
[API Spec](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/newswangerd/galaxy-api-v4/master/openapi%3A%20galaxy_ng_v4.yml#/Pulp%20Ansible/get-plugin-ansible-search-collection-versions)

This API allows searching all collection versions in hub across all repositories. It would replace the current functionality `_ui/v1/repo/{base_path}` and `_ui/v1/collection-versions` endpoints by providing a flag to return all collection versions or just the latest version in each collection.

This endpoint addresses a couple of important problems in galaxy_ng.
- Repository discovery: provides a mechnisim to find what repositories a collection is in
- Content discovery: provides a way to search which collections have a specific piece of content (such as a role or a module)
- UX Issues: right now, all collection views in the UI have to be scoped to a single repository and it's an awful user experience.

The following related fields can be includeded:
- `namespace`: includes summary of the namespace the version is in
- `metadata`: includes the collection version metadata
- `distributions`: includes a list of the distributions that content is in.

By default this endpoint will only search content that are in distributions that are labelled with `content=public`. Other sets of distributions can be queried using `?distribution_labels=<label>` and a specific repository can be selected using `?distribution=<base_path>`.

#### Configuration

[API Spec](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/newswangerd/galaxy-api-v4/master/openapi%3A%20galaxy_ng_v4.yml#/App%20Configuration/get-configuration)

Since the API requires a distribution base_path to publish and download content, this provides a way to configure a default upload/download repo that clients can read.

This also allows clients to look up if content type such as execution environments are supported on the service.

#### Object Permissions

[Example for collection namespaces](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/newswangerd/galaxy-api-v4/master/openapi%3A%20galaxy_ng_v4.yml#/Pulp%20Ansible/get-plugins-ansible-namespaces-name-users)

Rather than embedd updating permissions for objects into the object itself, like the old v3 and \_ui apis, object level permissions will be set using `<object_url>/groups` and `<object_url>/users.` These two viewsets will accept PUT operations for setting and updating a list of permissions on the given object and a DELETE operation for removing a list of permissions from a given object.

### Changed APIs

#### Namespaces

Container and collection namespaces no longer have the `groups` property. Getting and setting group ownership will be done through the object permissions apis.

## Implementation

All of the endpoints listed in the API spec will be implemented in pulp ansible with the exception of
- `/plugin/execution-environments` which will be fully implemented in galaxy_ng
- `/configuration` which will be reimplemented in galaxy_ng to provide execution environment settings.

Routes in pulp_ansible must be built so that they can be imported into galaxy_ng and provided via the galaxy_ng router without any subclassing. To accomodate this, authentication and permission classes for all v4 viewsets in pulp_ansible must be configurable globally so that galaxy_ng can bring it's own acces policies and and authentication for cloud.redhat.com and the ansible automation platform.

## V3
The original plan was to move V3 into pulp_ansible, but since we're developing V4 in pulp_ansible and V4 will supercede V3, I would like to propose freezing V3 and leaving it as is.

## Todo
- How to handle urls for collection remotes? Currently the URL tells pulp which repo to sync.
-