From 07a081f9395c4ec352785954b27d7e4a33cc9b58 Mon Sep 17 00:00:00 2001
From: Kristi Nikolla <kristi@nikolla.me>
Date: Thu, 17 Aug 2023 11:06:21 -0400
Subject: [PATCH] Add openapi.yaml and update README

Provided a minimum of documentation to reduce knowledge debt
and technical debt.
---
 README.md    | 28 +++++++++++++++++++++--
 openapi.yaml | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 89 insertions(+), 2 deletions(-)
 create mode 100644 openapi.yaml

diff --git a/README.md b/README.md
index a6bc5c1..e7e00ee 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,26 @@
-# coldfront-plugin-api
-Simple REST API for ColdFront
+# Coldfront API Plugin
+REST API plugin for ColdFront.
+
+See `openapi.yaml` for OpenAPI specification.
+
+ColdFront doesn't currently provide a mechanism for allowing out of tree
+plugins to expose URLs, so applying the patch file at
+`patches/01_add_api_urls.patch` is required.
+
+The plugin can be enabled by adding `coldfront_plugin_api` to `ENABLED_APPS`
+in the Django `local_settings.py`.
+
+If the environment variable `PLUGIN_AUTH_OIDC` is detected, authentication
+will be done through `mozilla-django-oidc`, using the same configuration
+as the rest of ColdFront.
+
+**Note**: If using service accounts and Keycloak, it is necessary to add
+`openid` to the client scope of the service account performing the API
+request.  This step is because  the `mozilla-django-oidc` Django Rest
+Framework implementation uses the `userinfo` endpoint to validate tokens and
+that endpoint [requires] `openid` scope. If you're receiving a 403 Forbidden
+and wondering why, that might be the cause. For more information, see
+[client scope documentation].
+
+[requires]: https://github.com/keycloak/keycloak/pull/14237
+[client scope documentation]: https://access.redhat.com/documentation/en-us/red_hat_single_sign-on_continuous_delivery/2/html/server_administration_guide/clients#client_scopes
diff --git a/openapi.yaml b/openapi.yaml
new file mode 100644
index 0000000..97cf8da
--- /dev/null
+++ b/openapi.yaml
@@ -0,0 +1,63 @@
+openapi: 3.0.3
+info:
+  title: ColdFront API
+  description: ColdFront API
+  version: 0.1.0
+components:
+  schemas:
+    Project:
+      type: object
+      properties:
+        description:
+          type: string
+        id:
+          type: integer
+        field_of_science:
+          type: string
+        pi:
+          type: string
+        title:
+          type: string
+        status:
+          type: string
+    Allocation:
+      type: object
+      properties:
+        description:
+          type: string
+        id:
+          type: integer
+        resource:
+          type: object
+          properties:
+            name:
+              type: string
+            resource_type:
+              type: string
+        status:
+          type: string
+        project:
+          $ref: '#/components/schemas/Project'
+        attributes:
+          type: object
+          description: JSON Dictionary of all visible attributes.
+paths:
+  /api/allocations:
+    get:
+      description: Returns all active Resource Allocations.
+      responses:
+        '200':
+          description: A list of allocations.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Allocation'
+      parameters:
+        - name: all
+          in: query
+          description: Whether to include all Resource Allocations regardless of status.
+          required: false
+          schema:
+            type: boolean