Advanced URL Anatomy in API Documentation
Master the advanced components of URL structure in API documentation - endpoints, resources, HTTP methods, status codes, and authentication. Learn how each element enhances API functionality and why understanding these advanced URL concepts is essential for effective API integration and documentation.
Table of Contents
You now know about the components of a URL: protocol, domain, path, query parameters, and fragment identifiers. But that’s not all! URLs also have endpoints and resources. In this chapter, you’ll learn about endpoints and resources and how they differ from paths.
Let’s start with an example URL: https://api.example.com/users/12345?name=John Doe
The above URL has following components, and we document all of them if present:
- Endpoint:
https://api.example.com/users/12345?name=John Doe - Resource:
/12345?name=John Doe
Let’s see everything in detail. Select the appropriate tabs for more information. For example, if you want all the relevant information on domain name, select the Endpoint tab.
Endpoint
An endpoint is a complete URL that can be used to access a resource. It includes the protocol (for example, HTTP or HTTPS), domain name, path, and query parameters (if any). The HTTP method is also typically included in the endpoint.
In our URL, the endpoint is: https://api.example.com/users/12345?name=John Doe.
This endpoint can be used to retrieve the user with the ID 12345 from the API exposed by api.example.com.
How to Identify an Endpoint?
To identify an endpoint, look for the following components in the URL:
- Protocol (for example, HTTP or HTTPS)
- Domain name
- Path
- Query parameter (if any)
For example, in the following URL, the endpoint is: https://api.example.com/users/12345:
HTTP GET /users/12345- What is the purpose of the endpoint in this API?
- What is the full URL of the endpoint, including the protocol, domain, path, and query parameters?
- What HTTP methods can be used with this endpoint (for example, GET, POST, PUT, DELETE)?
- What type of data does this endpoint return (for example, JSON, XML)?
- Are there any specific security considerations for this endpoint (for example, authentication or authorization requirements)?
- Is the endpoint documented, and if so, where can you find the documentation?
Resource
A resource is a data object or entity that is exposed by an API. It can be anything from a single user to a complex product catalog. Resources are typically represented as JSON or XML objects in API responses.
For example, the following JSON object could represent a user resource:
{
"id": 12345,
"name": "John Doe",
"email": "john.doe@example.com"
}
Resources can be accessed through endpoints. For example, the following endpoint could be used to retrieve the user with the ID 12345:
HTTP GET /users/12345Resources can also be created, updated, and deleted through endpoints. For example, the following endpoint could be used to create a new user:
HTTP POST /usersHow to Identify a Resource?
To identify a resource, look for the following in the URL:
- Path
- Query parameters (if any)
For example, in the following URL, the resource is the user with ID 12345:
https://api.example.com/users/12345- What is the purpose of this resource in the context of the API?
- What data does this resource represent (for example, user, product, order)?
- What is the structure and schema of this resource's data (for example, fields, attributes)?
- How can you uniquely identify this resource (for example, ID, URL, or other key)?
- What operations can you perform on this resource (for example, read, create, update, delete)?
- Are there any relationships between this resource and other resources in the API?
- What are the common use cases for accessing or modifying this resource?
- Are there any specific access control or permissions associated with this resource?
- How is this resource represented in API responses (for example, JSON, XML)?
Advanced URL Concepts for API Documentation
Now that we’ve covered the basics of endpoints and resources, let’s explore some advanced URL concepts that are crucial for creating effective, secure, and user-friendly API documentation.
URL Encoding: Making Special Characters Safe
Have you ever noticed that spaces in URLs are replaced with %20 or +? That’s URL encoding in action!
URL encoding (also called percent-encoding) converts characters that aren’t allowed in URLs into a format that is. This is especially important for APIs that handle user input or special characters.
For example, the URL https://api.example.com/search?q=John Doe should actually be encoded as https://api.example.com/search?q=John%20Doe.
Here are some common URL encoding situations:
- Spaces become
%20or+ - Special characters like
&,=,?, and/become%26,%3D,%3F, and%2F - Non-ASCII characters (like ñ, é, or emoji) are encoded into their UTF-8 byte values
When documenting APIs, you should:
- Show both the readable and encoded versions of URLs when they contain special characters
- Remind developers to encode values when building URL strings programmatically
- Mention which characters need special handling in your API
- Which special characters need to be encoded in this URL?
- How are spaces represented in URL-encoded form?
- What happens if you don't properly encode special characters in URLs?
- Are there differences in how different programming languages handle URL encoding?
- How do you decode URL-encoded strings?
- Which characters have special meanings in URLs and need to be encoded?
Relative vs. Absolute URLs in API Documentation
When writing API documentation, you’ll need to decide whether to use absolute URLs (full URLs including the domain) or relative URLs (partial URLs that depend on a base URL).
Absolute URLs:
- Example:
https://api.example.com/v1/users/12345 - Benefits: Self-contained, no ambiguity, works anywhere
- Best for: API reference documentation, examples that need to be copy-pasted
Relative URLs:
- Example:
/v1/users/12345(relative to the API’s base URL) - Benefits: Shorter, environment-agnostic, easier to maintain when base URL changes
- Best for: Documentation that establishes a base URL upfront, internal references
URL Types Comparison
| Feature | Absolute URLs | Relative URLs |
|---|---|---|
| Includes full domain | ✓ | ✗ |
| Works without context | ✓ | ✗ |
| Environment-agnostic | ✗ | ✓ |
| Shorter in documentation | ✗ | ✓ |
| Easier maintenance when domain changes | ✗ | ✓ |
Documenting Best Practices for URL Design
As technical writers, you need to clearly explain the URL design patterns adopted by your API developers. Focus on these documentation aspects:
- Document Resource Naming Conventions
- Explain if your API uses nouns for resources (e.g.,
/users/123) - Clarify if plural nouns are used for collections (e.g.,
/products) - Example: “Our API uses plural nouns to represent resource collections. Individual resources are accessed using their unique IDs.”
- Explain if your API uses nouns for resources (e.g.,
- Explain Hierarchical Relationships
- Document how nested resources are represented (e.g.,
/users/123/orders) - Example: “Child resources are accessed through their parent resources as shown in this pattern:
/parent/{parentId}/child/{childId}”
- Document how nested resources are represented (e.g.,
- Clarify Naming Conventions
- Document whether hyphenation, camelCase, or underscore_notation is used
- Example: “All resource names use hyphenated-lowercase format for multi-word resources (e.g.,
/shipping-addresses)”
- Create Consistency Guides
- Create a style guide section specifically for URL patterns
- Document exceptions to standard patterns with clear examples
Remember, your job is not to design these patterns but to explain them clearly so developers can correctly implement your API.
Documenting Security Considerations for API URLs
Technical writers play a crucial role in communicating security practices through documentation. Here’s how to effectively document security aspects of URLs:
- Clearly Document Security Warning Notices
- Prominently display warnings about sensitive data: “⚠️ Never include authentication credentials in URL parameters”
- Use highlighted callout boxes for critical security information
- Document Protocol Requirements
- Clearly state if HTTPS is required: “All API requests must use HTTPS. HTTP requests will be rejected.”
- Explain consequences of using incorrect protocols
- Document Authentication Parameter Placement
- Explain where authentication belongs (typically headers, not URLs)
- Provide contrasting examples of correct vs. incorrect approaches:
- ✅ CORRECT:
Authorization: Bearer {token}in headers - ❌ INCORRECT:
/api/data?token=1234abcin URL
- ✅ CORRECT:
- Document ID Exposure Guidelines
- Explain your API’s approach to resource identifiers
- Example: “This API uses non-sequential UUIDs to prevent resource enumeration”
- Document Validation Requirements
- Explain any input validation implemented for URL parameters
- Provide examples of valid vs. invalid parameters
The technical writer’s role is to communicate these security measures clearly, helping developers use the API securely rather than implementing security themselves.
Documenting Common URL Issues for End Users
How to Document URL Troubleshooting for API Users
Documentation Challenge: Explaining Deeply Nested URLs
What to document: Provide a visual hierarchy diagram for complex URLs like /organizations/123/departments/456/teams/789/members/101112
Documentation approach: Create a table showing each path segment and its purpose, with examples of alternatives:
- Standard approach:
/organizations/{orgId}/departments/{deptId}/teams/{teamId}/members/{memberId} - Alternative approach:
/members/{memberId}?team={teamId}
Documentation Challenge: Clarifying Inconsistent Resource Names
What to document: When your API uses varying terms like /users, /staff, and /customers for similar concepts
Documentation approach: Create a resource glossary that maps business concepts to API endpoints:
| Business Concept | API Endpoint | When to Use |
|---|---|---|
| System users | /users |
For managing login accounts |
| Staff members | /staff |
For employee-specific operations |
Documentation Challenge: Explaining Action-Based URLs
What to document: How to properly use verb-based endpoints if your API includes them (like /getUsers or /createOrder)
Documentation approach: Create a "URL Patterns" section that explains your API's approach to actions:
This API uses two types of URL patterns:
- Resource-based endpoints:
GET /users,POST /orders - Action-based endpoints:
/convertCurrency,/validateAddress
Use resource-based endpoints when working with data objects, and action-based endpoints for stateless operations.
Documentation Challenge: Documenting Complex Query Parameters
What to document: How to use endpoints with many parameters like /search?param1=value1¶m2=value2¶m3=value3...
Documentation approach: Create parameter tables with example combinations:
- Use expandable sections for different use cases
- Provide code samples showing the most common parameter combinations
- Create a decision tree to help users determine which parameters they need
Example: "For basic searches, only the query parameter is required. Add filter parameters to narrow results."
Documentation Best Practices for API URLs
As technical writers, your goal is not just to understand URL components but to document them effectively for your audience. Here are specific documentation best practices for API URLs:
1. Create Clear Visual Hierarchies
Document URL components using visual aids:
https://api.example.com/v2/users/12345?fields=name,email
└─┬─┘ └───┬───┘ └┬┘└─┬─┘└┬┘ └────┬────┘
│ │ │ │ │ └─ Query Parameters
│ │ │ │ └─ Resource ID
│ │ │ └─ Collection
│ │ └─ Version
│ └─ Domain
└─ Protocol
2. Use Consistent Formatting
Establish and follow formatting standards in your documentation:
- Use
code formattingfor all URL components - Bold or color-code variable parts that users must replace
- Include parameters tables that explain each variable component
3. Include Clear Examples
Provide multiple examples for different use cases:
- Basic example (minimal required parameters)
- Complete example (all possible parameters)
- Error examples (showing common mistakes)
4. Document URL Parameters Thoroughly
When documenting URL parameters, create comprehensive parameter tables that answer all possible developer questions. Here’s a model parameter documentation table structure:
World-Class URL Parameter Documentation
| Property | Documentation Guidance | Example |
|---|---|---|
| Name Required |
|
|
| Description |
|
Specifies the unique identifier of the product to retrieve. This ID is generated when a product is created and remains constant across all environments. |
| Location |
|
Path parameter (in URL path) Other examples: Query parameter, Path parameter, Header |
| Data Type |
|
Other examples: |
| Required? |
|
Required Or: Optional, Required if |
| Default |
|
Other examples: |
| Constraints |
|
Other examples: 1-100 characters, Values: |
| Examples |
|
Valid: Invalid: |
| Notes |
|
ℹ️ The ⚠️ This parameter cannot be used with the |
This comprehensive parameter table structure includes all essential information developers need, presented in a visually clear format. Using this consistent structure for all parameters ensures your documentation is thorough and accessible. Each row provides both guidance for technical writers and real-world examples.
5. Address Common Documentation Challenges
When documenting APIs, be prepared to handle:
- Environment differences: Document how URLs change between development, staging, and production
- Authentication details: Clearly mark where authentication tokens belong in the URL or headers
- Encoding requirements: Explain which parameters need special encoding and why
- Rate limits: Document any URL-based rate limiting (e.g., per endpoint)
Remember that good API documentation helps developers implement your API correctly the first time, reducing support burden and improving adoption.
You’ve now learned advanced concepts of URL anatomy for API documentation. In the next chapter, we’ll explore data formats used in API communication, which will build upon the URL concepts we’ve mastered here.
Test Your Knowledge: URL Anatomy
Look at this URL: https://api.example.com/v2/products/electronics?brand=apple&sort=price#details
Can you identify:
- The endpoint
- The resource path
- The query parameters
- The fragment identifier
Frequently Asked Questions
URL Basics & Structure
A URL (Uniform Resource Locator) consists of five main components: protocol (e.g., https://), domain name (e.g., example.com), path (e.g., /products), query parameters (e.g., ?id=123), and fragment identifiers (e.g., #section1). Each component serves a specific purpose in locating and accessing resources on the web.
HTTP (Hypertext Transfer Protocol) and HTTPS (HTTP Secure) both facilitate web communication, but HTTPS adds a crucial security layer. HTTP sends data in plain text, making it vulnerable to eavesdropping, while HTTPS encrypts data using SSL/TLS protocols. This encryption protects sensitive information like passwords and payment details. Modern APIs and websites should always use HTTPS for security.
Query parameters appear after a question mark (?) in a URL and are formatted as key-value pairs separated by ampersands (&). For example: example.com/search?query=api&page=2. They allow you to send additional information to the server, such as search terms, filter criteria, or pagination details. When documenting APIs, always specify which query parameters are required versus optional, their data types, and default values.
Fragment identifiers appear after a hash symbol (#) in a URL (e.g., example.com/page#section3) and point to specific sections within a webpage. They’re processed by the browser, not the server, meaning they aren’t sent in HTTP requests. While less common in API requests, they’re useful in API documentation to create deep links to specific sections. Unlike query parameters, fragments don’t reload the page when changed.
Subdomains appear before the main domain name (e.g., api.example.com instead of example.com). Many companies use dedicated subdomains for their APIs (like api.twitter.com) to separate API traffic from website traffic. This approach allows for independent scaling, different security policies, and clearer DNS management. In documentation, always clearly indicate which subdomain to use, especially if different environments (sandbox vs. production) use different subdomains.
URL Implementation & Best Practices
RESTful URL patterns focus on representing resources rather than actions. They use nouns for resources (e.g., /users instead of /getUsers), rely on HTTP methods for actions, follow a hierarchical structure for related resources (e.g., /users/123/orders), and maintain consistency. Following these patterns creates intuitive, predictable APIs that are easier to learn, use, and maintain.
Spaces and special characters in URLs must be URL-encoded (also called percent-encoding). Spaces become %20 or +, while special characters like &, ?, and # become %26, %3F, and %23 respectively. For example, ‘John Smith’ becomes ‘John%20Smith’. Most programming languages offer built-in functions for URL encoding (e.g., encodeURIComponent() in JavaScript). Always encode user-provided data before including it in URLs to prevent security issues.
Path parameters are part of the URL path (e.g., /users/{userId}) and are typically used to identify specific resources. They’re required and directly affect which resource is accessed. Query parameters appear after the ? (e.g., /users?role=admin) and are used for filtering, sorting, or modifying how resources are returned. They’re often optional and don’t fundamentally change which resource is being accessed. Path parameters are generally preferred for required, resource-identifying values.
While the HTTP specification doesn’t define a maximum URL length, different browsers, servers, and proxies have various limits. A practical maximum length is about 2,000 characters, though some systems have lower limits. Extremely long URLs can cause issues like truncation, server errors, or broken links. To avoid problems, keep URLs under 2,000 characters, use POST requests for large data payloads, and consider implementing shortened URLs for sharing.
There are several approaches to API versioning in URLs. The most common is path versioning (e.g., /api/v1/users), which is explicit and easily visible but technically not RESTful. Other methods include query parameter versioning (/api/users?version=1), custom header versioning (API-Version: 1), or content negotiation using the Accept header. Path versioning is most widely used for its simplicity and explicit nature, though header-based approaches are more technically correct from a RESTful perspective.
URL Security & Performance
URLs impact API security in several ways. First, sensitive data should never be included in URLs since they’re often logged, cached, and visible in browser history. Second, URLs should use HTTPS to encrypt the entire connection, preventing man-in-the-middle attacks. Third, predictable resource IDs in URLs (like sequential numbers) can be vulnerable to enumeration attacks. Finally, URL parameters should be validated to prevent injection attacks. Always consider what information is exposed through your URL structure.
A well-structured URL enhances SEO for API documentation. Use descriptive, keyword-rich paths that explain the content (e.g., /docs/api/authentication instead of /d/a/auth). Keep URLs relatively short, use hyphens for word separation (not underscores), maintain a logical hierarchy, and ensure consistency. Clean, semantic URLs improve search rankings, make documentation more discoverable, and provide better user experience through greater readability and memorability.
Extremely long URLs can negatively impact performance in several ways. First, they increase the size of HTTP request headers, which can slow down requests, especially in high-volume scenarios. Second, very long URLs may exceed server or proxy limits, causing request failures. Third, lengthy URLs can increase DNS resolution time if they contain many subdomains. For optimal performance, keep URLs concise, use POST requests for large data payloads, and consider implementing pagination for large resource collections.
Absolute URLs include the complete path starting with the protocol and domain (e.g., https://api.example.com/v1/users), while relative URLs omit some parts and are interpreted relative to a base URL (e.g., /v1/users or ../products). In API documentation, absolute URLs provide complete clarity but require updates if the domain changes. Relative URLs are more maintainable across environments but require context to understand. Best practice is to use absolute URLs for external references and relative URLs for internal links within the same documentation site.
URL redirects (status codes 301, 302, 307, etc.) affect APIs in several ways. They add latency by requiring additional HTTP requests, which can significantly impact performance in mobile or low-bandwidth environments. For API clients, redirects may require additional handling logic, especially for maintaining authentication across redirects. While redirects are useful for API versioning transitions or domain migrations, they should be minimized in production APIs. If redirects are necessary, use 301 (permanent) redirects where appropriate to enable caching.
Advanced URL Concepts
URL templates provide a format for describing parameterized URLs using placeholders. For example, instead of showing /users/123, a template would show /users/{userId}. Common formats include RFC 6570 URL Templates and OpenAPI’s path templating. These templates clearly distinguish between fixed and variable parts of URLs, make parameters explicit, ensure consistency across documentation, and enable automatic code generation. Always include examples of both the template format and concrete, fully-expanded URLs in documentation.
Different API architectures use distinct URL patterns. REST APIs use multiple endpoints representing resources (/users, /products/{id}, etc.) with HTTP methods determining actions. GraphQL typically uses a single endpoint (e.g., /graphql) for all operations, with the request body specifying the data requirements. SOAP APIs often use a single endpoint with XML payloads and rely on the SOAP protocol. Understanding these differences helps technical writers document each API type appropriately and helps developers integrate with them correctly.
URI schemes appear at the beginning of URLs (like https://, ftp://, or mailto:) and specify the protocol or purpose of the resource. Beyond common web protocols, APIs might use specialized schemes like ws:// or wss:// for WebSockets, data: for embedding data directly in URLs, or custom schemes for mobile deep linking. When documenting APIs, always specify the required scheme and explain any non-standard schemes that might be used.
Internationalized Domain Names (IDNs) containing non-ASCII characters (like ü, é, or 汉字) require special handling in APIs. They must be converted to Punycode (ASCII representation) format before DNS resolution. For example, 例子.测试 becomes xn--fsqu00a.xn--0zwm56d. API clients should use libraries that handle this conversion automatically. When documenting APIs that support IDNs, provide examples in both formats and explain potential encoding issues, particularly for users in international markets.
URL normalization is the process of standardizing URLs to a canonical form by applying transformations like converting to lowercase, removing default ports, resolving relative references, and more. Normalized URLs are important for API caching, security checks, and preventing duplicate content. For example, HTTP://example.COM:80/path/ and http://example.com/path should be treated as identical. API gateways and documentation should explain how URLs are normalized to help developers understand caching behavior and create consistent requests.
Key Takeaways
- Endpoints are complete URLs used to access API resources, including protocol, domain, path, and query parameters
- Resources are data objects or entities exposed by an API, typically represented as JSON or XML
- URL encoding is essential for handling special characters in URLs, converting them to a web-safe format
- Use absolute URLs for standalone examples and relative URLs for environment-agnostic documentation
- Follow RESTful URL design best practices: use nouns, maintain hierarchies, and be consistent
- Prioritize security in URL design by using HTTPS, avoiding sensitive data in URLs, and implementing proper authentication
Test Your Knowledge
Advanced URL Resources
Expand your understanding of URL structure with these carefully selected resources.
External Resources
Tools & APIs
Found value in the course?
Your support fuels my work!
Have an issue?
Help improve the course by reporting an issue
