feat: add sandbox audit API endpoint #1122

Kanishkavijay39 · 2025-08-07T10:23:55Z

Overview
This PR introduces a new REST API endpoint that allows partners to trigger audits on sandbox sites without requiring Slack SpaceCat access. The endpoint provides a simple, programmatic way to initiate audits for sandbox environments.

Wiki: https://wiki.corp.adobe.com/display/AEMSites/AEM+Sites+Optimizer+-+Sandbox+Backend+APIs
Changes
New API Endpoint
Route: GET /sandbox/audit
Purpose: Trigger audits on sandbox sites programmatically
Key Features
✅ Single audit trigger: GET /sandbox/audit?baseURL=https://sandbox.example.com&auditType=meta-tags,alt-text
✅ Multiple audit trigger: GET /sandbox/audit?baseURL=https://sandbox.example.com (triggers all enabled audits)
✅ Sandbox validation: Only works with sites marked as isSandbox: true
✅ Comprehensive error handling: Validates URLs, audit types, site existence, and sandbox status
✅ Added rate limiting : fetch last audit run and did time diff by default kept it 4 hrs have created env. variable as well so we can update it if needed.

Supported Audit Types
meta-tags - Validate meta tags and SEO elements
alt-text - Check for missing alt text in images

Testing done on local

- Add GET /sandbox/audit endpoint for partners to trigger audits on sandbox sites - Support single audit type or trigger all enabled audits - Validate that only sandbox sites can use this endpoint - Add comprehensive test coverage (17 test cases) - Include complete OpenAPI documentation with examples - Update route handlers and main application integration Resolves need for partners to trigger audits without Slack access

- Fixed sandbox validation in sandbox-audit controller - Changed from site.isSandbox (undefined) to site.getIsSandbox() (boolean) - Updated test mocks to use getIsSandbox() method instead of isSandbox property - Removed debug logging after issue was resolved - All sandbox audit tests now passing (1190 passing)

github-actions · 2025-08-07T11:34:35Z

This PR will trigger a minor release when merged.

absarasw · 2025-08-08T05:21:05Z

src/controllers/sandbox-audit.js

