protos/pogo0.437.0

API

O esquema, os ficheiros .proto, os descritores compilados e a tabela de métodos RPC por HTTP, para scripts e outras ferramentas: o que cada rota devolve e um comando para a experimentar.

O essencial

Tudo o que o site mostra também é servido por HTTP simples: o esquema em JSON, os ficheiros .proto gerados, os descritores compilados e a tabela de métodos RPC. Ler não pede chave nem autenticação.

As rotas que dependem da versão do jogo aceitam ?v=<versão> (ou ?version=); sem ele respondem com a mais recente. Uma versão que o site não tem cai para a mais recente, exceto em /data/schema.json, que responde 404.

As respostas trazem um ETag. Devolve-o em If-None-Match e um ficheiro que não mudou custa um 304 sem corpo, o que torna barato verificar de tempos a tempos.

URL base https://protos.chung.pt

Mais rotas com a chave de API

As rotas que gerem o site só são listadas a quem tem a chave de API. Escreve-a para as ver e para as executar a partir desta página. Fica só neste separador e é esquecida quando o fechas.

Esquema

A reconstrução inteira num só ficheiro JSON: cada mensagem com os seus campos e números, cada enum com os seus valores, e os métodos RPC. É o que a pesquisa do explorador e o descodificador carregam no browser.

GET/data/schema.json

Cerca de 1,8 MB de JSON, servido em brotli ou gzip quando o cliente os aceita (cerca de 210 KB). Com v explícito a resposta pode ficar em cache um dia.

Parâmetros
v
Versão do jogo. Versões desconhecidas respondem 404.
curl --compressed "https://protos.chung.pt/data/schema.json?v=0.437.0" -o schema.json
GET

GET/api/diff

O que mudou entre duas versões: resumo em JSON estruturado por omissão, ou diff .proto unificado (format=proto ou format=golbat). Por omissão compara to (a mais recente) com a versão imediatamente anterior.

Parâmetros
from
Versão base. Por omissão, a versão anterior a to.
to
Versão alvo. Por omissão, a mais recente.
format
json (omissão), proto (diff unificado do vbase.proto), ou golbat (diff unificado no formato Golbat).
curl "https://protos.chung.pt/api/diff?to=0.437.0&format=proto"
GET

Ficheiros .proto

O código .proto gerado a partir do esquema: ficheiro a ficheiro, tudo num só, ou em zip.

GET/protos/<ficheiro>.proto

Um dos ficheiros gerados da versão mais recente, por exemplo adventuresync_android.proto. Os nomes são os que vêm no zip.

curl -O "https://protos.chung.pt/protos/adventuresync_android.proto"
GET

GET/protos/vbase.proto

Todas as mensagens e enums num só ficheiro, para ferramentas que querem um esquema único.

curl -O "https://protos.chung.pt/protos/vbase.proto"
GET

GET/protos/pogo-protos-<versão>.zip

Todos os ficheiros da versão mais recente, incluindo o vbase.proto.

curl -O "https://protos.chung.pt/protos/pogo-protos-0.437.0.zip"
GET

GET/protos/v/<versão>/<ficheiro>

Os mesmos ficheiros para uma versão concreta (em cache durante 60 segundos).

curl -O "https://protos.chung.pt/protos/v/0.437.0/vbase.proto"
GET

Descritores e métodos RPC

Formas compiladas do esquema, feitas para o Traffic Light mas úteis a tudo o que descodifica tráfego: um descritor binário, o módulo Python e a tabela de métodos RPC.

GET/trafficlight/info

O que existe para uma versão: contagens, o URL de cada ficheiro, o tamanho e o SHA-256, e a configuração de que o Traffic Light precisa.

Parâmetros
v
Versão do jogo.
curl "https://protos.chung.pt/trafficlight/info"
GET

GET/trafficlight/pogo.desc

Um FileDescriptorSet binário, como o que protoc --descriptor_set_out escreve. Carrega-o para descodificar mensagens sem compilar nada.

