Need to construct URLs dynamically from individual components? This guide covers everything about building URLs via API, including URL structure, encoding rules, and implementation examples.
URL Structure
A complete URL consists of several components:
scheme://username:password@host:port/path?query#fragment
Example:
https://user:pass@example.com:8080/api/v1/users?page=1&limit=10#section- Scheme: Protocol (http, https, ftp)
- Authority: User info, host, and port
- Path: Resource location
- Query: Parameters after ?
- Fragment: Anchor after #
Why Use a URL Builder?
String concatenation for URLs is error-prone:
- Missing or double slashes
- Improper encoding of special characters
- Invalid query string format
- Missing scheme validation
A URL builder handles all these concerns automatically.
Tip: The API automatically encodes special characters and handles edge cases in path and query construction.
Using the URL Builder API
TinyFn provides a flexible endpoint for URL construction:
API Request
POST https://api.tinyfn.io/v1/url/build
Headers: X-API-Key: your-api-key
Content-Type: application/json
{
"scheme": "https",
"host": "api.example.com",
"port": 8080,
"path": "/v1/users",
"query": {
"page": "1",
"limit": "10",
"search": "john doe"
},
"fragment": "results"
}
Response
{
"url": "https://api.example.com:8080/v1/users?page=1&limit=10&search=john%20doe#results",
"components": {
"scheme": "https",
"host": "api.example.com",
"port": 8080,
"path": "/v1/users",
"query": "page=1&limit=10&search=john%20doe",
"fragment": "results"
}
}Parameters
| Parameter | Type | Description |
|---|---|---|
scheme |
string | URL scheme (default: "https") |
host |
string | Hostname or IP address (required) |
port |
integer | Port number (optional, omitted if default) |
path |
string|array | Path string or array of segments |
query |
object | Query parameters as key-value pairs |
fragment |
string | URL fragment/anchor |
username |
string | Basic auth username |
password |
string | Basic auth password |
Code Examples
JavaScript / Node.js
const response = await fetch(
'https://api.tinyfn.io/v1/url/build',
{
method: 'POST',
headers: {
'X-API-Key': 'your-api-key',
'Content-Type': 'application/json'
},
body: JSON.stringify({
scheme: 'https',
host: 'api.example.com',
path: '/users',
query: { page: '1', search: 'john doe' }
})
}
);
const { url } = await response.json();
console.log(url); // "https://api.example.com/users?page=1&search=john%20doe"Python
import requests
response = requests.post(
'https://api.tinyfn.io/v1/url/build',
headers={'X-API-Key': 'your-api-key'},
json={
'scheme': 'https',
'host': 'api.example.com',
'path': '/users',
'query': {'page': '1', 'search': 'john doe'}
}
)
url = response.json()['url']
print(url) # "https://api.example.com/users?page=1&search=john%20doe"cURL
curl -X POST "https://api.tinyfn.io/v1/url/build" \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"scheme": "https",
"host": "api.example.com",
"path": "/users",
"query": {"page": "1"}
}'Common Use Cases
- API Client Development: Build endpoint URLs with varying parameters
- Dynamic Redirects: Construct redirect URLs from user input
- OAuth Flows: Build authorization URLs with proper encoding
- Pagination Links: Generate next/previous page URLs
- Deep Links: Create app deep links with parameters
Best Practices
- Don't pre-encode: Let the API handle encoding
- Validate host: Ensure the host is from allowed domains
- Use HTTPS: Default to secure protocols
- Omit default ports: Don't include :80 or :443