REST API

Авторизация

Вы можете получить доступ к REST API только через https. Для доступа к REST API вам нужно использовать токен доступа. Вы можете сгенерировать токен доступа, перейдя на страницу учетной записи вашей организации.

В разделе API Tokens нажмите на кнопку Generate Token.

Дайте вашему токену имя и нажмите кнопку для создания вашего нового токена. В новом окне появится ваш новый токен доступа.

Обязательно запишите его, потому что вы не сможете увидеть токен после закрытия этого окна. Этот токен предназначен для сохранения в тайне, поэтому не делитесь им с кем-либо, кроме вашей команды (например, не публикуйте его на форумах).

На странице вашей учетной записи вы также можете отозвать все сгенерированные вами токены или конкретный токен. Вы также можете изменить имя токена.

При отправке запросов к API вы должны установить заголовок 'Authorization' в вашем HTTP-запросе на это значение:

Bearer [access_token]

Замените [access_token] на токен доступа, который вы сгенерировали на странице вашего аккаунта.

Например:

curl -H "Authorization: Bearer nesgdxhiqe7hylfilr6ss1rds0gq1uj8" https://playcanvas.com/api/...

Параметры

Различные маршруты принимают ряд параметров. Для запросов GET, если параметр не является частью URL, вы можете передать его в виде параметра строки запроса HTTP. Для запросов POST, PUT и DELETE параметры, не включенные в URL, должны быть закодированы в формате JSON с Content-Type 'application/json'.

Есть несколько общих параметров, которые используются в каждой конечной точке:

project_id

Этот параметр можно найти в URL на странице обзора проекта.

scenes

При открытии сцены в редакторе идентификатор сцены находится в URL.

branch_id

Этот параметр можно найти в панели version control и его можно выбрать и скопировать.

Формат ответа

Наш REST API следует некоторым общим рекомендациям по формату ответа каждого вызова API.

GET resource

Если вы пытаетесь получить один ресурс с помощью GET, ответ будет объектом JSON с запрашиваемым ресурсом.

GET multiple resources

Если вы пытаетесь получить несколько ресурсов, например, перечисляя приложения проекта, вы получите объект JSON следующего формата:

{
    "result": [
        resource_1,
        resource_2,
        ...,
        resource_N
    ],
    "pagination": {
        "limit": число,
        "skip": число,
        "total": число
    }
}

Как вы можете заметить, ответ в этом случае также содержит данные о разбиении на страницы. Чтобы контролировать разбиение на страницы ответа, вы можете передать следующие параметры URL:

Так что, например, чтобы получить 32 элемента после первых 16 элементов, вы должны отправить этот запрос:

https://playcanvas.com/api/items?limit=32&skip=16

Ошибки

Когда возникает ошибка, вы получите объект JSON в таком формате:

{
    "error": "Это сообщение об ошибке"
}

Также код состояния ответа будет соответствующим кодом ошибки HTTP.

Ограничение скорости

Запросы к REST API имеют ограничение скорости.

Проверьте свои лимиты здесь. Существуют разные ограничения скорости в зависимости от запроса:

Ответ будет содержать следующие заголовки, чтобы помочь вам регулировать частоту вызова API:

Если вы превысите ограничение скорости, вы получите код состояния 429 Too Many Requests. Вам придется подождать сброса текущего окна, чтобы продолжить отправку запросов.