NpgsqlRest

Appearance

Comments
Written with Claude
IMPORTANT

As you may notice, this page and pretty much the entire website were obviously created with the help of AI. I wonder how you could tell? Was it a big "Written With Claude" badge on every page? I moved it to the top now (with the help of AI of course) to make it even more obvious. There are a few blogposts that were written by me manually, the old-fashioned way, I hope there will be more in the future, and those have a similar "Human Written" badge. This project (not the website), on the other hand, is a very, very different story. It took me more than two years of painstaking and unpaid work in my own free time. A story that, hopefully, I will tell someday. But meanwhile, what would you like me to do? To create a complex documentation website with a bunch of highly technical articles with the help of AI and fake it, to give you an illusion that I also did that manually? Like the half of itnernet is doing at this point? How does that makes any sense? Is that even fair to you? Or maybe to create this website manually, the old-fashioned way, just for you? While working a paid job for a salary, most of you wouldn't even get up in the morning. Would you like me to sing you a song while we're at it? For your personal entertainment? Seriously, get a grip. Do you find this information less valuable because of the way this website was created? I give my best to fix it to keep the information as accurate as possible, and I think it is very accurate at this point. If you find some mistakes, inaccurancies or problems, there is a comment section at the bottom of every page, which I also made with the help of the AI. And I woould very much appreciate if you leave your feedback there. Look, I'm just a guy who likes SQL, that's all. If you don't approve of how this website was constructed and the use of AI tools, I suggest closing this page and never wever coming back. And good riddance. And I would ban your access if I could know how. Thank you for your attention to this matter.

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';

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