NpgsqlRest

Appearance

Comments
Written with Claude

PATH ​

Set a custom endpoint path. Alternative to specifying the path in the HTTP annotation.

Keywords ​

@path, path

Syntax ​

code
@path <url-path>

Examples ​

Custom Path ​

sql
sql
create function get_user_data()
returns json
language sql
begin atomic;
...;
end;

comment on function get_user_data() is
'HTTP GET
@path /users/data';

Equivalent as a SQL file endpoint (sql/get-user-data.sql):

sql
sql
-- HTTP GET
-- @path /users/data
select row_to_json(u) from users u where id = current_user_id();

Creates: GET /users/data

Path with HTTP Method ​

sql
sql
comment on function my_function() is
'HTTP GET
@path /custom/endpoint';

Creates: GET /custom/endpoint

Versioned API ​

sql
sql
comment on function get_users_v2() is
'HTTP GET
@path /api/v2/users';

Path Parameters ​

Paths can include parameter placeholders using the {param} syntax. Parameter values are extracted directly from the URL path.

Basic Path Parameter ​

sql
sql
create function get_user(user_id int)
returns json
language sql
begin atomic;
...;
end;

comment on function get_user(int) is
'HTTP GET
@path /users/{user_id}';

Call: GET /users/42 → user_id = 42

Nested Path Parameters ​

sql
sql
create function get_user_order(user_id int, order_id int)
returns json
language sql
begin atomic;
...;
end;

comment on function get_user_order(int, int) is
'HTTP GET
@path /users/{user_id}/orders/{order_id}';

Call: GET /users/42/orders/123 → user_id = 42, order_id = 123

Parameter Name Matching ​

Parameter names in {param} can use either:

  • PostgreSQL snake_case name: {user_id}
  • Converted camelCase name: {userId}

Matching is case-insensitive.

Optional Path Parameters ​

New in 3.8.0

Optional path parameters were added in version 3.8.0.

Path parameters support the ASP.NET Core optional parameter syntax {param?}. When a path parameter is marked as optional and the corresponding PostgreSQL function parameter has a default value, omitting the URL segment will use the PostgreSQL default:

sql
sql
create function get_item(p_id int default 42)
returns text
language sql
begin atomic;
select p_id::text;
end;

comment on function get_item(int) is '
HTTP GET /items/{p_id?}
';
  • GET /items/5 → uses the provided value 5
  • GET /items/ → uses the PostgreSQL default 42

This also works with query_string_null_handling null_literal to pass NULL via the literal string "null" in the path for any parameter type:

sql
sql
create function get_item(p_id int default null)
returns text
language sql
begin atomic;
select p_id::text;
end;

comment on function get_item(int) is '
HTTP GET /items/{p_id}
query_string_null_handling null_literal
';
  • GET /items/null → passes SQL NULL to the function

Behavior ​

  • Overrides the auto-generated path
  • Path should start with / for absolute paths
  • Can be used alongside HTTP annotation
  • Path parameters can be combined with query string or body parameters
  • Optional path parameters ({param?}) use the PostgreSQL default when the URL segment is omitted
  • HTTP - Define endpoint (can also set path)

Comments