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

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

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 operacoes.

• Tempo de Resposta

Latência típica < 200ms por operação simples.

• Lorem Ipsum

Lorem Ipsum.

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)

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

Resposta 200

{
  "sessionId": "<id>"
}

Sessões

DELETE /api/session/{sessionId}

Remove a sessão e todos os dados associados.

Exemplo (cURL)

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

Resposta 200

{ "message": "Session deleted" }

Componentes

POST /api/{sessionId}/component

Adiciona um novo componente ao circuito da sessão.

Pedido

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

Exemplo (cURL)

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

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)

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

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)

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

Resposta 200

{ "message": "Circuit built" }

Circuito

GET /api/{sessionId}/circuit

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

Exemplo (cURL)

curl -X GET \
  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)

curl -X GET \
  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 }
  ]
}

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.