Foreman has built API v2 on apipie-rails. This was developed by Foreman developers in a world where OpenAPI didn't exist yet.

OpenAPI

These days OpenAPI is an industry standard and a lot of tooling exists around it. apipie-rails has some support for OpenAPI, but only version 1. These days apipie-rails is not well maintained and we bear much of the maintenance burden. It may be better to look at other API frameworks to see what we can use instead of adding OpenAPI v3 support to apipie-rails.

On a more technical level the design is also not very flexible. Resources are not easily identified. For example, on a host you may find:

{
  "id": 1,
  "name": "host.example.com",
  "organization_id": 1,
  "organization_name": "Example Org"
}

It's not easy to figure out the where to find the host resource itself. One example is the GitHub API which returns the URL and HTML URL to find the resources.

Then the organization should be an object as well that, again, can be easily found. A better structure would be:

{
  "id": 1,
  "name": "host.example.com",
  "url": "https://satellite.example.com/api/v3/hosts/1",
  "html_url": "https://satellite.com/hosts/1",
  "organization": {
    "id": 1,
    "name": "Example Org",
    "url": "https://satellite.example.com/api/v3/organizations/1",
    "html_url": "https://satellite.com/organizations/1"
  }
}

This allows the front end to easily add links to objects and get more information.

A consideration that should be taken is to use href or url. Some APIs don't include the full hostname in their responses but only the path.

Another consideration to be taken is integration. Today both Hammer and our Ansible collections use apipie to build a lot of the support. These should be updated to use OpenAPI if possible.

Authentication

The current API doesn't allow for limited scope API tokens. Adding this can benefit security, but also trust. Users of the MCP container may want to provide a read-only token to be sure AI doesn't make any changes.

A better mechanism for Smart Proxy authentication is also good to have. Especially if it can be somehow unified with the regular authentication, though that is not a hard requirement.