Skip to content
אצלי
Go back

Um cliente de API dentro do Standard Notes, com sintaxe .http e criptografia ponta a ponta

Updated:
Editor API Client dentro do Standard Notes no tema escuro, com requisições em sintaxe .http à esquerda e, à direita, as variáveis e a resposta de um GET no jsonplaceholder com status, tempo, cabeçalhos e corpo

Também disponível em inglês: An API client inside Standard Notes, with .http syntax and end-to-end encryption.

Uso o Standard Notes desde abril de 2024, como contei no Hora do café #3. É um app de notas gratuito, open source e com criptografia ponta a ponta, e dá para estendê-lo com editores customizados.

O StandardNotes-APIclient é um desses editores: um cliente de API HTTP em que as requisições ficam no corpo da nota, em texto puro. Tokens, payloads e variáveis herdam a criptografia ponta a ponta do resto dos seus dados, algo que os clientes REST web normalmente não oferecem.

Standard Notes com o editor API Client aberto sobre a nota "demo", tema claro. À esquerda, o texto em sintaxe .http, com as variáveis @host e @token e três blocos: Echo POST, Status check e CRUD example. À direita, o botão Run all, as variáveis com o token mascarado e os três blocos, cada um com os botões Run e Copy as cURL. O POST no httpbin.org já foi executado e mostra 200 em 1280 ms, 791 bytes, um botão Copy body, dois cabeçalhos recolhíveis e o corpo em JSON

Como funciona

O formato é o .http, o mesmo do REST Client do VS Code e do kulala.nvim. A nota inteira é um arquivo assim:

@host = https://httpbin.org
@token = your-secret-token

### Echo POST
POST {{host}}/post
Content-Type: application/json

{"plugin": "standardnotes-apiclient"}

### Status check
GET {{host}}/status/201
Authorization: Bearer {{token}}

Cada ### Título abre um bloco. A linha da requisição é MÉTODO url, e uma URL sozinha vira GET; linhas que começam com ? ou & logo depois dela continuam a query string. Variáveis se declaram com @nome = valor e entram com {{nome}}, e uma variável pode referenciar as anteriores. Ambientes também ficam no arquivo: @nome.staging = valor cria o valor para staging, e @env = staging define o ativo. Na lista de variáveis, os valores de nomes que contêm token, secret, key, password ou auth ficam mascarados até você apertar show.

O botão Run de cada bloco executa só aquela requisição, e a resposta aparece logo abaixo: status colorido, tempo, tamanho, cabeçalhos recolhíveis e corpo. Imagens ganham pré-visualização e as demais respostas binárias podem ser baixadas. Uma requisição em andamento pode ser cancelada, o tempo limite é de 30 segundos, e # @timeout 5000 muda isso para uma requisição, em milissegundos. As respostas ficam só em memória, nunca são gravadas na nota, e o texto da nota não é alterado por uma execução. Ctrl/Cmd+Enter no texto executa a requisição sob o cursor. O texto tem realce da sintaxe .http, e corpos multipart e GraphQL ganham um realce próprio.

A mesma nota no tema escuro. O texto à esquerda em roxo e verde, o token agora visível por inteiro na lista de variáveis, e o bloco CRUD example executado contra o jsonplaceholder: 200 em 126 ms, 292 bytes, quatro cabeçalhos e o JSON do post

Como tudo é texto, a busca global do Standard Notes encontra uma requisição pela URL, pelo nome de um cabeçalho ou pelo título do bloco, sem abrir o editor. E um export da nota continua legível em qualquer outro cliente que fale .http.

Encadeamento e verificações

Requisições podem alimentar umas às outras. Uma linha # @name login dá um nome à requisição e, depois que ela roda, as seguintes podem ler a resposta registrada: {{login.response.body.$.json.token}} pega um campo (um subconjunto de JSONPath: $, .campo, [índice] e [*]) e {{login.response.headers.X-Token}} pega um cabeçalho. {{login.request.body}} e {{login.request.headers.X}} leem a requisição como ela foi enviada, com as variáveis já resolvidas. As referências são resolvidas na hora da execução e nunca são gravadas na nota.

