iframe-proxy | Sunbelt Computer Software

65 lines (65 loc) · 33.9 KB

import{_ as a,c as i,o as n,a5 as e}from"./chunks/framework.CgT1UzWm.js";const k=JSON.parse('{"title":"HTTP Annotation","titleTemplate":"NpgsqlRest","description":"Expose PostgreSQL functions, procedures, and SQL files as HTTP endpoints. Configure HTTP methods (GET, POST, PUT, DELETE, QUERY) and custom URL paths.","frontmatter":{"outline":[2,3],"title":"HTTP Annotation","titleTemplate":"NpgsqlRest","description":"Expose PostgreSQL functions, procedures, and SQL files as HTTP endpoints. Configure HTTP methods (GET, POST, PUT, DELETE, QUERY) and custom URL paths.","head":[["meta",{"name":"keywords","content":"npgsqlrest http annotation, postgresql http endpoint, rest api function, http method postgresql"}],["meta",{"property":"og:title","content":"NpgsqlRest HTTP Annotation"}],["meta",{"property":"og:description","content":"Expose PostgreSQL functions, procedures, and SQL files as HTTP endpoints with configurable methods and paths."}],["meta",{"property":"og:type","content":"article"}],["link",{"rel":"canonical","href":"https://npgsqlrest.github.io/annotations/http.html"}],["meta",{"property":"og:url","content":"https://npgsqlrest.github.io/annotations/http.html"}],["meta",{"property":"og:image","content":"https://npgsqlrest.github.io/og-image.png"}],["meta",{"name":"twitter:card","content":"summary_large_image"}],["meta",{"name":"twitter:title","content":"NpgsqlRest HTTP Annotation"}],["meta",{"name":"twitter:description","content":"Expose PostgreSQL functions, procedures, and SQL files as HTTP endpoints with configurable methods and paths."}],["meta",{"name":"twitter:image","content":"https://npgsqlrest.github.io/og-image.png"}]]},"headers":[],"relativePath":"annotations/http.md","filePath":"annotations/http.md","lastUpdated":1782480183000}'),t={name:"annotations/http.md"};function l(p,s,h,r,d,o){return n(),i("div",null,s[0]||(s[0]=[e(`<h1 id="http" tabindex="-1">HTTP <a class="header-anchor" href="#http" aria-label="Permalink to "HTTP""></a></h1>Expose a PostgreSQL function, procedure, or SQL file as an HTTP endpoint.<h2 id="keywords" tabindex="-1">Keywords <a class="header-anchor" href="#keywords" aria-label="Permalink to "Keywords""></a></h2><code>http</code><h2 id="syntax" tabindex="-1">Syntax <a class="header-anchor" href="#syntax" aria-label="Permalink to "Syntax""></a></h2><details class="code-collapsible" open><summary>code</summary><div class="language- vp-adaptive-theme line-numbers-mode"><button title="Copy Code" class="copy"></button><pre class="shiki shiki-themes catppuccin-latte catppuccin-mocha vp-code" tabindex="0"><code>HTTP

HTTP <method>

HTTP <path>

HTTP <method> <path></code></pre><div class="line-numbers-wrapper" aria-hidden="true">1 2 3 4 </div></div></details>method: <code>GET</code>, <code>POST</code>, <code>PUT</code>, <code>DELETE</code>, <code>QUERY</code><code>QUERY</code> is the recently standardized safe, idempotent HTTP method that carries the query in the request body: parameters default to the JSON body (like POST), while clients treat it as a cacheable read (the TypeScript client's React Query hooks map it to <code>useQuery</code>, MCP tools get <code>readOnlyHint: true</code>). Available since version 3.20.0. Note: QUERY endpoints are not representable in OpenAPI 3.0/3.1 documents and are skipped there with a logged warning.path: Custom URL path (must start with <code>/</code> or be a relative path)<h2 id="commentsmode-requirement" tabindex="-1">CommentsMode Requirement <a class="header-anchor" href="#commentsmode-requirement" aria-label="Permalink to "CommentsMode Requirement""></a></h2>The <code>HTTP</code> annotation behavior depends on the <a href="./../config/npgsqlrest.html#comments-mode">CommentsMode</a> configuration setting:<div class="table-container"><div class="table-wrapper"><table tabindex="0"><thead><tr><th>Mode</th><th>HTTP Annotation Behavior</th></tr></thead><tbody><tr><td><code>OnlyAnnotated</code></td><td>Required - Endpoints are only created for routines with <code>HTTP</code> in their comment (or a plugin annotation that requests an endpoint, such as <code>@mcp</code>). Default. <code>OnlyWithHttpTag</code> is a backward-compatible alias.</td></tr><tr><td><code>ParseAll</code></td><td>Optional - All routines become endpoints; <code>HTTP</code> can customize method/path.</td></tr><tr><td><code>Ignore</code></td><td>Ignored - All routines become endpoints; comments are not parsed.</td></tr></tbody></table></div></div>With the default <code>OnlyAnnotated</code> mode, a function without the <code>HTTP</code> annotation will not be exposed as an endpoint.<h2 id="default-behavior" tabindex="-1">Default Behavior <a class="header-anchor" href="#default-behavior" aria-label="Permalink to "Default Behavior""></a></h2>When method is not specified:<ul><li><code>GET</code> for non-volatile functions, or names starting with <code>get_</code>, containing <code>_get_</code>, or ending with <code>_get</code></li><li><code>POST</code> for all other functions</li></ul>When path is not specified, it's generated from the function name using the configured URL prefix and naming conventions.<h2 id="examples" tabindex="-1">Examples <a class="header-anchor" href="#examples" aria-label="Permalink to "Examples""></a></h2><h3 id="basic-endpoint" tabindex="-1">Basic Endpoint <a class="header-anchor" href="#basic-endpoint" aria-label="Permalink to "Basic Endpoint""></a></h3><details class="code-collapsible" open><summary>sql</summary><div class="language-sql vp-adaptive-theme line-numbers-mode"><button title="Copy Code" class="copy"></button>sql<pre class="shiki shiki-themes catppuccin-latte catppuccin-mocha vp-code" tabindex="0"><code>create function get_status()

returns text

language sql

begin atomic;

end;

comment on function get_status() is 'HTTP';</code></pre><div class="line-numbers-wrapper" aria-hidden="true">1 2 3 4 5 6 7 8 </div></div></details>Equivalent as a SQL file endpoint (<code>sql/get-status.sql</code>):<details class="code-collapsible" open><summary>sql</summary><div class="language-sql vp-adaptive-theme line-numbers-mode"><button title="Copy Code" class="copy"></button>sql<pre class="shiki shiki-themes catppuccin-latte catppuccin-mocha vp-code" tabindex="0"><code>-- HTTP

select 'OK';</code></pre><div class="line-numbers-wrapper" aria-hidden="true">1 2 </div></div></details>Creates: <code>GET /api/get-status</code><h3 id="explicit-http-method" tabindex="-1">Explicit HTTP Method <a class="header-anchor" href="#explicit-http-method" aria-label="Permalink to "Explicit HTTP Method""></a></h3><details class="code-collapsible" open><summary>sql</summary><div class="language-sql vp-adaptive-theme line-numbers-mode"><button title="Copy Code" class="copy"></button>sql<pre class="shiki shiki-themes catppuccin-latte catppuccin-mocha vp-code" tabindex="0"><code>create function create_user(_name text)

returns int

language sql

insert into users(name) values(_name) returning id;

end;

comment on function create_user(text) is 'HTTP POST';</code></pre><div class="line-numbers-wrapper" aria-hidden="true">1 2 3 4 5 6 7 8 </div></div></details>Creates: <code>POST /api/create-user</code><h3 id="custom-path" tabindex="-1">Custom Path <a class="header-anchor" href="#custom-path" aria-label="Permalink to "Custom Path""></a></h3><details class="code-collapsible" open><summary>sql</summary><div class="language-sql vp-adaptive-theme line-numbers-mode"><button title="Copy Code" class="copy"></button>sql<pre class="shiki shiki-themes catppuccin-latte catppuccin-mocha vp-code" tabindex="0"><code>create function get_all_users()

returns setof users

language sql

end;

comment on function get_all_users() is 'HTTP GET /users';</code></pre><div class="line-numbers-wrapper" aria-hidden="true">1 2 3 4 5 6 7 8 </div></div></details>Creates: <code>GET /users</code><h3 id="method-and-custom-path" tabindex="-1">Method and Custom Path <a class="header-anchor" href="#method-and-custom-path" aria-label="Permalink to "Method and Custom Path""></a></h3><details class="code-collapsible" open><summary>sql</summary><div class="language-sql vp-adaptive-theme line-numbers-mode"><button title="Copy Code" class="copy"></button>sql<pre class="shiki shiki-themes catppuccin-latte catppuccin-mocha vp-code" tabindex="0"><code>create function search_products(_query text)

returns setof products

language sql

select * from products where name ilike '%' || _query || '%';

end;

comment on function search_products(text) is 'HTTP GET /products/search';</code></pre><div class="line-numbers-wrapper" aria-hidden="true">1 2 3 4 5 6 7 8 </div></div></details>Creates: <code>GET /products/search</code><h3 id="multi-line-with-documentation" tabindex="-1">Multi-line with Documentation <a class="header-anchor" href="#multi-line-with-documentation" aria-label="Permalink to "Multi-line with Documentation""></a></h3><details class="code-collapsible" open><summary>sql</summary><div class="language-sql vp-adaptive-theme line-numbers-mode"><button title="Copy Code" class="copy"></button>sql<pre class="shiki shiki-themes catppuccin-latte catppuccin-mocha vp-code" tabindex="0"><code>comment on function get_user_profile(int) is

'Returns the complete user profile including preferences.

Used by the frontend dashboard.

HTTP GET /users/profile';</code></pre><div class="line-numbers-wrapper" aria-hidden="true">1 2 3 4 5 </div></div></details>The documentation text is ignored; only the <code>HTTP</code> line is parsed.<h3 id="unrecognized-method-becomes-path" tabindex="-1">Unrecognized Method Becomes Path <a class="header-anchor" href="#unrecognized-method-becomes-path" aria-label="Permalink to "Unrecognized Method Becomes Path""></a></h3><details class="code-collapsible" open><summary>sql</summary><div class="language-sql vp-adaptive-theme line-numbers-mode"><button title="Copy Code" class="copy"></button>sql<pre class="shiki shiki-themes catppuccin-latte catppuccin-mocha vp-code" tabindex="0"><code>comment on function my_endpoint() is 'HTTP custom-endpoint';</code></pre><div class="line-numbers-wrapper" aria-hidden="true">1 </div></div></details>Since <code>custom-endpoint</code> is not a valid HTTP method, it's treated as a path:Creates: <code>POST /custom-endpoint</code><h2 id="path-parameters" tabindex="-1">Path Parameters <a class="header-anchor" href="#path-parameters" aria-label="Permalink to "Path Parameters""></a></h2>You can define RESTful path parameters using the <code>{param}</code> syntax in URL paths. Parameter values are extracted directly from the URL path instead of query strings or request body.<h3 id="single-path-parameter" tabindex="-1">Single Path Parameter <a class="header-anchor" href="#single-path-parameter" aria-label="Permalink to "Single Path Parameter""></a></h3><details class="code-collapsible" open><summary>sql</summary><div class="language-sql vp-adaptive-theme line-numbers-mode"><button title="Copy Code" class="copy"></button>sql<pre class="shiki shiki-themes catppuccin-latte catppuccin-mocha vp-code" tabindex="0"><code>create function get_product(p_id int)

returns text

language sql

select ...;

end;

comment on function get_product(int) is 'HTTP GET /products/{p_id}';</code></pre><div class="line-numbers-wrapper" aria-hidden="true">1 2 3 4 5 6 7 8 </div></div></details>Call: <code>GET /products/123</code> → <code>p_id = 123</code><h3 id="multiple-path-parameters" tabindex="-1">Multiple Path Parameters <a class="header-anchor" href="#multiple-path-parameters" aria-label="Permalink to "Multiple Path Parameters""></a></h3><details class="code-collapsible" open><summary>sql</summary><div class="language-sql vp-adaptive-theme line-numbers-mode"><button title="Copy Code" class="copy"></button>sql<pre class="shiki shiki-themes catppuccin-latte catppuccin-mocha vp-code" tabindex="0"><code>create function get_review(p_id int, review_id int)

returns text

language sql

select ...;

end;

comment on function get_review(int, int) is 'HTTP GET /products/{p_id}/reviews/{review_id}';</code></pre><div class="line-numbers-wrapper" aria-hidden="true">1 2 3 4 5 6 7 8 </div></div></details>Call: <code>GET /products/5/reviews/10</code> → <code>p_id = 5</code>, <code>review_id = 10</code><h3 id="path-parameters-with-query-string" tabindex="-1">Path Parameters with Query String <a class="header-anchor" href="#path-parameters-with-query-string" aria-label="Permalink to "Path Parameters with Query String""></a></h3><details class="code-collapsible" open><summary>sql</summary><div class="language-sql vp-adaptive-theme line-numbers-mode"><button title="Copy Code" class="copy"></button>sql<pre class="shiki shiki-themes catppuccin-latte catppuccin-mocha vp-code" tabindex="0"><code>create function get_product_details(p_id int, include_reviews boolean default false)

returns text

language sql

select ...;

end;

comment on function get_product_details(int, boolean) is 'HTTP GET /products/{p_id}/details';</code></pre><div class="line-numbers-wrapper" aria-hidden="true">1 2 3 4 5 6 7 8 </div></div></details>Call: <code>GET /products/42/details?includeReviews=true</code> → <code>p_id = 42</code>, <code>include_reviews = true</code><h3 id="path-parameters-with-json-body" tabindex="-1">Path Parameters with JSON Body <a class="header-anchor" href="#path-parameters-with-json-body" aria-label="Permalink to "Path Parameters with JSON Body""></a></h3><details class="code-collapsible" open><summary>sql</summary><div class="language-sql vp-adaptive-theme line-numbers-mode"><button title="Copy Code" class="copy"></button>sql<pre class="shiki shiki-themes catppuccin-latte catppuccin-mocha vp-code" tabindex="0"><code>create function update_product(p_id int, new_name text)

returns text

language sql

select ...;

end;

comment on function update_product(int, text) is 'HTTP POST /products/{p_id}';</code></pre><div class="line-numbers-wrapper" aria-hidden="true">1 2 3 4 5 6 7 8 </div></div></details>Call: <code>POST /products/7</code> with body <code>{"newName": "New Name"}</code> → <code>p_id = 7</code>, <code>new_name = "New Name"</code><h3 id="path-parameter-key-features" tabindex="-1">Path Parameter Key Features <a class="header-anchor" href="#path-parameter-key-features" aria-label="Permalink to "Path Parameter Key Features""></a></h3><ul><li>Parameter names in <code>{param}</code> can use either the PostgreSQL name (<code>{p_id}</code>) or the converted camelCase name (<code>{pId}</code>), matching is case-insensitive</li><li>Works with all HTTP methods (GET, POST, PUT, DELETE, QUERY)</li><li>Can be combined with query string parameters (GET/DELETE) or JSON body parameters (POST/PUT/QUERY)</li><li>Supports all parameter types (int, text, uuid, bigint, etc.)</li><li>Zero performance impact on endpoints without path parameters</li></ul><h2 id="related" tabindex="-1">Related <a class="header-anchor" href="#related" aria-label="Permalink to "Related""></a></h2><ul><li><a href="./../config/npgsqlrest.html">NpgsqlRest Options configuration</a> - Configure URL prefixes, naming conventions</li><li><a href="./../guide/annotations.html">Comment Annotations Guide</a> - How annotations work</li><li><a href="./../guide/configuration.html">Configuration Guide</a> - How configuration works</li></ul><h2 id="related-annotations" tabindex="-1">Related Annotations <a class="header-anchor" href="#related-annotations" aria-label="Permalink to "Related Annotations""></a></h2><ul><li><a href="./path.html">PATH</a> - Alternative way to set custom path</li><li><a href="./authorize.html">AUTHORIZE</a> - Require authentication</li><li><a href="./request-param-type.html">REQUEST_PARAM_TYPE</a> - Control parameter source</li></ul>`,59)]))}const u=a(t,[["render",l]]);export{k as __pageData,u as default};

Sunbelt Computer Software

PL/B Language Development and Support

Navigation Menu

Uh oh!

Sunbelt Computer Software

PL/B Language Development and Support

Uh oh!

FilesExpand file tree

annotations_http.md.BDBFWX1o.js

Latest commit

History

annotations_http.md.BDBFWX1o.js

File metadata and controls