Skip to content

response-headers.md

Latest commit

 

History

History
203 lines (159 loc) · 4.32 KB

response-headers.md

File metadata and controls

203 lines (159 loc) · 4.32 KB
Raw
outline
2
3
title Response Headers Annotation
titleTemplate NpgsqlRest
description Set custom HTTP response headers for PostgreSQL REST API endpoints. Configure Cache-Control, Content-Type, and custom headers.
head
meta
name content
keywords
npgsqlrest response headers, custom http headers, cache control header, content type header, api response headers
meta
property content
og:title
NpgsqlRest Response Headers Annotation
meta
property content
og:description
Set custom HTTP response headers like Cache-Control and Content-Type.
meta
property content
og:type
article

Response Headers

Set custom HTTP response headers for the endpoint.

Syntax

<Header-Name>: <value>

Response headers use standard HTTP header format with a colon separator. Header names are case-insensitive.

Examples

Set Content-Type

create function get_html_page()
returns text
language sql
begin atomic;
select '<html><body><h1>Hello</h1></body></html>';
end;

comment on function get_html_page() is
'HTTP GET
Content-Type: text/html';

Equivalent as a SQL file endpoint (sql/get-html-page.sql):

/*
HTTP GET
Content-Type: text/html
*/
select '<html><body><h1>Hello</h1></body></html>';

Response includes: Content-Type: text/html

Multiple Headers

create function get_api_data()
returns json
language sql
begin atomic;
select '{"status": "ok"}'::json;
end;

comment on function get_api_data() is
'HTTP GET
Content-Type: application/json
Cache-Control: no-store
X-Custom-Header: custom-value';

Response includes all three headers.

Multi-Value Headers

Headers with the same name are combined:

create function set_cookies()
returns text
language sql
begin atomic;
select 'OK';
end;

comment on function set_cookies() is
'HTTP GET
Set-Cookie: session=abc123
Set-Cookie: theme=dark
Set-Cookie: lang=en';

Response includes: Set-Cookie: session=abc123, theme=dark, lang=en

Cache Control

create function get_static_config()
returns json
language sql
begin atomic;
select config from app_config where id = 1;
end;

comment on function get_static_config() is
'HTTP GET
Cache-Control: public, max-age=3600';

Clients can cache the response for 1 hour.

Combined with Other Annotations

create function export_report()
returns text
language sql
begin atomic;
...;
end;

comment on function export_report() is
'HTTP GET
@authorize manager
Content-Type: text/csv
Content-Disposition: attachment; filename="report.csv"
Cache-Control: no-cache';

Dynamic Headers from Parameters

Header values can include parameter values using the {param_name} template syntax. The matching and substitution rules (case-sensitivity, NULL handling, etc.) are shared across annotations — see Parameter Value Substitution.

create function export_report(_type text, _file text)
returns text
language sql
begin atomic;
...;
end;

comment on function export_report(text, text) is
'HTTP GET
@authorize manager
Content-Type: {_type}
Content-Disposition: attachment; filename={_file}
Cache-Control: no-cache';

Request: GET /api/export-report?_type=text/csv&_file=report.csv

Response headers:

Content-Type: text/csv
Content-Disposition: attachment; filename=report.csv

CORS Headers

create function cors_endpoint()
returns json
language sql
begin atomic;
select '{}'::json;
end;

comment on function cors_endpoint() is
'HTTP GET
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST
Access-Control-Allow-Headers: Content-Type';

Note: To configure CORS centrally (origins, methods, credentials, preflight), use the CORS configuration instead.

Common Headers

Header Purpose
Content-Type Response media type
Cache-Control Caching directives
Content-Disposition Download filename
X-* Custom application headers
Set-Cookie Set cookies

Related

Related Annotations

  • RAW - Return raw text output
  • CACHED - Server-side caching