Parâmetros
v
Versão do jogo.
curl -O "https://protos.chung.pt/trafficlight/pogo.desc"
GET

GET/trafficlight/methods.json

O id, name, request_message e response_message de cada método RPC, dentro de um objeto com version, updated_at e total_methods.

Parâmetros
v
Versão do jogo.
format=raw
Só a lista de métodos, sem o objeto à volta.
curl "https://protos.chung.pt/trafficlight/methods.json?format=raw"
GET

GET/trafficlight/pogo_pb2.py

O módulo Python gerado por protoc --python_out.

Parâmetros
v
Versão do jogo.
curl -O "https://protos.chung.pt/trafficlight/pogo_pb2.py"
GET

GET/trafficlight/v/<versão>/<ficheiro>

Os mesmos ficheiros com a versão no caminho, para configurações que não aceitam query string. <ficheiro> é pogo.desc, methods.json, pogo_pb2.py ou vbase.proto.

curl -O "https://protos.chung.pt/trafficlight/v/0.437.0/pogo.desc"
GET

GET/trafficlight

Uma página com a lista acima, para pessoas. Clientes que pedem JSON (Accept: application/json, ou ?json) recebem o mesmo que em /trafficlight/info.

curl "https://protos.chung.pt/trafficlight?json"
GET

Golbat

vbase.proto único formatado para o Golbat (option go_package = "golbat.com/pogo";, tipos Internal*/Titan* deduplicados e convenção Golbat nos nomes dos valores de enum para protoc --go_out).

GET/golbat/vbase.proto

vbase.proto compatível com o Golbat para a versão mais recente, pronto para o updateproto.sh ou protoc --go_out.

curl -O "https://protos.chung.pt/golbat/vbase.proto"
GET

GET/golbat/v/<versão>/vbase.proto

O mesmo vbase.proto compatível com o Golbat para uma versão concreta. Responde 404 se a versão não estiver instalada.

curl -O "https://protos.chung.pt/golbat/v/0.437.0/vbase.proto"
GET

GET/golbat/diff

Diff .proto unificado entre duas versões no formato vbase.proto do Golbat (option go_package, nomes de enums). Por omissão compara to (a mais recente) com a versão anterior.

Parâmetros
from
Versão base. Por omissão, a versão anterior a to.
to
Versão alvo. Por omissão, a mais recente.
curl "https://protos.chung.pt/golbat/diff?to=0.437.0"
GET

Geração de código

Código Go e JSON gerados a partir da tabela de métodos RPC, prontos a escrever nos projetos que os usam.

GET/api/codegen

O índice: a versão servida, quantos métodos tem, as versões disponíveis e o URL de cada destino.

Parâmetros
v
Versão do jogo.
curl "https://protos.chung.pt/api/codegen"
GET

GET/api/codegen/controller-methods.go

Constantes dos métodos, String() e mapas de consulta, para controller/pogo/methods.go. Também responde em /api/codegen/methods.go.

Parâmetros
v
Versão do jogo.
download=1
Envia-o como anexo.
curl -s "https://protos.chung.pt/api/codegen/controller-methods.go" > controller/pogo/methods.go
GET

GET/api/codegen/methods.json

A tabela de métodos com version, updated_at e total_methods.

Parâmetros
v
Versão do jogo.
curl "https://protos.chung.pt/api/codegen/methods.json"
GET

Referência em HTML

Uma única página HTML que documenta todas as mensagens e enums, gerada a partir dos ficheiros .proto.

GET/docs/pogoprotos-doc.html

A página gerada. /docs redireciona para aqui.

curl -O "https://protos.chung.pt/docs/pogoprotos-doc.html"
GET

GET/api/doc

Se a página existe para uma versão, e onde a ler.

Parâmetros
version
Versão do jogo.
curl "https://protos.chung.pt/api/doc"
GET