API internal catch-all function

[ppKrauss]

Existem duas estratégias para implementar a resolução de parâmetros GET por regular expression:

1. enviando a string inteira para uma "função catch-all" que faz o dispatch.
   Uma eventual vantagem é o tratamento centralizado de erros; a desvantagem é uma pequena perda de performance.
2. gerando automaticamente o script NGINX com cada uma das resoluções.
   As vantagens seriam performance e gradualidade (permite automação mais tardia).

A estratégia 1 foi utilizada no primeiro rascunho do projeto. A estratégia 2 parecia ser a melhor, todavia não foi encontrada solução compacta no NGINX para resolver os 3 casos distintos (CSV/JSON/HTM). Tendo isso em vista, voltamos à estratégia inicial.

---

Problemas:

1. PostgREST v7 está sem suporte para CSV de JSON array;
2. funções que retornam tabelas precisariam ser submetidas ao select to_jsonb(t) from f($1) t e depois agregadas como array jsonb. Ainda assim não tem como retornar CSV nas condições atuais.
3. Problemas clássicos de função retornando setof record, surgem com jsonb_populate_record e jsonb_to_record. Não tem como retornar "tipo record" para o CSV pois não existe tipo genérico.
4. O NGINX também tem os seus problemas, apesar de menores.

[ppKrauss]

Solução meio gambiarra: organizar catch-all functions por tipo de retorno: se o tipo é o mesmo, o PostgreSQL permite usar uma só função com CASE para as demais.

1. criar no esquema API da base SQL as funções uri_dispatch_x() agrupadoras de saída.
2. criar no script NGINX os locations agrupadores de sintaxe e parametrização.
3. revisar o sufixo x das funções uri_dispatch_x() para que sua sintaxe possa ser resolvida no NGINX.

[ppKrauss]

Outra opção....

• manter uso de cath-all apenas para retorno JSON e funções temporárias ou mais simples.

• usar parametrização padronizada, api.f(uri text, args text).

• manter uso de retornos tabulares padronizados para simplificar descrição da API (lembrando que podemos fazer ?select=a,j->x para simplificações)... Ou seja, api.f(uri text, args text) RETURNS (LIKE api.ttpl_x).

• manter ideia de sintaxe de nome da função compatível com sintaxe do endpoint

[ppKrauss]

Resolvido no NGINX:

    # API /v1{formatoSaida}/{modulo}/{funcao}/{parametros}

    location ~ /v1(?:\.json)?/([a-z_][a-z0-9_]*)/([a-z_][a-z0-9_]*)/(.+) {
      proxy_pass http://localhost:3103/rpc/uridisp_$1_$2?p_uri=$3&$args;
    }
    location ~ /v1\.csv/([a-z_][a-z0-9_]*)/([a-z_][a-z0-9_]*)/(.+) {
      proxy_set_header Accept 'text/csv';
      proxy_pass http://localhost:3103/rpc/uridisp_$1_$2?p_uri=$3&$args;
    }

E resolvido no Postgresql, mantendo

• em https://github.com/AddressForAll/WS/tree/master/src/step01-ini.sql as inicializações globais
• em https://github.com/AddressForAll/WS/tree/master/src/step02-api.sql todas as tabelas-template dos retornos da API, todas as funções essenciais de uso do esquema API (ex. api.uri_dispatch_parser()), e todas as "funções globais", relativas a módulos multi-projeto.
• demais funções de API, a cada respectivo projeto-módulo.

Exemplos do módulo Eclusa do Projeto DigitalPreservation:

• http://api.addressforall.org/v1/eclusa/checkuserfiles_step1/igor/1
• http://api.addressforall.org/v1/eclusa/checkuserfiles_step2/igor?limit=2&select=cityname,ctype,fname,is_valid,fmeta-%3E%3Ehash

[ppKrauss]

Fechando a arquitetura em conformidade com http://addressForAll.org/api e step01-iniApi.sql
... usar api.addressforall.org/v1.json/ como listagem de urls ou de endpoints, ver https://api.github.com/
equanto request json de api.addressforall.org retorna versoes e demais metodos.

Outro problema, o fetch() do Javascript nao permite CORS (? ver fetch-crossorigin), ou algo se passa com /rpc NGINX vs /_sql direto .... Aceitou http://api-test.addressforall.org/_sql/origin_agg1 mas nao aceitou http://api-test.addressforall.org/_sql . Passou a aceitar com mode:no-cors mas dai dando erro "Uncaught (in promise) SyntaxError: JSON.parse: unexpected end".

[ppKrauss]

Por hora temos 3 motivacoes para a funcoes de RPC com sintaxe de filtragem no NGINX:

1. Falha conceitual do PostgREST, que nao permite fazer "row filtering" (WHERE) sobre elementos ausentes do SELECT
2. Falha no parser do PostgREST conforme "No function matches the given name" on valid condiction for the RPC returning table PostgREST/postgrest-docs#359
3. Demanda interna do projeto por condicoes complexas (WHERE complexo), viabilizando o recurso para o usuario final.

[0e1]

Tentando agrupar assuntos correlatos, trouxe AddressForAll/specifications#9 e #32 de Novembro/2021 para cá:

Portuguese

É necessário regrar um pouco melhor a oferta de APIs de cada domínio... Sugere-se mais ou menos o seguinte:

1. API implementada por um período de teste em modo teste, para comprovar que não tem "efeitos colaterais" no servidor, e que contempla ambos, a especificação técnica inicial e as necessidades reais de quem usa.

2. Controle dos nomes de API através de versionamento e jurisdição. Por exemplo a API do batista seria versão 1 (v1) da Colômbia, então o nome seria algo como API.addressforall.org/v1/CO/search

3. Controle interno dos nomes de função no PostgreSQ/PostgREST, dentro do SQL-schema API: o acesso GET e POST se faz no NGINX por algo como
   proxy_pass http://localhost:$porta/rpc/uridisp_$1_$2?p_uri=$3&$args onde $1 é o módulo funcional (ex. addressfind), $2 o nome da API (ex. search), $3 o parâmetro default contendo o "resto do path na URL" e em $args os demais parâmetros, quando houverem. A declaração de função será sempre seguindo o template CREATE FUNCTION api.uridisp_{module}_{name}(p_uri text, {args}) RETURNING jsonb .... IMMUTABLE.

Nesta issue discutiremos diretamente o draft da documentação e a sua implementação final.

---

Depois de avançar na discussão, AddressForAll/specifications#9

1. Revisar o README.md para que passe a ser conteúdo de /docs
2. Criar em /docs/address-endpoints.md o rascunho da especificação.
3. Criar exemplos de caso aderentes à proposta para testar as especificações
4. Fechar a primeira versão.