docs: Document URL encoding requirements for record IDs with special characters

Edgar Rivera
2026-03-23T08:44:21Z

## Background
Issue #703 fixed URL-encoding of record IDs when RAFS calls the storage service. However, clients need to be aware of proper URL encoding when record IDs contain special characters.

## Problem
When a record ID contains literal `%` characters (e.g., `osdu:master-data--Sample:7%2F12-A-7%20D_Sample_249`), clients must **double-encode** the URL to preserve the `%` characters:

- ❌ Single-encoded: `7%2F12` → FastAPI decodes to `7/12` (wrong ID)
- ✅ Double-encoded: `7%252F12` → FastAPI decodes to `7%2F12` (correct ID)

This is standard HTTP behavior (RFC 3986).

## Requested Changes

### 1. API Documentation
Add a note about URL encoding in the API documentation explaining:
- Record IDs with `%` characters must be double-encoded
- Example showing correct encoding

### 2. Swagger/OpenAPI
If possible, add description/examples in the OpenAPI spec for record ID parameters showing:
- Standard record ID example: `osdu:master-data--Sample:simple_id`
- Encoded record ID example: `osdu:master-data--Sample:7%252F12-A-7%2520D_Sample_249`

## Example

| Record ID (actual) | URL to call RAFS |
|-------------------|------------------|
| `osdu:...:simple_id` | `/v2/masterdata/osdu:...:simple_id` |
| `osdu:...:7%2F12-A-7%20D` | `/v2/masterdata/osdu:...:7%252F12-A-7%2520D` |

## Related
- #703 - URL-encode record IDs in Storage client