Read the envelope from a frontend¶
Every answer has the same top level, so a client needs one type, one fetch function and one pager. TypeScript, though the shape is the same from any language.
The types¶
type Page =
| { type: 'page'; count: number; page: number; pages: number; page_size: number;
has_next: boolean; has_previous: boolean }
| { type: 'cursor'; next_cursor: string | null; previous_cursor: string | null;
page_size: number; has_next: boolean; has_previous: boolean };
type Success<T> = { success: true; status_code: number; message: string; data: T;
pagination?: Page };
type Failure = { success: false; status_code: number; message: string; error_code: string;
data: { fields?: Record<string, { code: string; message: string }[]> }
& Record<string, unknown> };
type Envelope<T> = Success<T> | Failure;
If the project uses the schema, generate these from it instead: the schema describes the envelope, so the generated types are the same.
One fetch function¶
async function ask<T>(path: string, init: RequestInit = {}): Promise<Envelope<T>> {
const response = await fetch(`${API}${path}`, {
...init,
headers: { 'Content-Type': 'application/json',
'Accept-Language': currentLanguage(), // the messages in the reader's language
...init.headers },
});
return response.json(); // always the envelope
}
const answer = await ask<Product>('/products/1/');
if (answer.success) {
show(answer.data);
} else if (answer.error_code === 'out_of_stock') { // branch on the code, never the message
offer(answer.data.available as number);
} else {
toast(answer.message); // a person reads the message
}
One pager for both kinds¶
function nextQuery(page: Page): Record<string, string> | null {
if (!page.has_next) return null;
return page.type === 'page'
? { page: String(page.page + 1) }
: { cursor: page.next_cursor! };
}
has_next is in both kinds, so "load more" works on a numbered list and a
feed alike.
A form's errors¶
if (!answer.success && answer.error_code === 'validation_error') {
for (const [field, problems] of Object.entries(answer.data.fields ?? {})) {
markField(field, problems[0].message); // "items.0.quantity" for a nested one
}
}
problems[0].code - required, max_length, unique - tells a client what
went wrong without reading translated text.