Annotations Guide

Edit this page on GitHub

BufferRows

bufferrows number                                          
buffer_rows number                                         
buffer-rows number                                         
buffer number
bufferrows number                                          
buffer_rows number                                         
buffer-rows number                                         
buffer number

Sets the buffered amount of rows before they are written to the response for this endpoint.

Tags

for tag1, tag2, tag3 [, ...]                               
tag tag1, tag2, tag3 [, ...]                               
tags tag1, tag2, tag3 [, ...]
for tag1, tag2, tag3 [, ...]                               
tag tag1, tag2, tag3 [, ...]                               
tags tag1, tag2, tag3 [, ...]

All annotations in lines below this line apply only to tags in the argument list.

Disabled

disabled                                                   
disabled [ tag1, tag2, tag3 [, ...] ]
disabled                                                   
disabled [ tag1, tag2, tag3 [, ...] ]

The endpoint is disabled. Optional tag list disabled only for tags in the argument list.

Enabled

enabled                                                    
enabled [ tag1, tag2, tag3 [, ...] ]
enabled                                                    
enabled [ tag1, tag2, tag3 [, ...] ]

The endpoint is enabled. Optional tag list enabled only for tags in the argument list.

HTTP

HTTP                                                       
HTTP [ GET | POST | PUT | DELETE ]                         
HTTP [ GET | POST | PUT | DELETE ] path
HTTP                                                       
HTTP [ GET | POST | PUT | DELETE ]                         
HTTP [ GET | POST | PUT | DELETE ] path

HTTP settings:

  • Use HTTP annotation to enable when running in CommentsMode.OnlyWithHttpTag option.
  • Change the HTTP method with the optional second argument.
  • Change the HTTP path with the optional third argument.

RequestParamType

requestparamtype [ [ querystring | query_string | query-string | query ]   |   [ bodyjson | body_json | body-json | json | body ] ]
paramtype  [ [ querystring | query_string | query-string | query ]   |   [ bodyjson | body_json | body-json | json | body ] ]
request_param_type  [ [ querystring | query_string | query-string | query ]   |   [ bodyjson | body_json | body-json | json | body ] ]
param_type  [ [ querystring | query_string | query-string | query ]   |   [ bodyjson | body_json | body-json | json | body ] ]
request-param-type  [ [ querystring | query_string | query-string | query ]   |   [ bodyjson | body_json | body-json | json | body ] ]
param-type  [ [ querystring | query_string | query-string | query ]   |   [ bodyjson | body_json | body-json | json | body ] ]
requestparamtype [ [ querystring | query_string | query-string | query ]   |   [ bodyjson | body_json | body-json | json | body ] ]
paramtype  [ [ querystring | query_string | query-string | query ]   |   [ bodyjson | body_json | body-json | json | body ] ]
request_param_type  [ [ querystring | query_string | query-string | query ]   |   [ bodyjson | body_json | body-json | json | body ] ]
param_type  [ [ querystring | query_string | query-string | query ]   |   [ bodyjson | body_json | body-json | json | body ] ]
request-param-type  [ [ querystring | query_string | query-string | query ]   |   [ bodyjson | body_json | body-json | json | body ] ]
param-type  [ [ querystring | query_string | query-string | query ]   |   [ bodyjson | body_json | body-json | json | body ] ]

Set how request parameters are sent - query string or JSON body.

RequiresAuthorization

requiresauthorization                                      
authorize                                                  
requires_authorization                                     
requires-authorization                                     
requiresauthorization [ role1, role2, role2 [, ...] ]      
authorize [ role1, role2, role2 [, ...] ]                  
requires_authorization [ role1, role2, role2 [, ...] ]     
requires-authorization [ role1, role2, role2 [, ...] ]
requiresauthorization                                      
authorize                                                  
requires_authorization                                     
requires-authorization                                     
requiresauthorization [ role1, role2, role2 [, ...] ]      
authorize [ role1, role2, role2 [, ...] ]                  
requires_authorization [ role1, role2, role2 [, ...] ]     
requires-authorization [ role1, role2, role2 [, ...] ]

Require authorization for this endpoint.

  • If the user is not authorized and authorization is required, the endpoint will return the status code 401 Unauthorized.
  • If the user is authorized but not in any of the roles required by the authorization, the endpoint will return the status code 403 Forbidden.

AllowAnonymous

allowanonymous                                               
allow_anonymous                                              
allow-anonymous                                              
anonymous                                                    
anon
allowanonymous                                               
allow_anonymous                                              
allow-anonymous                                              
anonymous                                                    
anon

Allow anonymous access with no authorization to this endpoint.

CommandTimeout

commandtimeout seconds                                       
command_timeout seconds                                      
command-timeout seconds                                      
timeout seconds
commandtimeout seconds                                       
command_timeout seconds                                      
command-timeout seconds                                      
timeout seconds

Set the command execution timeout in seconds.

RequestHeadersMode

requestheadersmode [ ignore | context | parameter ]          
request_headers_mode [ ignore | context | parameter ]        
request-headers-mode [ ignore | context | parameter ]        
requestheaders [ ignore | context | parameter ]              
request_headers [ ignore | context | parameter ]             
request-headers [ ignore | context | parameter ]
requestheadersmode [ ignore | context | parameter ]          
request_headers_mode [ ignore | context | parameter ]        
request-headers-mode [ ignore | context | parameter ]        
requestheaders [ ignore | context | parameter ]              
request_headers [ ignore | context | parameter ]             
request-headers [ ignore | context | parameter ]

