Validating Response Bodies (URL-Encoded)

Some APIs return their response bodies as URL-encoded form data (application/x-www-form-urlencoded) instead of JSON. OAuth token endpoints are the most common example. Instead of returning {"access_token": "abc123", "token_type": "bearer"}, they return access_token=abc123&token_type=bearer&expires_in=3600.

HttpClientResponse.schemaBodyUrlParams validates these URL-encoded response bodies against a Schema, just like schemaBodyJson does for JSON responses.

1
import { HttpClientResponse } from "effect/unstable/http";
2
import { Schema } from "effect";
3

4
const TokenResponse = Schema.Struct({
5
  access_token: Schema.String,
6
  token_type: Schema.String,
7
  expires_in: Schema.NumberFromString,
8
});
9

10
// After executing a request to an OAuth token endpoint:
11
const token =
12
  yield * HttpClientResponse.schemaBodyUrlParams(TokenResponse)(response);
13

14
// token is fully typed: { access_token: string, token_type: string, expires_in: number }
15
console.log(token.access_token);

schemaBodyUrlParams is curried, following the same pattern as schemaBodyJson:

1
HttpClientResponse.schemaBodyUrlParams(TokenResponse)(response);
2
//                                      ^^^^^^^^^^^^   ^^^^^^^^
3
//                                        schema       response

Under the hood, schemaBodyUrlParams() reads the response body as URL-encoded params, then validates the key-value pairs against your schema. If a declared field is missing or doesn’t match, you get a SchemaError.

Notice Schema.NumberFromString for expires_in. URL-encoded data is always strings, so the raw value is "3600". NumberFromString converts it to the number 3600 during validation.