Design documents for Quadlet API Endpoints

contrib/design-docs/quadlet_api/Quadlet REST API Endpoints.md

@@ -0,0 +1,77 @@
+# Change Request
+
+Last Update: Oct 6, 2025
+
+## **Short Summary**
+
+The aim is to offer a collection of API endpoints for managing quadlets on a remote Podman API server.
+
+## **Objective**
+
+This document proposes the design of new API endpoints for managing quadlets remotely via a Podman API server. The aim is to establish a secure and robust interface for the full lifecycle management of quadlets (creation, retrieval, updating, and deletion), facilitating efficient remote administration. This feature should be implemented without requiring compatibility handlers or introducing breaking changes to existing Podman APIs.
+
+## **Use case**
+
+The design outlines a robust and complete RESTful API interface for the existing Podman API service that allows a client to maintain a quadlet and associated unit files. This interface will empower both rootful and rootless users to create, configure, and control Podman quadlets.The API is stateless, rather it queries the disk and systemd to report state.
+
+### Challenges
+
+1. Where should the unit files be written?
+   1. XDG_CONFIG_HOME is not currently always available
+   2. Need to research if HOME is set when SocketActivated()
+   3. What is the server environment for the new TLS endpoint?
+2. How to safely and securely invoke systemd reloads or other operations from API service.
+   1. Response bodies currently return loaded and active status. This may not be possible. If not, then we may use the libpod status of the podman container generated from the system unit files, filtering on the label PODMAN_SYSTEMD_UNIT and the quadlet name.
+3. Ensure environments exposed from API service are secure and as expected for containers driven by quadlets.
+4. Should these API operations publish podman events?
+   1. The handler should publish events to the podman event system, stating what unit operations are being performed on which Unit files.
+5. When reading an application/octet-stream from a POST method, should the contents be staged on the server or streamed directly to the destination file?
+   1. The intended use of \`enabled\` in post was to flag the need to create or delete a drop-in file for the unit with an \`\[Install\]\` stanza. If we allow clients to post an opaque file they could include an \`\[Install\]\` stanza themselves. This would lead to the situation where the API could be asked to disable a quadlet and it does not.
+      This is not reported as an error as operations should be idempotent.
+
+## **Target Podman Release**
+
+5.Y+ (with no breaking changes we can release on any Y branch)
+
+## **Jira/Github Link**
+
+TBD
+[\[containers/podman\] Provide a remote API for inactive quadlets](https://issues.redhat.com/browse/RUN-3585)
+[Remote API for all Quadlet operations](https://issues.redhat.com/browse/RUN-3574)
+
+## **Stakeholder**
+
+TBD
+Podman Desktop
+
+## **Impacts**
+
+### **CLI**
+
+There will be no changes to the CLI.
+
+### **Libpod**
+
+All modifications will be confined to `pkg/api`, where the API service is implemented. Developer documentation will be required and, for the time being, will be based on the existing Swagger implementation.
+
+### **Others**
+
+1. The python and golang bindings will need to be updated to include the new RESTful endpoints.
+2. Quadlet unit types are handled through individual, separate operations. This approach is necessary because these operations modify files on the remote system, and most filesystems do not support atomic operations. However, a single operation is available for inspecting all components of a quadlet.
+
+### **Detailed Description:**
+
+Each POST/PUT endpoint accepts a JSON payload. This payload is processed by a golang template to render the required Unit file. Fields intended for rendering in the Unit file begin with an uppercase letter, while fields acting as flags or markers for the server begin with a lowercase letter.
+
+Quadlet endpoints defined in [quadlet.yaml](https://drive.google.com/file/d/1LO0NNM8OGBFPhC5zPOXD9zNgbfQRI_o3/view?usp=sharing)
+
+This Swagger document was generated by AI (Cursor/Claude) from the Podman Quadlet man pages and subsequently reviewed by me. Discrepancies between the as-built implementation and the man pages will not be reflected.
+
+### **Future Considerations**
+
+- **Pagination:** Implement pagination for the "Get All Quadlets" endpoint to handle a large number of quadlets efficiently.
+- **Filtering and Sorting:** Add query parameters for filtering and sorting quadlets based on various attributes.
+
+## **Test Descriptions (Optional):**
+
+Description of how the new feature should be tested