Set how request parameters are handled:

  • Ignore: do not send request headers.
  • Context: Request headers are set as the session variable under request.headers key.
  • Parameter: Request headers are set as a default parameter defined with RequestHeadersParameterName.

RequestHeadersParameterName

requestheadersparametername name                
requestheadersparamname name                    
request_headers_parameter_name name             
request_headers_param_name name                 
request-headers-parameter-name name             
request-headers-param-name name
requestheadersparametername name                
requestheadersparamname name                    
request_headers_parameter_name name             
request_headers_param_name name                 
request-headers-parameter-name name             
request-headers-param-name name

When RequestHeadersMode is set to send request headers as a parameter, set the existing parameter name. The default is headers.

BodyParameterName

bodyparametername name                          
body-parameter-name name                        
body_parameter_name name                        
bodyparamname name                              
body-param-name name                            
body_param_name name
bodyparametername name                          
body-parameter-name name                        
body_parameter_name name                        
bodyparamname name                              
body-param-name name                            
body_param_name name

Set the name of the existing parameter which is sent as body content. When the BodyParameterName is set, all other parameters are sent by the query string.

ResponseNullHandling

responsenullhandling [ emptystring | nullliteral | nocontent ]         
response_null_handling [ emptystring | nullliteral | nocontent ]       
response-null-handling [ emptystring | nullliteral | nocontent ]
responsenullhandling [ emptystring | nullliteral | nocontent ]         
response_null_handling [ emptystring | nullliteral | nocontent ]       
response-null-handling [ emptystring | nullliteral | nocontent ]

Sets the response NULL handling option for a single function results other than JSON (text, number, etc...):

  • EmptyString: Empty content response. This is the default.
  • NullLiteral: Content is the null string.
  • NoContent: Response is HTTP 204 No Content status response code.

QueryStringNullHandling

querystringnullhandling [ emptystring | nullliteral | ignore ]        
query_string_null_handling [ emptystring | nullliteral | ignore ]     
query-string-null-handling [ emptystring | nullliteral | ignore ]
querystringnullhandling [ emptystring | nullliteral | ignore ]        
query_string_null_handling [ emptystring | nullliteral | ignore ]     
query-string-null-handling [ emptystring | nullliteral | ignore ]

Sets the response NULL handling option for the query string parameters:

  • EmptyString: Empty query string is interpreted as the NULL value parameter.
  • NullLiteral: The literal value null (case insensitive) in the query string is interpreted as the NULL value parameter.
  • Ignore: Doesn't handle NULL parameters in query strings. This is the default.

Headers

key: value
key: value

Any line containing a: character is interpreted as the request header key and value where the key is the left side and the value is the right side string. For example: Content-Type: text/html

Login

login                                           
signin
login                                           
signin

This annotation will transform the routine into the authentication endpoint that performs the sign-in operation.

See more information on how the login endpoints work on the login endpoints documentation page.

Logout

logout                                          
signout
logout                                          
signout

This annotation will transform the routine into the endpoint that performs the logout or the sign-out operation.

If the routine doesn't return any data, the default authorization scheme is signed out. Any values returned will be interpreted as scheme names (converted to string) to sign out.

For more information on the login and the logout see the login endpoints documentation page.

Raw

raw
raw

Sets response to a "raw" mode. HTTP response is written exactly as it is received from PostgreSQL (raw mode).

This is useful for creating CSV responses automatically. For example:

create function raw_csv_response1() 
returns setof text
language sql
as 
$$
select trim(both '()' FROM sub::text) || E'\n' from (
values 
    (123, '2024-01-01'::timestamp, true, 'some text'),
    (456, '2024-12-31'::timestamp, false, 'another text')
)
sub (n, d, b, t)
$$;
comment on function raw_csv_response1() is '
raw
Content-Type: text/csv
';
create function raw_csv_response1() 
returns setof text
language sql
as 
$$
select trim(both '()' FROM sub::text) || E'\n' from (
values 
    (123, '2024-01-01'::timestamp, true, 'some text'),
    (456, '2024-12-31'::timestamp, false, 'another text')
)
sub (n, d, b, t)
$$;
comment on function raw_csv_response1() is '
raw
Content-Type: text/csv
';

Produces the following response:

HTTP/1.1 200 OK                                                  
Connection: close
Content-Type: text/csv
Date: Tue, 08 Aug 2024 14:25:26 GMT
Server: Kestrel
Transfer-Encoding: chunked

123,"2024-01-01 00:00:00",t,"some text"
456,"2024-12-31 00:00:00",f,"another text"

Separator

separator [ separator_value ]
separator [ separator_value ]

Defines a standard separator between raw values. It only applies when raw is on.

NewLine

newline [ newline ]
newline [ newline ]

Defines a standard separator between raw value columns. It only applies when raw is on.

ColumnNames

columnnames                                     
column_names                                    
column-names
columnnames                                     
column_names                                    
column-names

If this option is set to true - and if the endpoint is int the "raw" mode - the endpoint will contain a header names. If separators are applied, they will be used also.

Comments