Документация API
=================

Этот раздел содержит примеры запросов и ответов для API расчета нагрева проводов.

Пример JSON-ответа
-------------------

Ниже представлен пример JSON-ответа от сервера:

.. literalinclude:: ../_static/example_api_response.json
   :language: json
   :linenos:
   :caption: Пример JSON-ответа API

Вы можете скачать этот файл: :download:`example_api_response.json <../_static/example_api_response.json>`.



Описание полей
---------------

Общая информация

- **apiVersion**: Версия API.
- **title**: Название сервиса.
- **description**: Краткое описание API.

Эндпоинты
---------

1. Calculate Wire Heating
^^^^^^^^^^^^^^^^^^^^^^^^^

- **URL**: ``/calculate-heating``
- **Method**: POST

**RequestBody**:

  - **wireModel**: Модель или марка провода (например, ``'МФ-85'``, ``'МФ-100'``). Должна соответствовать значению из файла ``TWires.dat``.
  - **windSpeed**: Скорость ветра в метрах в секунду (м/с). По умолчанию: ``1.0``.
  - **ambientTemperature**: Температура окружающей среды в градусах Цельсия (°C). По умолчанию: ``40.0``.
  - **maxTime**: Максимальное время симуляции в минутах. По умолчанию: ``60``.
  - **timeStep**: Шаг времени для симуляции в минутах. По умолчанию: ``1``.
  - **tmpProgram**: Использовать ли временную программу для расчетов. По умолчанию: ``false``.
  - **calculationMethod**: Метод расчета (например, ``'Ми77'``, ``'Ми61'``). Должен соответствовать одному из доступных методов.

**ResponseBody**:

  - **status**: Статус расчета (``'success'`` или ``'error'``).
  - **message**: Дополнительное сообщение или описание ошибки.
  - **results**:
    
    - **currentOverTime**: Массив значений тока во времени (в амперах).
    - **temperatureOverTime**: Массив значений температуры во времени (в градусах Цельсия).
    - **permissibleTemperature**: Допустимый предел температуры (в градусах Цельсия).
    - **tapr**: Параметр TAPR, специфичный для выбранной модели провода.
    - **additionalStats**:
    
      - **averageCurrent**: Средний ток за период симуляции (в амперах).
      - **peakTemperature**: Пиковая температура, достигнутая во время симуляции (в градусах Цельсия).

1. Get Available Wire Models
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- **URL**: ``/available-wires``
- **Method**: GET

**ResponseBody**:

  - **status**: Статус запроса (``'success'`` или ``'error'``).
  - **message**: Дополнительное сообщение или описание ошибки.
  - **wires**: Список доступных моделей проводов со свойствами:

    - **mark**: Модель или марка провода (например, ``'МФ-85'``).
    - **diameter**: Диаметр провода (в миллиметрах).
    - **resistance**: Сопротивление провода (в омах на километр).
    - **thermalCapacity**: Теплоемкость провода (в джоулях на кельвин).
    - **ratedCurrent**: Номинальный ток провода (в амперах).
    - **durabilityTemperature**: Температура прочности провода (в градусах Цельсия).
    - **tapr**: Параметр TAPR, специфичный для модели провода.

1. Get Available Calculation Methods
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- **URL**: ``/available-methods``
- **Method**: GET

**ResponseBody**:

  - **status**: Статус запроса (``'success'`` или ``'error'``).
  - **message**: Дополнительное сообщение или описание ошибки.
  - **methods**: Список доступных методов расчета:

    - **shortName**: Короткое название метода (например, ``'Ми77'``).
    - **fullName**: Полное название или описание метода (например, ``'Михеев, 1977, гладкий'``).