Documentação da API — Laboratório de Circuitos

Documentação da API — Laboratório de Circuitos

Fizicar — Laboratório em Realidade Aumentada

O Fizicar é um laboratório virtual desenvolvido em Unity que permite simular circuitos eléctricos em realidade aumentada, proporcionando uma experiência de aprendizagem prática, visual e intuitiva.

Descarregar Aplicação (Android)

Simula e aprende com circuitos reais

Introdução

Esta API permite criar sessões de circuito, adicionar componentes, ligar terminais e obter análise eléctrica.

• Token de Sessão

Os endpoints baseiam-se no token de sessão, para registo de todas operações.

• Tempo de Resposta

Latência < 200ms por operação.

• Versatilidade

A API permite manipulação dinâmica dos componentes e ligações.

Autenticação

A API pode operar sem credenciais em ambiente de testes. Em produção, use Bearer Token no cabeçalho Authorization.

Exemplo de cabeçalhos: Content-Type: application/json e Authorization: Bearer <token>.

Boas práticas

Use ids curtos para componentes (ex.: R1, V1).
Adote unidades SI no campo value (Ω, V, A conforme o tipo).
Garanta unicidade dos nós (nodeA, nodeB) na análise.
Persista o sessionId no cliente entre chamadas.

Endpoints

Sessões

POST /api/session

Inicia nova sessão de circuito e devolve identificador.

Exemplo

curl -X POST \
    -H "Content-Type: application/json" \
    http://fizicar.somee.com/api/session

Invoke-RestMethod -Method POST `
    -Uri 'http://fizicar.somee.com/api/session' `
    -ContentType 'application/json' `
    -Body '{}'

Resposta 200

{ "sessionId": "abc-123" }

Componentes

POST /api/{sessionId}/component

Adiciona um novo componente ao circuito da sessão.

Pedido

{
    "id": "R1",
    "type": "resistor",
    "value": 1000
}

Exemplo

curl -X POST \
    -H "Content-Type: application/json" \
    -d '{"id":"R1","type":"resistor","value":1000}' \
    http://fizicar.somee.com/api/abc-123/component

Invoke-RestMethod -Method POST `
    -Uri 'http://fizicar.somee.com/api/abc-123/component' `
    -ContentType 'application/json' `
    -Body '{"id":"R1","type":"resistor","value":1000}'

Resposta 201

{
    "id": "R1",
    "type": "resistor",
    "value": 1000,
    "nodeA": "n1",
    "nodeB": "n2"
}

Ligações

POST /api/{sessionId}/connect

Cria uma ligação entre terminais de dois componentes.

Pedido

{
    "component1": "R1",
    "terminal1": "a",
    "component2": "V1",
    "terminal2": "a"
}

Exemplo

curl -X POST \
    -H "Content-Type: application/json" \
    -d '{"component1":"R1","terminal1":"a","component2":"V1","terminal2":"a"}' \
    http://fizicar.somee.com/api/abc-123/connect

Invoke-RestMethod -Method POST `
    -Uri 'http://fizicar.somee.com/api/abc-123/connect' `
    -ContentType 'application/json' `
    -Body '{"component1":"R1","terminal1":"a","component2":"V1","terminal2":"a"}'

Resposta 200

{ "message": "Connection added" }

Circuito

POST /api/{sessionId}/circuit

Monta o circuito com listas completas de componentes e ligações.

Pedido

{
    "components": [
        { "id": "V1", "type": "voltageSource", "value": 5 },
        { "id": "R1", "type": "resistor", "value": 1000 }
    ],
    "connections": [
        { "component1": "V1", "terminal1": "a", "component2": "R1", "terminal2": "a" }
    ]
}

Exemplo

curl -X POST \
    -H "Content-Type: application/json" \
    -d '{"components":[{"id":"V1","type":"voltageSource","value":5},{"id":"R1","type":"resistor","value":1000}],
        "connections":[{"component1":"V1","terminal1":"a","component2":"R1","terminal2":"a"}]}' \
    http://fizicar.somee.com/api/abc-123/circuit

Invoke-RestMethod -Method POST `
    -Uri 'http://fizicar.somee.com/api/abc-123/circuit' `
    -ContentType 'application/json' `
    -Body '{
        "components":[{"id":"V1","type":"voltageSource","value":5},{"id":"R1","type":"resistor","value":1000}],
        "connections":[{"component1":"V1","terminal1":"a","component2":"R1","terminal2":"a"}]
    }'

Resposta 200

{ "message": "Circuit built" }

Circuito

GET /api/{sessionId}/circuit

Devolve a estrutura actual de componentes e ligações da sessão.

Exemplo

curl -X GET \
    http://fizicar.somee.com/api/abc-123/circuit

Invoke-RestMethod -Method GET `
    -Uri 'http://fizicar.somee.com/api/abc-123/circuit'

Resposta 200

{
    "components": [
        { "id": "V1", "type": "voltageSource", "value": 5, "nodeA": "0", "nodeB": "1" },
        { "id": "R1", "type": "resistor", "value": 1000, "nodeA": "1", "nodeB": "0" }
    ],
    "connections": [
        { "component1": "V1", "terminal1": "a", "component2": "R1", "terminal2": "a" }
    ]
}

Análise

GET /api/{sessionId}/analysis

Executa análise eléctrica e devolve tensão e corrente por componente.

Exemplo

curl -X GET \
    http://fizicar.somee.com/api/abc-123/analysis

Invoke-RestMethod -Method GET `
    -Uri 'http://fizicar.somee.com/api/abc-123/analysis'

Resposta 200

{
    "componentResults": [
        { "id": "V1", "voltage": 5, "current": 0.005 },
        { "id": "R1", "voltage": 5, "current": 0.005 }
    ]
}

Sessões

DELETE /api/session/{sessionId}

Remove a sessão e todos os dados associados.

Exemplo

curl -X DELETE \
    http://fizicar.somee.com/api/session/abc-123

Invoke-RestMethod -Method DELETE `
    -Uri 'http://fizicar.somee.com/api/session/abc-123'

Resposta 200

{ "message": "Session deleted" }

Exemplo de fluxo completo

Criar sessão
Adicionar V1 (fonte de 5V) e R1 (1kΩ)
Ligar terminais
Obter circuito
Executar análise

POST /api/session
→ { "sessionId": "abc-123" }

POST /api/abc-123/component
{ "id":"V1", "type":"voltageSource", "value":5 }

POST /api/abc-123/component
{ "id":"R1", "type":"resistor", "value":1000 }

POST /api/abc-123/connect
{ "component1":"V1","terminal1":"a","component2":"R1","terminal2":"a" }

GET /api/abc-123/analysis
→ { "componentResults": [ {"id":"V1","voltage":5,"current":0.005}, {"id":"R1","voltage":5,"current":0.005} ] }

Visual minimalista do circuito (exemplo)

Fonte de 5V em série com resistor de 1kΩ.

Erros comuns

400 — JSON inválido ou campos em falta.
404 — sessionId inexistente.
409 — Identificador de componente duplicado dentro da sessão.
422 — Ligação impossível devido a terminais incompatíveis.

FAQ

Que tipos de componente estão disponíveis?

Exemplos: resistor, voltageSource, currentSource, capacitor, inductor. A lista pode crescer conforme a evolução do serviço.

Qual o formato das unidades?

Valores numéricos em SI. Converta prefixos (k, m, µ) no cliente ou no servidor conforme a política adoptada.