To serve HTML and JSON files with exact paths on a tech support site, you must configure your web server to map specific URLs directly to their corresponding file locations without fallback logic or generic routing. This approach ensures that API endpoints return pure JSON data while documentation pages serve static HTML, improving both user experience and application reliability by preventing unintended content type mismatches or redirect loops.
Understanding Exact Path Routing
Exact path routing means that a URL like
/api/status serves only the JSON file located at
/var/www/html/api/status.json, and
/docs/intro serves only the HTML file at
/var/www/html/docs/intro.html. Unlike Single Page Applications (SPAs) that rely on a catch-all rule to route all traffic to
index.html, this method requires explicit configuration for each resource. This is particularly useful for tech support sites where distinct API responses and static help articles coexist on the same domain.
When implementing this, you avoid the common pitfall of serving an HTML page when a JSON response is expected, which can break JavaScript consumers. It also prevents the browser from caching dynamic API data as static HTML. The core principle is precision: every defined URL maps to exactly one physical file or directory index, with no ambiguity.
Configuring Nginx for Exact Paths
Nginx provides robust tools for mapping URIs to file system paths. To serve JSON and HTML correctly, you must ensure MIME types are handled appropriately so the browser interprets the content correctly.
First, verify that your
mime.types file is included in your main configuration. This ensures that
.json files are served with the correct
application/json header. Without this, browsers may treat JSON as plain text, causing parsing errors in client-side scripts.
Next, define your server block with specific location blocks. Avoid using a generic
location / { try_files $uri $uri/ /index.html; } rule, as this will intercept all requests and potentially serve HTML for JSON endpoints. Instead, use precise matches.
server {
listen 80;
server_name example.com;
root /var/www/html;
# Serve HTML files
location /docs/ {
try_files $uri $uri/ =404;
}
# Serve JSON files
location /api/ {
default_type application/json;
try_files $uri =404;
}
# Fallback for other assets
location /assets/ {
expires 30d;
add_header Cache-Control "public, immutable";
}
}
In this configuration,
/docs/intro.html is served via the first location block. The
try_files directive checks if the file exists; if not, it returns a 404 error rather than falling back to an index file. For the API, the
default_type directive forces the JSON MIME type, ensuring consistency even if the file extension is missing or ambiguous.
Configuring Apache for Exact Paths
Apache uses
.htaccess files or virtual host configurations to achieve similar results. The key is to disable directory indexing and prevent automatic fallbacks.
Use the
FilesMatch directive to handle JSON files specifically. This allows you to set headers and MIME types for specific file extensions.
# .htaccess in /var/www/html
# Disable directory browsing
Options -Indexes
# Handle JSON files
Header set Content-Type "application/json"
# Ensure no HTML fallback
RewriteEngine Off
# Handle HTML files explicitly if needed
RewriteRule ^docs/(.*)$ docs/$1.html [L]
The
Header set Content-Type command ensures that any file ending in
.json is delivered with the correct MIME type. By turning off
RewriteEngine within this block, you prevent any global rewrite rules from interfering with the direct file access. This is crucial for maintaining the integrity of API responses.
For HTML files, you can rely on Apache's default behavior of serving
index.html in directories, or use
RewriteRule to map clean URLs to specific HTML files. However, be cautious not to create circular redirects. Always test your configuration with
apachectl configtest before reloading the service.
Testing and Validation
After configuring your server, validate the setup using command-line tools. Use
curl to check the response headers and body.
curl -I http://example.com/api/status
curl -I http://example.com/docs/intro
The first command should return a
200 OK status with
Content-Type: application/json. The second should return
Content-Type: text/html. If you see
text/plain for JSON, revisit your MIME type configuration. If you see HTML for the API endpoint, check for overriding rewrite rules or incorrect
location blocks.
Additionally, inspect the network tab in your browser's developer tools. Navigate to your tech support site and trigger an API call. Verify that the response payload is valid JSON and not an HTML error page. This visual confirmation helps identify issues that automated tests might miss, such as server-side rendering errors that leak into API responses.
For related troubleshooting, you might encounter issues with symlinks ignoring CSS files. See
HTML File Opened via Symlink Ignores CSS: A Tech Support Reminder for details on resolving asset loading problems. Also, if you are fetching these JSON resources via PHP, refer to
Retrieving JSON with Curl in PHP to ensure proper client-side handling.
Frequently Asked Questions
Why does my JSON endpoint return HTML?
This usually happens because a generic fallback rule, like
try_files $uri $uri/ /index.html;, catches the request when the file is not found or due to misconfigured MIME types. Ensure your location blocks are specific and do not share fallback logic with your HTML routes.
Can I use a single location block for both HTML and JSON?
Yes, but you must differentiate them based on file extension or URI path. Using
try_files with different default types for each extension can work, but separate location blocks provide clearer control over headers and security policies for each content type.
How do I handle query parameters in exact path routing?
Exact path routing typically ignores query parameters for file lookup. If your API relies on query strings (e.g.,
/api/data?user=123), you cannot serve a static file directly. You must use a backend script (like PHP or Node.js) to process the request and generate the JSON response dynamically.
What if I need to serve both HTML and JSON from the same directory?
You can mix them in the same directory, but you must ensure the web server distinguishes them by extension. Configure
default_type or MIME mappings to recognize
.html as text and
.json as application/json. Avoid renaming files to bypass extension checks, as this breaks MIME detection.
Is it safe to disable directory indexing for API folders?
Yes, it is highly recommended. Disabling directory indexing (
Options -Indexes) prevents users from browsing the raw file structure of your API, which could expose sensitive filenames or internal organization. Always pair this with strict access controls and validation in your backend logic.