Project API

Project API даёт программный доступ к YAML-файлам проекта: их можно читать, проверять и записывать через REST-эндпоинты. Отсюда — автоматизация рутины, встраивание в CI/CD и массовые правки конфигурации без единого клика в интерфейсе.

Что такое YAML проекта

Коротко

YAML — человекочитаемый формат для конфигураций. Во FlutterFlow YAML-файлы описывают структуру приложения целиком — это и есть полная схема проекта.

Что входит в схему

• Интерфейс и страницы: деревья виджетов, раскладки страниц, иерархия компонентов, оформление.
• Настройки приложения: данные приложения, способы аутентификации, интеграции — AdMob, Firebase и прочие.
• Данные: коллекции базы, схемы API, переменные App State, собственные типы данных.
• Логика: действия, функции, условия, сценарии.
• Ресурсы: файлы кастомного кода, ссылки на изображения, шрифты и остальные ресурсы проекта.
• Организация проекта: структура папок, библиотеки компонентов, метаданные.

YAML и интерфейс FlutterFlow

Любое действие в визуальном редакторе — перетащили виджет, настроили коллекцию — в итоге записывается в эти YAML-файлы. Интерфейс FlutterFlow редактирует ту же схему, что и Project API, только визуально.

Структура файлов

Проект автоматически разбит на отдельные YAML-файлы по смыслу: app-state, ad-mob, отдельные страницы, коллекции и так далее. Благодаря этому правка одной части не задевает остальные.

Базовый адрес

Адрес зависит от окружения:

• Production

  https://api.flutterflow.io/v2/

• Beta/Staging

  https://api.flutterflow.io/v2-staging/

• Enterprise — по регионам:

  https://api-enterprise-india.flutterflow.io/v2/
  https://api-enterprise-apac.flutterflow.io/v2/
  https://api-enterprise-us-central.flutterflow.io/v2/
  https://api-enterprise-europe.flutterflow.io/v2/

Авторизация

Все эндпоинты требуют Bearer-токен в заголовке Authorization. Как его получить — в разделе про API-токен.

Authorization: Bearer YOUR_API_TOKEN_HERE

Эндпоинты

Список файлов

Прежде чем читать или менять файлы, нужно узнать, какие они есть. Эндпоинт возвращает полный список имён YAML-файлов проекта.

Эндпоинт

GET /listPartitionedFileNames

Параметры запроса

projectId (обязательный) — идентификатор проекта FlutterFlow.

Ответ

{
  "success":true,
  "reason":null,
  "value":{
    "versionInfo": {
      "partitionerVersion": 6, 
      "projectSchemaFingerprint": "abc123"
    },
    "fileNames": [
      "folders",
      "app-details",
      "collections/id-yr7z6g5a",
      "page/id-Scaffold_l9g6ilb6/page-widget-tree-outline/node/id-Column_174wuhc4",
      "custom-file/id-MAIN/custom-file-code",
      ...
    ]
  }
}

В массиве fileNames перечислены все доступные файлы. Блок versionInfo описывает версию схемы и её отпечаток: если он изменился, значит поменялась структура ответов API.

Пример

curl -X GET \
  'https://api.flutterflow.io/v2/listPartitionedFileNames?projectId=your-project-id' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Список проектов

Возвращает проекты вашего аккаунта с метаданными: название, почта владельца, команда, настройки совместной работы, сведения о версиях.

Эндпоинт

POST /l/listProjects

Тело запроса

{
  "project_type": "ALL",
  "deserialize_response": true
}

• project_type: "ALL" — личные, командные и общие проекты; "TEAM_RESOURCE" — только командные.

• deserialize_response: true — ответ придёт читаемым JSON, а не protobuf в base64.

Ответ

JSON с массивом проектов в ключе entries. У каждой записи — идентификатор и метаданные: участники, иконки, сессии, сведения о ветках.

{
  "success": true,
  "reason": null,
  "value": {
    "entries": [
      {
        "id": "XXXXXXXXXXXXXXX",
        "project": {
          "name": "Sample Project A",
          "ownerEmail": "user1@example.com",
          "createdAt": "2024-08-08T11:01:12.427Z",
          "updatedAt": "2024-08-08T11:01:18.669Z",
          "teamRef": {
            "path": "teams/TEAM_ID_1"
          },
          "mainBranchRef": {
            "path": "projects/sample-project-id"
          },
          "numBranches": 2,
          "otherMembers": {
            "USER_XYZ": {
              "email": "editor1@example.com",
              "accessLevel": "EDITOR"
            }
          },
          "activeSessions": {
            "SESSION_ID_1": {
              "lastSuccessfulUpdate": "2024-08-06T18:41:56.569Z"
            }
          },
          "totalNumUpdates": 2177
        }
      }
    ]
  }
}

Пример

curl 'https://api.flutterflow.io/v2/l/listProjects' \
  -H 'authorization: Bearer YOUR_API_TOKEN' \
  --data-raw '{
    "project_type": "ALL",
    "deserialize_response": true
  }'

Выгрузка YAML

Скачивает один файл конфигурации или все сразу — полезно, чтобы посмотреть текущую структуру перед правкой.

Эндпоинт

GET /projectYamls

