Advanced URL Anatomy in API Documentation

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.

HTTP GET /users/12345

{
  "id": 12345,
  "name": "John Doe",
  "email": "john.doe@example.com"
}

HTTP GET /users/12345

HTTP POST /users

https://api.example.com/users/12345

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 %20 or +
• 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

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, easier to read, adapts to environment changes
• Best for: Documentation where the base URL is defined once and reused

A good practice is to define the base URL early in your documentation and use relative URLs for endpoints, making it clear which parts are fixed and which are variable.

URL Design Best Practices for APIs

Well-designed URLs make APIs more intuitive and easier to use. Here are some best practices to highlight in your documentation:

1. Be consistent with resource naming
   • Use plural nouns for collections (/users, not /user)
   • Use consistent casing (kebab-case is common: /user-profiles)
2. Create a logical hierarchy
   • Nest resources logically: /departments/5/employees
   • But don’t go too deep (more than 3 levels becomes unwieldy)
3. Use query parameters appropriately
   • For filtering: /products?category=electronics&price=<100
   • For pagination: /users?page=2&limit=20
   • For sorting: /orders?sort=date_desc
4. Version your APIs in the URL
   • /v1/users makes it clear which version is being used
   • Allows for evolution while maintaining backward compatibility
5. Keep URLs readable
   • Avoid cryptic abbreviations
   • Use descriptive resource names

When you document these practices, you help developers understand not just how to use your API, but the reasoning behind its design.

Security Considerations for API URLs

URLs can inadvertently expose sensitive information if not handled properly. Your documentation should address these security concerns:

1. Never include credentials in URLs
   • Bad: https://api.example.com/users?api_key=abcd1234
   • Good: Use authorization headers or request body for credentials
2. Be cautious with sensitive identifiers
   • Consider whether IDs in URLs could expose sensitive information
   • For highly sensitive operations, consider POST instead of GET to keep parameters out of URLs
3. Protect against path traversal attacks
   • Document how your API validates and sanitizes URL path components
   • Explain any restrictions on characters or patterns in URL paths
4. HTTPS everywhere
   • Emphasize that all API URLs should use HTTPS, never HTTP
   • Explain the risks of sending unencrypted API requests
5. URL length limitations
   • Document any restrictions on URL length
   • Suggest alternatives (like POST with request body) for complex queries

By addressing these security considerations in your documentation, you help developers build more secure applications that properly protect user data.