URL (Semantic Module)

← Back to Modules Reference

The URL semantic module validates that incoming values are properly formed, absolute web links conforming to the WHATWG URL Standard.

Beyond simple format checking, the URL semantic module functions as a critical security shield against Server-Side Request Forgery (SSRF), credential leaks, and malicious URL schemes by restricting protocols, IP hostnames, explicit ports, and embedded authentication.

Technical Specifications

Attribute	Specification
Scope	`Property` (Applied to a text or string property)
Data Type	`String`
Parsing Standard	WHATWG URL Standard
Default Protocols	`http:` and `https:` (`https:` only when `requireHttps` is enabled)
Credential Protection	Rejects embedded credentials (`user:pass@host`) by default

Key Capabilities & Security Fencing

1. Absolute URL Validation

Every submitted value is parsed using the standard WHATWG URL parser. Relative paths (such as /about or profile/link), malformed syntax, and non-web protocols (like javascript:, data:, or ftp:) are strictly rejected.

2. HTTPS Protocol Enforcement (`requireHttps`)

When building production SaaS or fintech backends, external webhook URLs, profile links, or business websites should always be encrypted:

When requireHttps: true is set, any URL starting with unencrypted http:// is blocked with a validation error.
By default, both standard http:// and https:// are permitted.

3. SSRF & Internal Network Protection (`allowIP` & `allowPort`)

If your backend or background workers fetch user-submitted URLs, attackers may try to submit internal IP addresses (such as http://169.254.169.254 or http://192.168.1.1:8080) to access cloud metadata services or internal databases.

IP Fencing (allowIP: false): Rejects raw IPv4 and IPv6 addresses as hostnames.
Port Fencing (allowPort: false): Blocks URLs specifying custom ports (such as :8080, :3000, or :22), permitting only standard web ports.

4. Credential Leakage Prevention (`allowAuthentication`)

URLs can accidentally expose sensitive API keys or passwords if entered as https://admin:secret123@api.example.com. By default (allowAuthentication: false), API Now automatically blocks any URL containing embedded usernames or passwords.

5. Query String & Fragment Fencing

allowQueryParams: false: Rejects URLs containing query parameters (e.g. ?ref=affiliate), ensuring only clean domain or path endpoints are stored.
allowFragments: false: Rejects URLs containing anchor hashes (e.g. #section-2).

Configuration Options

When configuring the URL semantic in the Domain Modeler, you can customize the following security parameters:

Option	Type	Default	Description
`requireHttps`	`boolean`	`false`	Enforces that the URL must use the secure `https:` protocol.
`allowAuthentication`	`boolean`	`false`	Forbids embedded credentials (`user:pass@host`) to prevent security leaks.
`allowIP`	`boolean`	`true`	When `false`, blocks raw IP addresses (e.g., `http://192.168.1.1`) to prevent SSRF.
`allowPort`	`boolean`	`true`	When `false`, forbids custom ports (e.g., `:8080`).
`allowQueryParams`	`boolean`	`true`	When `false`, rejects URLs containing search query parameters (`?key=value`).
`allowFragments`	`boolean`	`true`	When `false`, rejects URLs containing anchor fragments (`#heading`).
`allowInternational`	`boolean`	`true`	When `false`, blocks Internationalized Domain Names (IDN) and Punycode (`xn--...`).

API Lifecycle Examples

1. Successful Web Link Submission

A client creates a profile with a secure website URL:

POST /companies
Content-Type: application/json

{
  "name": "Acme Corp",
  "website": "https://www.acme.com/about"
}

Server Response (201 Created):

{
  "data": {
    "id": "comp_101",
    "name": "Acme Corp",
    "website": "https://www.acme.com/about"
  }
}

2. Validation Failure (HTTPS Required)

If requireHttps: true is configured and the client submits an unencrypted http:// link:

Server Response (422 Unprocessable Entity):

{
  "type": "https://docs.apinow.app/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "code": "E_VALIDATION_ERROR",
  "detail": "The field 'website' must use the HTTPS protocol."
}

3. Security Rejection (Embedded Credentials)

If an input contains embedded authentication credentials:

{
  "website": "https://admin:supersecret@example.com"
}