Save API Documentation

Overview

The Save API (running on port 3001 by default) serves as a proxy to fetch HTML content from a user-provided URL. It then forwards this HTML content to the Scan API for accessibility analysis.

Main Endpoint: POST /

This is the primary endpoint for the Save API. It fetches content from the specified URL and sends it for scanning.

Request

• Method: POST
• Content-Type: application/json
• Body:

  {
      "url": "string (The URL of the website to fetch and scan)"
  }

• URL Validation: The provided URL undergoes a two-step validation process on the server-side:
  1. Initial Format Check: A regular expression performs a basic check on the URL structure. If this fails, an error (see the second example in the table below) is returned.
  2. Advanced Parsing and Normalization:
     • If no protocol (http:// or https://) is present, https:// is prepended to the URL.
     • The (potentially modified) URL is then parsed using the standard URL constructor. This step ensures the URL has a valid hostname and that the protocol is either http or https.
     • The fully validated and normalized URL from this step is used for fetching. If this advanced parsing fails, an error (see the third example in the table below) is returned.

Responses

Success

If the URL is fetched successfully and the Scan API processes the content, this endpoint will forward the JSON response directly from the Scan API. The HTTP status code will also match the Scan API's response status.

Refer to the Scan API Documentation for the structure of a successful scan result.

Error Responses

{
    "success": false,
    "message": "URL is required in the request body."
}

{
    "success": false,
    "message": "Invalid URL format. Please provide a valid URL (e.g., example.com, http(s)://example.com)."
}

{
    "success": false,
    "message": "Invalid URL: [Details from parser, e.g., 'Hostname is missing.' or 'Invalid protocol: foo:']. Please ensure the URL is correctly formatted and uses http or https."
}

// Generic message format:
{
    "success": false,
    "message": "Failed to fetch URL [urlToSave]. Status: [status] [statusText]."
}

{
    "success": false,
    "message": "Scan service failed. Detail: [detailMessageFromScanAPI]"
}

{
    "success": false,
    "message": "Error processing [urlToSave]: [errorMessage]"
}

Status Endpoint: GET /status

Provides the operational status of the Save API.

Request

• Method: GET

Response (Success 200 OK)

{
    "status": "active",
    "service": "save-api",
    "timestamp": "ISO_Date_String (e.g., 2023-10-27T10:00:00.000Z)"
}

Internal Configuration Endpoint: POST /set-internal-scan-mode

This endpoint is primarily for internal/development use. It allows dynamic configuration of the internal Scan API service URL that this Save API instance will communicate with.

Request

• Method: POST
• Query Parameter: target
  • local: Configures the Save API to use a local Scan API (e.g., http://localhost:3002).
  • server: Configures the Save API to use the production/server Scan API (e.g., https://accessscan.sumfall.gay/api/scan).
• Example URL: /set-internal-scan-mode?target=local
• Content-Type: application/json
• Request Body: An empty JSON object ({}) should be sent. The server does not currently process this body content.

Responses

Success (200 OK)

When target is local:

{
    "success": true,
    "message": "Save service scan target set to local."
}

When target is server:

{
    "success": true,
    "message": "Save service scan target set to server."
}

Error (400 Bad Request)

If the target parameter is invalid or missing:

{
    "success": false,
    "message": "Invalid target parameter. Use \"local\" or \"server\"."
}