Introdução

O que é o GO?

O GO é um conjunto de aplicações web que pretende responder às principais necessidades operacionais de equipas que gerem redes de transporte público. No diagrama está resumido o principal fluxo de informação que permite desenhar, operar e analisar transportes públicos em escala e num modelo de melhoria contínua.

Versões

O API é versionado para permitir o desenvolvimento de novas funcionalidades sem comprometer a compatibilidade com sistemas que dependem das estruturas de dados de versões anteriores.

Uma vez que todas as respostas são JSON, adicionar novas propriedades aos endpoints não é considerado uma alteração significativa, pois estas propriedades podem ser ignoradas com segurança pelos consumidores. Portanto, nesses casos, a versão pode não ser alterada. Esta abordagem parece-nos equilibrada pois permite-nos introduzir melhorias mais rapidamente enquanto minimizamos o impacto nas integrações existentes.

Estrutura uniforme da resposta

Todas as respostas do API seguem a especificação JSend. Esta estrutura padronizada garante a consistência em todos os endpoints e fornece uma framework para incluir informações adicionais de debugging quando necessário.

Em caso de erros, o formato JSend oferece uma forma clara e estruturada de descrever o que correu mal e, quando possível, como o problema poderá ser resolvido. Esta abordagem simplifica o tratamento de erros para os consumidores do API e melhora a developer experience do programador.

{
	status: "success",
	timestamp: 1721023200,
	data: [ ... ] or { ... } // The requested data
}

{
	status: "error",
	timestamp: 1721023200,
	message: "Unable to communicate with database"
}

TypeScript

A utilização de uma linguagem tipificada é fortemente recomendada. Para utilizadores de Typescript, fornecemos um pacote no NPM com tipos para todas as estruturas utilizadas. Decidimos utilizar Calendar Versioning para este pacote, pelo que apenas garantimos compatibilidade com a versão mais recente do API.