+import { badRequest, notFound, ok } from '@adobe/spacecat-shared-http-utils';
+import { sendAuditMessage } from '../support/utils.js';
+
+const ALL_AUDITS = [


Can we take this from site config?

As discussed, will create a follow up task will add configuration object for sandbox audits.
have to add the audit-types array to spacecat-shared-data-access configuration.

absarasw · 2025-08-08T05:27:53Z

src/controllers/sandbox-audit.js

+const triggerAuditForSiteAPI = async (site, auditType, context) => sendAuditMessage(
+  context.sqs,
+  context.env.AUDIT_JOBS_QUEUE_URL,
+  auditType,


Can you make it a list?

- Remove scoped_api_key authentication option - Keep only ims_key for better security and user identification - Aligns with other administrative endpoint patterns

…cat-api-service into SITES-sandbox-audit-api

…essed, update docs & tests

…rage

…tests

…ing logic * Added normalizeAuditTypes and enforceRateLimit helpers * Consolidated triggerAllEnabledAudits & triggerSpecificAudits into triggerAudits * Updated controller to use helpers and env-configurable SANDBOX_AUDIT_RATE_LIMIT_HOURS * Extended tests and docs; maintains 100% coverage

…-limit info

…udit-service.js – removed redundant eslint suppression • src/controllers/sandbox-audit.js – add c8 ignore for minutes/hours branch • tests – added over/under-hour cases + helper test → 100 % branch & line coverage • docs/openapi/sandbox-audit-api.yaml + docs/index.html – document auditsSkipped, nextAllowedIn, skippedDetail • .vscode/launch.json – optional VS Code debug profile

habansal · 2025-08-18T03:13:21Z

docs/openapi/sandbox-audit-api.yaml

+      **Restrictions:**
+      - Only works with sandbox sites (sites with `isSandbox: true`)
+      - Audits are rate-limited (default **4 hours** between runs for the same site/audit type). If the
+        limit is hit the endpoint responds with HTTP 400 and an explanatory message.


How about using 429?

habansal · 2025-08-18T03:14:25Z

docs/openapi/sandbox-audit-api.yaml

@@ -0,0 +1,176 @@
+sandbox-audit:
+  get:


Why using GET for something that modifies state?

Backend already prevents re-runs in x h, so it felt idempotent, but you’re right it does create state. I’ll update it to POST.
Updated

habansal · 2025-08-18T03:25:31Z

README.md

+entirely.
+
+```plaintext
+SANDBOX_AUDIT_RATE_LIMIT_HOURS=24


ack, I’ll recheck and will make it consistent.
done

habansal · 2025-08-18T03:26:25Z

README.md

@@ -102,6 +102,16 @@ SLACK_TOKEN_WORKSPACE_EXTERNAL_ELEVATED=Slack token for the external workspace,
 SLACK_OPS_CHANNEL_WORKSPACE_EXTERNAL=channel ID to use for operations messages in the external workspace
 ```

+Sandbox audit rate-limit (optional):
+
+Minimum hours that must elapse before the same audit can run again for the same site. 


Should the rate limit be like x audit triggers per y hours?

Yes, we can enhance it this way. I will add in configuration site level for sandbox for audit types and in that audit i will set rate limit time as well.
Will modify.

habansal · 2025-08-18T03:28:39Z

docs/openapi/sandbox-audit-api.yaml

+          The audit type(s) to trigger. Accepts:
+          • a single value (e.g. `meta-tags`)
+          • a comma-separated list (e.g. `meta-tags,alt-text`)
+          If omitted, all enabled audits are triggered.


enabled and supported for sandboxes, you mean, right?

Yes, enabled and supported.

habansal · 2025-08-18T03:33:50Z

docs/openapi/sandbox-audit-api.yaml

+      - `meta-tags`: Validate meta tags and SEO elements  
+      - `alt-text`: Check for missing alt text in images
+    parameters:
+      - name: baseURL


Whh baseurl and not siteId?
As part of API route instead of query param?

siteId is an internal primary key, exposing it is unnecessary for partners. but many apis do add site id as path variable i will also update.
Done.

habansal · 2025-08-18T03:37:54Z

README.md

+```plaintext
+SANDBOX_AUDIT_RATE_LIMIT_HOURS=24
+```
+


How will UI know if triggered audit failed or succeeded?

since triggering audit is async, we can't provide audit details in this api.
rather ui can call get latest audits and see the status.
https://opensource.adobe.com/spacecat-api-service/#tag/import/operation/getImportJobStatus
Or i can provide job id with specific audit.

habansal · 2025-08-18T03:39:39Z

docs/openapi/sandbox-audit-api.yaml

+      partners who need to trigger audits programmatically on sandbox environments only.
+
+      **Behavior:**
+      - If `auditType` is specified: triggers that specific audit type


What happens if the audit is disabled?

Will give proper 400, detailed error with all the audits which are enabled.

…ve rate-limit handling • Route now uses siteId path parameter (avoids baseURL query) • Response when rate limit hit is 429 (Too Many Requests) • Default limit clarified as 4 h via SANDBOX_AUDIT_RATE_LIMIT_HOURS env var • Updated OpenAPI docs and README • Removed unused import warning

- Updated all test cases to use siteId path parameter instead of baseURL query parameter - Fixed mock Site objects to include getBaseURL() method - Updated rate limit test expectations to use 429 status code - Fixed linter errors (trailing spaces) - Updated route tests to include new dynamic route - All sandbox audit tests now pass

…auditType

- Resolved conflicts in routes configuration - Added LLMO customer-intent routes alongside sandbox audit route - Updated test expectations to include both features - Used main branch version of generated docs/index.html

Kanishkavijay39 requested a review from absarasw August 7, 2025 10:24

absarasw reviewed Aug 8, 2025

View reviewed changes

absarasw requested a review from solaris007 August 8, 2025 05:25

absarasw reviewed Aug 8, 2025

View reviewed changes

Kanishkavijay39 and others added 9 commits August 8, 2025 12:54

Merge branch 'main' into SITES-sandbox-audit-api

8c0e70f

Restrict sandbox audit endpoint to IMS authentication only

e9ea35a

- Remove scoped_api_key authentication option - Keep only ims_key for better security and user identification - Aligns with other administrative endpoint patterns

Merge branch 'SITES-sandbox-audit-api' of github-personal:adobe/space…

cfaf3ef

…cat-api-service into SITES-sandbox-audit-api

feat(sandbox-audit): refactor controller/service,review comments addr…

f0628ed

…essed, update docs & tests

test(sandbox-audit): add failure-path logging test to reach 100% cove…

ab8f3e2

…rage

test(sandbox-audit): achieve 100% coverage with additional edge-case …

be4c86f

…tests

docs: regenerate HTML OpenAPI reference to include sandbox audit rate…

284dcb4

…-limit info

Kanishkavijay39 requested a review from absarasw August 15, 2025 18:35

habansal reviewed Aug 18, 2025

View reviewed changes

Kanishka added 2 commits August 18, 2025 17:28

Kanishkavijay39 requested a review from habansal August 18, 2025 13:46

Kanishka added 2 commits August 19, 2025 01:56

Fix sandbox audit API: use query parameters instead of body data for …

e0f0b45

…auditType

Merge main into SITES-sandbox-audit-api

7fe70e4

- Resolved conflicts in routes configuration - Added LLMO customer-intent routes alongside sandbox audit route - Updated test expectations to include both features - Used main branch version of generated docs/index.html

Kanishkavijay39 force-pushed the SITES-sandbox-audit-api branch from c3ddf88 to 7fe70e4 Compare August 21, 2025 18:35

Kanishkavijay39 force-pushed the SITES-sandbox-audit-api branch from 9b43ae4 to e7687aa Compare August 22, 2025 09:17

refactor: clean up sandbox audit code

5886a7d

Kanishkavijay39 force-pushed the SITES-sandbox-audit-api branch from e7687aa to 5886a7d Compare August 22, 2025 13:01

feat: add sandbox audit API endpoint #1122

Are you sure you want to change the base?

feat: add sandbox audit API endpoint #1122

Conversation

Kanishkavijay39 commented Aug 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Aug 7, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

absarasw Aug 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kanishkavijay39 Aug 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kanishkavijay39 Aug 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kanishkavijay39 Aug 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kanishkavijay39 Aug 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Kanishkavijay39 commented Aug 7, 2025 •

edited

Loading

absarasw Aug 8, 2025 •

edited

Loading

Kanishkavijay39 Aug 18, 2025 •

edited

Loading

Kanishkavijay39 Aug 18, 2025 •

edited

Loading

Kanishkavijay39 Aug 18, 2025 •

edited

Loading

Kanishkavijay39 Aug 18, 2025 •

edited

Loading