kme_content_adapter/specs/003-kme-content-fetch/contracts/http-content-fetch.md

# HTTP Contract: Content Fetch Route

**Feature**: `003-kme-content-fetch`  
**File**: `specs/003-kme-content-fetch/contracts/http-content-fetch.md`

This document defines the HTTP request/response contract for the content-fetch route exposed by the
KME Content Adapter proxy.

---

## Route

```
GET {proxy-base-url}?kmeURL={encoded-article-url}
```

The proxy detects the content-fetch route when:
- The incoming URL does **not** end in `/sitemap.xml`, AND
- The query string contains a `kmeURL` parameter (present, regardless of value)

Requests without `kmeURL` (and not a sitemap request) are routed to the existing auth-check
passthrough (returns 200 "Authorized").

---

## Request

### Method
`GET`

### Query Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `kmeURL` | Yes | The verbatim `vkm:url` value from the KME Search API response. Must be a well-formed absolute `http` or `https` URL. Percent-encoded characters are decoded once (standard URL decoding) — double-encoding must not occur. |

### Headers
None required on the inbound request. The proxy adds its own `Authorization` header on the upstream
request.

### Example Request
```
GET /?kmeURL=https%3A%2F%2Fcontent.kme.example%2Farticles%2F123 HTTP/1.1
Host: proxy.example.com
```

---

## Responses

### 200 OK — Article HTML Body

The article was successfully fetched and `vkm:articleBody` was extracted.

```
HTTP/1.1 200 OK
Content-Type: text/html

<p>Article content here...</p>
```

| Field | Value |
|-------|-------|
| Status | `200` |
| `Content-Type` | `text/html` |
| Body | Raw HTML string from `vkm:articleBody` field of the KME Content Service JSON-LD response. Not sanitised or transformed. |

---

### 400 Bad Request — Invalid `kmeURL`

Returned when `kmeURL` is absent, empty, whitespace-only, or not a well-formed absolute http/https URL.
No upstream request is made.

```
HTTP/1.1 400 Bad Request
Content-Type: text/plain

Bad Request: kmeURL parameter is required
```

```
HTTP/1.1 400 Bad Request
Content-Type: text/plain

Bad Request: kmeURL must be a well-formed absolute http/https URL
```

| Trigger | Response body |
|---------|---------------|
| `kmeURL` absent, empty, or whitespace | `Bad Request: kmeURL parameter is required` |
| `kmeURL` present but malformed or non-http/https | `Bad Request: kmeURL must be a well-formed absolute http/https URL` |

---

### 404 Not Found — Article Not Found

Returned when the upstream KME Content Service returns a 4xx response for the article URL, or when
the upstream response does not contain a non-empty `vkm:articleBody`.

```
HTTP/1.1 404 Not Found
Content-Type: text/plain

Not Found: article not found at upstream
```

```
HTTP/1.1 404 Not Found
Content-Type: text/plain

Not Found: article body not present in upstream response
```

| Trigger | Response body |
|---------|---------------|
| Upstream 4xx HTTP response | `Not Found: article not found at upstream` |
| `vkm:articleBody` absent, null, or empty string | `Not Found: article body not present in upstream response` |

---

### 500 Internal Server Error — Proxy Configuration Error

Returned when a required OIDC setting is missing from `kme_CSA_settings`. Indicates a proxy
deployment/configuration issue.

```
HTTP/1.1 500 Internal Server Error
Content-Type: text/plain

Configuration error: missing required field: tokenUrl
```

---

### 502 Bad Gateway — Upstream or Token Failure

Returned for any upstream connectivity, protocol, or data error, and for token acquisition failure.

```
HTTP/1.1 502 Bad Gateway
Content-Type: text/plain

Bad Gateway: token acquisition failed
```

| Trigger | Response body |
|---------|---------------|
| OIDC token acquisition failure | `Bad Gateway: token acquisition failed` |
| Upstream request timeout (`ECONNABORTED`/`ERR_CANCELED`) | `Bad Gateway: upstream request timed out` |
| Upstream 5xx HTTP response | `Bad Gateway: upstream error HTTP {status}` |
| Network-level error (no HTTP response) | `Bad Gateway: {error message}` |
| Upstream response body is not valid JSON | `Bad Gateway: unparseable response from upstream` |
| Upstream response body is not an object | `Bad Gateway: unexpected response from upstream` |

---

## Upstream Request (Proxy → KME Content Service)

The proxy makes a single GET request to the verbatim `kmeURL` value.

```
GET {kmeURL} HTTP/1.1
Authorization: OIDC_id_token {id_token}
```

| Field | Value |
|-------|-------|
| Method | `GET` |
| URL | Verbatim value of `kmeURL` query parameter — no manipulation, no re-encoding |
| `Authorization` | `OIDC_id_token {id_token}` where `id_token` is from `getValidToken()` |
| Timeout | 10 000 ms (10 seconds) |

---

## Error Mapping Summary

```
kmeURL absent/empty                  → 400
kmeURL malformed / non-http(s)       → 400
Missing OIDC config                  → 500
Token acquisition failure            → 502
Upstream 4xx                         → 404
Upstream 5xx                         → 502
Upstream timeout                     → 502
Network error                        → 502
Unparseable response body            → 502
vkm:articleBody absent/null/empty    → 404
Success                              → 200 text/html
```

---

## Non-regression: Existing Routes

This feature does not change the behaviour of existing routes:

| Route | Behaviour |
|-------|-----------|
| URL ends in `/sitemap.xml` | Sitemap flow (unchanged) |
| No `kmeURL`, not sitemap | Auth-check passthrough → 200 "Authorized" (unchanged) |