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

Questions to ask yourself about endpoints:

• 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/12345

Resources can also be created, updated, and deleted through endpoints. For example, the following endpoint could be used to create a new user:

HTTP POST /users

How 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

Questions to ask yourself about resources:

• 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 %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

Questions to ask yourself about URL encoding:

• 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, 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.

Questions to ask yourself about URL design:

• Does the URL follow RESTful design principles?
• Is the URL human-readable and intuitive?
• Does the URL use plural nouns for collections?
• How deep is the URL hierarchy, and is it appropriate?
• Is versioning incorporated into the URL structure?
• Does the URL avoid exposing implementation details?

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.

Questions to ask yourself about URL security:

• Does the URL contain any sensitive information that should be removed?
• Is HTTPS being used to protect the URL during transmission?
• Could the URL be susceptible to path traversal attacks?
• Are there any URL length limitations to consider?
• Should any of the parameters be moved to the request body for security purposes?
• Are there input validation measures for URL components?

Key Takeaways

• Endpoints represent complete URLs for accessing API resources
• Resources are data objects or entities exposed by the API
• URL encoding converts special characters to make them URL-safe
• Choose between absolute and relative URLs based on documentation needs
• Follow URL design best practices for intuitive, consistent API interfaces
• Address security considerations to prevent exposing sensitive data in URLs

Essential URL Resources

Expand your understanding of URL structure with these carefully selected resources.

External Resources

• URL Encoding Reference
• RESTful API Design Best Practices

Tools & APIs

• URL Encoder/Decoder
• API URL Builder

Previous: Anatomy of a URL Next: Understanding Data Formats

Start your learning journey!

Course Progress 0%

0 of 0 pages completed

Found value in the course?

Your support fuels my work!

Have an issue?

Help improve the course by reporting an issue