apostoldevel/module-PGHTTP

Provides the ability to receive and process HTTP requests using the PL/pgSQL programming language.

Postgres Fetch

PGHTTP - a module for Apostol.

Description

PGHTTP provides the ability to receive and process HTTP requests using the PL/pgSQL programming language.

Incoming requests

The module directs incoming HTTP GET and POST requests to the PostgreSQL database by calling the http.get and http.post functions, respectively, to process them.

Incoming requests are recorded in the http.log table.

Database installation

Follow the instructions for installing PostgreSQL in the description of Apostol.

Module installation

Follow the instructions for building and installing Apostol.

General information

• Base endpoint URL: http://localhost:8080/api/v1;

  • The module only accepts requests whose path starts with /api (this can be changed in the source code).

• All endpoints return either a JSON object or a JSON array depending on the number of records in the response. This behavior can be changed by adding the ?data_array=true parameter to the request, in which case the response will be a JSON array regardless of the number of records.

• Endpoint URL format:

http[s]://<hosthame>[:<port>]/api/<route>

HTTP Status Codes

• HTTP 4XX status codes are used for client-side errors - the problem is on the client side.
• HTTP 5XX status codes are used for internal errors - the problem is on the server side. It is important NOT to consider this as a failure operation. The execution status is UNKNOWN and may be successful.

Passing Parameters

• For GET endpoints, parameters should be sent as a query string.
• For POST endpoints, some parameters can be sent as a query string, and some as a request body:
• The following content types are allowed when sending parameters as a request body:
  • application/x-www-form-urlencoded for query string;
  • multipart/form-data for HTML forms;
  • application/json for JSON.
• Parameters can be sent in any order.

Function Parameters

To handle a GET request:

/**
* @param {text} path - Path
* @param {jsonb} headers - HTTP headers
* @param {jsonb} params - Query parameters
* @return {SETOF json}
**/
CREATE OR REPLACE FUNCTION http.get (
  path      text,
  headers   jsonb,
  params    jsonb DEFAULT null
) RETURNS   SETOF json

To handle a POST request:

/**
* @param {text} path - Path
* @param {jsonb} headers - HTTP headers
* @param {jsonb} params - Query parameters
* @param {jsonb} body - Request body
* @return {SETOF json}
**/
CREATE OR REPLACE FUNCTION http.post (
  path      text,
  headers   jsonb,
  params    jsonb DEFAULT null,
  body      jsonb DEFAULT null
) RETURNS   SETOF json