Skip to content
Docs

Can AI give good advice on API design related questions (Part 1)

To design an API where account references are used in URLs, cookies, headers, and potentially as cookie keys, while also defining a more permissive character set for account labels, we need to carefully consider which ASCII characters are safe and practical for each use case. Let’s explore this step-by-step through a Socratic approach to guide your decision-making.

Account References in URLs, Cookies, and Headers

First, let’s think about the account reference, which will appear in sensitive contexts like URL paths, query parameters, cookies, and headers. What properties do you think are essential for an account reference to ensure it’s safe and interoperable across these contexts? For instance, should it be short, human-readable, or restricted to certain characters to avoid encoding issues?

Consider the constraints of URLs. URLs have specific rules defined by standards like RFC 3986. Which characters do you think might cause issues in a URL path or query parameter if not encoded? For example, would including a space or a question mark in an account reference create problems? Why might certain characters, like slashes or ampersands, complicate parsing in URLs?

Now, think about cookies and headers. Cookies (per RFC 6265) and HTTP headers have their own restrictions. What happens if you include a comma or semicolon in a cookie value? Could including non-printable ASCII control characters, like a null byte or line feed, break cookie parsing or pose security risks? Similarly, in headers, which characters might be problematic due to how servers or clients interpret whitespace or special characters?

Let’s narrow it down. A common approach for identifiers like account references is to use a limited, safe subset of ASCII characters to minimize encoding and parsing issues. For example, alphanumeric characters (A-Z, a-z, 0-9) are generally safe. Would you consider adding other characters, like hyphens or underscores, to make the reference more readable or flexible? Why or why not? What about avoiding characters like percent signs (%) or equals signs (=), which have special meanings in URLs or cookies?

To help you reason through this, let’s consider a potential character set for account references. A safe choice might be:

  • Alphanumeric: A-Z, a-z, 0-9
  • Optional safe symbols: - (hyphen), _ (underscore), . (dot)

Why might these be good choices? Are there any contexts where even these characters could cause issues? For instance, could a dot in a cookie key be misinterpreted? Would you want to enforce case sensitivity, or make the reference case-insensitive to simplify handling?

Account Labels

Now, let’s explore the account labels, which you’ve indicated should be more permissive, allowing spaces but excluding ASCII control characters like the delete character. What do you think the purpose of the label is? Is it for display to users, storage in a database, or something else? Why would allowing spaces be useful, and what risks might come with including them in certain contexts, like URLs or JSON?

Since you want to exclude ASCII control characters (e.g., delete, null, carriage return), let’s define what “control characters” means. In ASCII, control characters are typically those with codes 0–31 and 127 (delete). Do you think all of these should be excluded, or are there specific ones you’re most concerned about? For example, why might a delete character (ASCII 127) or a null byte (ASCII 0) be particularly problematic?

For labels, a more permissive set might include:

  • Alphanumeric: A-Z, a-z, 0-9
  • Common punctuation: space, hyphen (-), underscore (_), dot (.), comma (,), apostrophe (’), etc.
  • Excluding control characters (ASCII 0–31, 127)

Does this seem like a reasonable starting point? What other characters might you want to allow for user-friendly labels? For example, would you include symbols like ampersands (&) or hashtags (#)? Why might these be problematic in some systems, like databases or web forms?

Reference Table for Characters to Avoid

You asked for a reference table listing characters to avoid in different contexts. Let’s reason through what such a table might include. For each context (URL path, query parameters, cookies, headers, labels), what characters do you think should be avoided, and why? Here’s a starting point to guide your thinking:

  1. URL Path (RFC 3986):
    • Reserved characters: /, ?, #, [, ], @, !, $, &, ’, (, ), *, +, ,, ;, =
    • Why avoid? These have special meanings (e.g., / separates path segments, ? starts query parameters).
    • Non-printable characters (ASCII 0–31, 127): Can break parsing or pose security risks (e.g., injection attacks).
    • Space: Requires encoding (%20), which can complicate usage.
  2. URL Query Parameters:
    • Reserved: &, =, #, +, space
    • Why avoid? & separates key-value pairs, = separates keys from values, and spaces need encoding.
    • Control characters: Same risks as in paths.
  3. Cookies (RFC 6265):
    • Forbidden in values: ,, ;, space, control characters (ASCII 0–31, 127)
    • Forbidden in keys: Same as values, plus =, as it separates key from value.
    • Why avoid? These can break cookie parsing or lead to malformed requests.
  4. HTTP Headers:
    • Forbidden: Control characters (ASCII 0–31, 127), non-ASCII characters.
    • Restricted: Whitespace (space, tab) at the start or end, as it may be trimmed or cause parsing errors.
    • Why avoid? Headers are sensitive to formatting, and control characters can cause security issues.
  5. Account Labels:
    • Avoid: Control characters (ASCII 0–31, 127) due to risks in storage, display, or processing.
    • Caution: Characters like <, >, & (potential XSS risks in web contexts), or quotes (”, ’) that might break JSON or SQL if not escaped.

Would you like to refine this table further? For example, should we specify which characters are safe rather than focusing on those to avoid? Would you want to test specific characters in each context to see how they behave in real systems?

For account references, a conservative approach is to use:

  • A-Z, a-z, 0-9, -, _, .
  • Why? These are safe across URLs, cookies, and headers, requiring minimal encoding. They’re also human-readable and unlikely to cause parsing issues.
  • Questions: Should the length be limited (e.g., 1–64 characters)? Should it be case-sensitive?

For account labels, a more permissive set could be:

  • A-Z, a-z, 0-9, space, -, _, ., ,, ’, !, :
  • Exclude: ASCII 0–31, 127, and potentially risky characters like <, >, &, ”, \ unless properly escaped in context.
  • Questions: Should labels have a maximum length? Are there specific display or storage constraints to consider?

Next Steps

To solidify your design, what specific use cases or systems (e.g., web frameworks, databases) are you targeting? Are there particular edge cases, like internationalization or legacy system compatibility, you want to explore? Would it help to create a sample account reference and label, then test how they behave in a URL, cookie, or header?

If you’d like a visual representation of safe vs. unsafe characters for each context, would you want me to generate a chart comparing the allowed characters across URLs, cookies, headers, and labels? This could help clarify the differences visually.

What do you think is the next question we should tackle to refine your API’s character set choices?

—

Prompt 2:

MD WebClip isn’t working,