Document email template and system config variable endpoints

Part 2 of 3 for DSpace/dspace-angular#5828: REST contract for
/api/system/emailtemplates (ETag concurrency, 304/412/428, 400
validation) and /api/system/systemconfigvariables (allowed config
discovery, decoupled from template payloads).

Author: MoamenElbarqy

PULL_REQUEST.md

@@ -0,0 +1,34 @@
+## References
+
+* Related to [DSpace/dspace-angular#5828](https://github.com/DSpace/dspace-angular/issues/5828)
+* Backend implementation: [DSpace/DSpace](https://github.com/DSpace/DSpace) (Branch: `feature/admin-email-templates`)
+* **Coordinated 3-Repository Feature (Part 2 of 3)**:
+  * **Part 1 (Backend REST API & Services)**: `DSpace/DSpace`
+  * **Part 2 (This PR - REST Contract Documentation)**: `DSpace/RestContract`
+  * **Part 3 (Coming soon - Angular Admin UI & Management)**: `DSpace/dspace-angular` (Branch: `feature/admin-email-templates`)
+
+---
+
+## Description
+
+Documents the two new admin-only endpoints for email template management:
+
+* `/api/system/emailtemplates` (list, retrieve with `ETag`/`If-None-Match` → 304, update with `If-Match` → 428/412, wildcard `*` force-overwrite, 400 on VTL/XSS/length violations).
+* `/api/system/systemconfigvariables` (list + retrieve single allowed config variable: `key`, `value`, `placeholder`).
+
+Key contract decision: configuration variables are **not** embedded in template payloads — clients fetch them once from the dedicated endpoint instead of receiving the identical list duplicated in every template.
+
+---
+
+## List of Changes in this PR
+
+* `emailtemplates.md`: fixed stale draft — removed `configVariables`/`allowedConfigs` from the example response and properties (decoupled per backend), documented field constraints (name pattern, content 10–50000, subject max 500, variable description max 500, placeholder max 30), kept ETag concurrency section.
+* `systemconfigvariables.md` (new): list + retrieve-single contract with example payloads, field constraints (key pattern, value max 2000, placeholder max 255), and status codes (200/401/403/404).
+* `endpoints.md`: linked both pages.
+
+---
+
+## Checklist
+
+* [x] My PR is created against the `main` branch of code.
+* [x] My documentation matches the backend implementation (`feature/admin-email-templates`: endpoint paths, `systemconfigvariable` type name, status codes, validation limits).

emailtemplates.md

@@ -0,0 +1,119 @@
+# Email Templates
+
+[Back to the list of all defined endpoints](endpoints.md)
+
+This endpoint exposes DSpace email templates to administrators, allowing them to view and edit email templates stored in `{dspace.dir}/config/emails/`.
+
+Only administrators are allowed to access and edit these templates.
+Templates cannot be created or deleted via the REST API because they correspond to hardcoded templates in the DSpace backend.
+
+System configuration variables usable inside templates (e.g. `${config.get('dspace.name')}`) are deliberately **not** embedded in template payloads. They are exposed via the dedicated [/api/system/systemconfigvariables](systemconfigvariables.md) endpoint.
+
+## Optimistic Concurrency Control
+
+To prevent concurrent administrators from overwriting each other's changes, this endpoint implements optimistic concurrency control via HTTP conditional headers:
+
+* **ETag Header**: Every `GET` and successful `PUT` response includes an `ETag` response header containing a SHA-256 hash of the template content (e.g., `ETag: "6a8f1b2c3d..."`).
+* **If-None-Match**: When retrieving a template with `GET`, clients may provide the `If-None-Match` header. If the template has not changed, the server responds with **304 Not Modified**.
+* **If-Match Required on PUT**: Every `PUT` request **must** provide the `If-Match` request header matching the current ETag (or `*` for unconditional overwrite).
+  * If `If-Match` is missing, the server responds with **428 Precondition Required**.
+  * If `If-Match` does not match the current template version, the server responds with **412 Precondition Failed**.
+
+---
+
+## Retrieve all email templates
+
+GET `/api/system/emailtemplates`
+
+Returns a list of all email templates, ordered alphabetically by name.
+
+### Status Codes for Retrieve All
+
+* 200 OK - if the operation succeeded
+* 401 Unauthorized - if not logged in
+* 403 Forbidden - if logged in as a non-admin user
+
+---
+
+## Retrieve a specific email template
+
+GET `/api/system/emailtemplates/<:template-name>`
+
+Returns a single email template by its filename identifier (e.g., `register`, `feedback`).
+
+### Example Response
+
+```json
+{
+  "name": "register",
+  "content": "## E-mail sent to DSpace users when they register for an account\n##\n## Parameters: {0} is expanded to a special registration URL\n##\n#set($subject = \"${config.get('dspace.name')} Account Registration\")\nTo complete registration, click: ${params[0]}\n",
+  "subject": "${config.get('dspace.name')} Account Registration",
+  "mimetype": "text/plain",
+  "variables": [
+    {
+      "index": 0,
+      "description": "is expanded to a special registration URL",
+      "placeholder": "${params[0]}"
+    }
+  ],
+  "lastModified": "2026-09-05T12:00:00Z",
+  "etag": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+  "type": "emailtemplate",
+  "_links": {
+    "self": {
+      "href": "http://localhost:8080/server/api/system/emailtemplates/register"
+    }
+  }
+}
+```
+
+### Template Properties
+
+* **name**: Unique template identifier matching filename. Pattern `^[a-zA-Z0-9._-]+$`, max 255 chars.
+* **subject**: Extracted subject line from `#set($subject = ...)` directive, max 500 chars.
+* **mimetype**: Enum indicating the content type. Possible values:
+  * `"text/plain"`: Standard plain text email (default).
+  * `"text/html"`: HTML-formatted email, detected when the template specifies `#set($mimetype = "text/html")` (supported via [DSpace PR #11755](https://github.com/DSpace/DSpace/pull/11755)).
+* **content**: Raw VTL template body, 10 to 50,000 chars.
+* **variables**: Array of parsed parameter variables (`index`, `description` max 500 chars, `placeholder` max 30 chars e.g. `${params[0]}`).
+* **lastModified**: ISO-8601 timestamp of when the file was last modified on disk.
+* **etag**: Deterministic SHA-256 hash of the template content for concurrency control.
+
+### Status Codes for Retrieve Specific
+
+* 200 OK - if the operation succeeded
+* 304 Not Modified - if `If-None-Match` matches current ETag
+* 401 Unauthorized - if not logged in
+* 403 Forbidden - if logged in as a non-admin user
+* 404 Not Found - if no template exists with the specified name
+
+---
+
+## Update an email template
+
+PUT `/api/system/emailtemplates/<:template-name>`
+
+Replaces the full content of the email template. The template content is validated against Velocity (VTL) syntax rules, XSS sanitization (OWASP), and size constraints (10 to 50,000 characters).
+
+### Required Request Headers
+
+* `Content-Type: application/json`
+* `If-Match: "<current-etag>"` (or `*`)
+
+### Example Request Body
+
+```json
+{
+  "content": "## E-mail sent to DSpace users when they register for an account\n##\n## Parameters: {0} is expanded to a special registration URL\n##\n#set($subject = \"${config.get('dspace.name')} Account Registration\")\nTo complete registration, please visit: ${params[0]}\n"
+}
+```
+
+### Status Codes for Update
+
+* 200 OK - if the template was successfully updated (returns updated template and new `ETag` header)
+* 400 Bad Request - if the content fails validation (invalid VTL syntax, XSS script tags, or length < 10 or > 50,000 chars)
+* 401 Unauthorized - if not logged in
+* 403 Forbidden - if logged in as a non-admin user
+* 404 Not Found - if no template exists with the specified name
+* 412 Precondition Failed - if the `If-Match` ETag is stale or does not match
+* 428 Precondition Required - if the `If-Match` header was omitted

endpoints.md

@@ -41,6 +41,8 @@
 * [/api/submission/vocabularyEntryDetails](vocabularyEntryDetails.md)
 * [/api/system/auditevents](auditevents.md)
 * [/api/system/systemwidealerts](systemwidealerts.md)
+* [/api/system/emailtemplates](emailtemplates.md)
+* [/api/system/systemconfigvariables](systemconfigvariables.md)
 * [/api/versioning/versions](versions.md)
 * [/api/versioning/versionhistories](versionhistories.md)
 * [/api/workflow/workflowitems](workflowitems.md)

systemconfigvariables.md

@@ -0,0 +1,83 @@
+# System Config Variables
+
+[Back to the list of all defined endpoints](endpoints.md)
+
+This endpoint exposes the general repository configuration variables that administrators may reference inside email templates (e.g. `${config.get('dspace.name')}`).
+
+It returns the subset of configuration properties allowed in templates, as defined by `message.templates.allowed-config` (resolved via `Utils.getAllowedTemplateConfig()`, matching `Email.java` and `LDN.java`).
+
+Only administrators are allowed to access these variables. They are exposed here — decoupled from the [/api/system/emailtemplates](emailtemplates.md) payloads — so clients fetch the identical list once instead of receiving it duplicated inside every template.
+
+---
+
+## Retrieve all system config variables
+
+GET `/api/system/systemconfigvariables`
+
+Returns a list of all allowed system configuration variables, ordered alphabetically by key.
+
+### Example Response (paginated, HAL-embedded)
+
+```json
+{
+  "_embedded": {
+    "systemconfigvariables": [
+      {
+        "key": "dspace.name",
+        "value": "DSpace at My University",
+        "placeholder": "${config.get('dspace.name')}",
+        "type": "systemconfigvariable"
+      },
+      {
+        "key": "dspace.ui.url",
+        "value": "http://localhost:4000",
+        "placeholder": "${config.get('dspace.ui.url')}",
+        "type": "systemconfigvariable"
+      }
+    ]
+  }
+}
+```
+
+### Variable Properties
+
+* **key**: Configuration property key (e.g. `dspace.name`). Pattern `^[a-zA-Z0-9._-]+$`, max 255 chars.
+* **value**: Resolved value of the configuration property, max 2000 chars.
+* **placeholder**: Velocity expression to insert into a template (e.g. `${config.get('dspace.name')}`), max 255 chars.
+
+### Status Codes for Retrieve All
+
+* 200 OK - if the operation succeeded
+* 401 Unauthorized - if not logged in
+* 403 Forbidden - if logged in as a non-admin user
+
+---
+
+## Retrieve a specific system config variable
+
+GET `/api/system/systemconfigvariables/<:property-key>`
+
+Returns a single configuration variable by its property key (e.g., `dspace.name`).
+
+### Example Response
+
+```json
+{
+  "key": "dspace.name",
+  "value": "DSpace at My University",
+  "placeholder": "${config.get('dspace.name')}",
+  "type": "systemconfigvariable",
+  "_links": {
+    "self": {
+      "href": "http://localhost:8080/server/api/system/systemconfigvariables/dspace.name"
+    }
+  }
+}
+```
+
+### Status Codes for Retrieve Specific
+
+* 200 OK - if the operation succeeded
+* 401 Unauthorized - if not logged in
+* 403 Forbidden - if logged in as a non-admin user
+* 404 Not Found - if no allowed variable exists with the specified key