### Login
# @name login
POST {{host}}/post
Content-Type: application/json

{"token": "abc123"}

### Use the token
GET {{host}}/bearer
Authorization: Bearer {{login.response.body.$.json.token}}
# @assert status == 200
# @assert body.$.token exists

O Run all executa todas as requisições na ordem do arquivo, esperando cada uma, de modo que uma requisição encadeada lê a resposta da anterior, e para na primeira falha.

As linhas # @assert, no estilo do kulala.nvim, são conferidas contra a resposta e aparecem como passou ou falhou. O lado esquerdo pode ser status, headers.<nome>, body ou body.$.caminho, e os operadores são ==, !=, >, <, >=, <=, exists e not exists. Uma asserção malformada nunca passa em silêncio.

As variáveis dinâmicas são geradas a cada execução e nunca salvas: {{$uuid}}, {{$timestamp}}, {{$randomInt 1 10}} e {{$datetime}}.

Levando as requisições para fora

O Copy as cURL de um bloco copia a requisição como um comando curl, com as variáveis já resolvidas e cada valor entre aspas para o shell, e o Copy as HTTPie faz o mesmo como um comando http. O Copy OpenAPI copia todas as requisições da nota como um documento OpenAPI 3.1: uma operação por bloco, com a query string e os cabeçalhos como parâmetros e o corpo como exemplo.

Algumas coisas menores. O bloco avisa sobre variáveis não resolvidas e sobre cabeçalhos que o navegador nunca envia, como Host ou Cookie. Dá para chegar aos blocos pelo teclado, com Tab e as setas.

Instalação

  1. No Standard Notes (web ou desktop), abra Preferences, depois Plugins.

  2. No fim da página, cole a URL abaixo em Install Custom Plugin:

    https://esli.cafe/StandardNotes-APIclient/ext.json
  3. Crie uma nota, abra o menu Editor e escolha API Client.

Uma nota vazia mostra o botão Add sample, que preenche o texto com requisições de exemplo contra o httpbin.org e o jsonplaceholder. Funciona nos apps web, desktop e mobile; em telas estreitas o texto e as requisições ficam empilhados. Quem quiser só ver funcionando pode usar a demo online, sem instalar nada. Nela o texto fica no localStorage do navegador.

Limites

As requisições saem do navegador (ou do app desktop), então só endpoints com CORS habilitado respondem direto do editor. Para os demais, o README lista um proxy local companion como planejado, e ele ainda não saiu. Enquanto isso, é preciso usar um endpoint que mande os cabeçalhos CORS.

Executar uma requisição manda, claro, a requisição descrita para o endpoint de destino. Fora isso, nada é armazenado nem transmitido para outro lugar.

Como foi feito

É React 18 e TypeScript, com build pelo Vite, sobre o editor-kit do Standard Notes, que entrega a nota ao editor e salva de volta. O painel do texto é o CodeMirror 6, com um realce StreamLanguage escrito para o .http, corpos multipart e GraphQL incluídos. O parser que divide a nota em blocos, variáveis, ambientes e asserts é TypeScript puro, sem dependências, e as requisições saem pelo fetch do navegador, com um AbortController por trás tanto do botão de cancelar quanto do tempo limite. A Content Security Policy da página só permite scripts da origem do próprio plugin; as conexões ficam abertas, já que mandar requisições para qualquer lugar é o objetivo. Os testes unitários rodam no Vitest, com testes de propriedade do fast-check para o parser e o realce, e o Playwright conduz o plugin compilado por um host falso do Standard Notes, incluindo a origem opaca e a CPU mais lenta do app mobile.

O plugin está na v1.0.1, licença AGPL-3.0, e o código fica em github.com/Esl1h/StandardNotes-APIclient.


Share this post on:

Previous Post
Music notation in Standard Notes: ABC, ChordPro and alphaTex
Next Post
Kanban dentro do Standard Notes, com o board salvo em Markdown