Параметры запроса

• projectId (обязательный) — идентификатор проекта.
• fileName (необязательный) — конкретный файл без расширения. Без него выгружаются все.

Ответ

Возвращается zip-архив в виде строки base64. Её нужно раскодировать самостоятельно: скопируйте значение projectYamlBytes и превратите его в файл, например через base64.guru или b64encode.com.

{
  "success":true,
  "reason":null,
  "value":{
    "versionInfo": {
      "partitionerVersion": 6,
      "projectSchemaFingerprint": "abc123"
    },
    "projectYamlBytes": "UEsDBAoAAAAAAKxV..."
  }
}

Пример

# Выгрузить все файлы
curl -X GET \
  'https://api.flutterflow.io/v2/projectYamls?projectId=your-project-id' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

# Выгрузить конкретный файл
curl -X GET \
  'https://api.flutterflow.io/v2/projectYamls?projectId=your-project-id&fileName=ad-mob' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Проверка YAML

Перед изменением проекта содержимое нужно проверить: форматирование и значения должны быть корректными.

Эндпоинт

POST /validateProjectYaml

Тело запроса

{
  "projectId": "your-project-id",
  "fileKey": "ad-mob",
  "fileContent": "showTestAds: false\nappId: \"your-app-id\""
}

Ответ

• Успех (200): YAML корректен — {"success": true, "reason": null, "value": ""}.
• Ошибка с подробностями:

  {
    "validationErrors": [
      {
        "message": "Expected bool value",
        "fileKey": "ad-mob",
        "yamlLocation": {
          "line": 1,
          "column": 15
        }
      }
    ]
  }

Пример

curl -X POST \
  'https://api.flutterflow.io/v2/validateProjectYaml' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "projectId": "your-project-id",
    "fileKey": "ad-mob", 
    "fileContent": "showTestAds: false"
  }'

Обновление YAML

Перезаписывает файлы проекта переданным содержимым.

Эндпоинт

POST /updateProjectByYaml

Тело запроса

{
  "projectId": "your-project-id",
  "fileKeyToContent": {
    "ad-mob": "showTestAds: false",
  }
}

Ответ

• Успех (200): {"success": true, "reason": null, "value": ""}.
• 400: ошибки проверки или неверный запрос.
• 403: недостаточно прав либо проект заблокирован.
• 404: проект или пользователь не найден.

Пример

Обновляем файл ad-mob и добавляем переменные App State.

curl -X POST \
  'https://api.flutterflow.io/v2/updateProjectByYaml' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "projectId": "your-project-id",
    "fileKeyToContent": {
      "ad-mob": "showTestAds: false",
      "app-state": "fields:\n  - parameter:\n      identifier:\n        name: myAppState\n        key: hg7j8z0y\n      dataType:\n        scalarType: String\n      description: \"Stores the current user session state\"\n    persisted: false\n  - parameter:\n      identifier:\n        name: userPreferences\n        key: abc123xy\n      dataType:\n        scalarType: JSON\n      description: \"User settings and preferences\"\n    persisted: true"
    }
  }'

Пример использования

Разберём практическую задачу: меняем переменную App State через Project API.

Сначала через /listPartitionedFileNames проверяем, есть ли в проекте файл app-state. Затем запрашиваем его у /projectYamls: в ответ приходит zip-архив в base64, который нужно раскодировать — например, через Base64 to ZIP.

Дальше открываем app-state.yaml, у переменной enableDarkMode ставим persisted: true, превращаем YAML в экранированную однострочную запись и проверяем её через /validateProjectYaml. Если проверка прошла, отправляем изменения в /updateProjectByYaml.

Обработка ошибок

Коды ответов

Ошибки проверки

Если YAML не прошёл проверку, придут подробности:

{
  "validationErrors": [
    {
      "message": "Unknown field name 'showTestAdsasssdaf'",
      "fileKey": "ad-mob",
      "yamlLocation": {
        "line": 1,
        "column": 1
      }
    }
  ]
}

Рекомендации

• Сначала проверка, потом запись. Перед обновлением прогоняйте YAML через эндпоинт проверки:

  # 1. Проверяем YAML
  curl -X POST 'https://api.flutterflow.io/v2/validateProjectYaml' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{"projectId": "project-id", "fileKey": "ad-mob", "fileContent": "showTestAds: false"}'
  
  # 2. Если всё в порядке — применяем
  curl -X POST 'https://api.flutterflow.io/v2/updateProjectByYaml' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{"projectId": "project-id", "fileKeyToContent": {"ad-mob": "showTestAds: false"}}'

• Учитывайте блокировки. Во время других операций проект бывает временно заблокирован. Получили 403 с текстом Project is locked due to ongoing changes. Please try again later. — подождите и повторите.

• Обновляйте пакетами. В одном запросе можно изменить несколько файлов:

  {
    "projectId": "your-project-id",
    "fileKeyToContent": {
      "ad-mob": "showTestAds: false",
      "app-settings": "appName: \"Updated Name\"",
      "authentication": "enableEmailAuth: true"
    }
  }

Ограничения по частоте

У API есть лимиты на количество запросов. Если запросов много, делайте паузы между ними, иначе получите отказ.