Руководство пользователя для разработчиков

Введение

Этот API позволяет вам управлять ключами API. Ключи API являются основным звеном системы авторизации Epsilon Metrics. Ознакомьтесь с этим руководством для получения дополнительной информации.

API принимает и возвращает JSON.
Базовый конечный пункт API: https://maps.epsilonmetrics.ru/user/{your_username}/api/v3/api_keys или https://maps.epsilonmetrics.ru/user/{org_name}/api/v3/api_keys в случае использования пользователя, принадлежащего организации.

Авторизация

Существует три разных ключа API, предоставляющих разные привилегии доступа:

default: Этот API предоставляет доступ ко всем публичным объектам. Его нельзя удалить.
master: Используя этот ключ API, вы получите полный доступ и сможете создавать/управлять regular ключами API. Его нельзя удалить. Вы должны хранить его токен в безопасности и использовать только тогда, когда это строго необходимо.
regular: Эти ключи API можно создавать с пользовательскими привилегиями доступа и удалять.

Формат ключа API

Каждый ключ API состоит из четырех основных частей:

name: Вы выберете его при создании ключа API, и он будет использоваться для индексации ваших ключей API.
type: Как упоминалось ранее, существует три типа ключей API: default, master и regular, предоставляющих разные уровни доступа.
token: Он будет использоваться для аутентификации ваших запросов.
grants: Описывает, к каким API этот ключ API предоставляет доступ и к каким таблицам. Он состоит из массива двух JSON объектов. Атрибут type этого объекта может быть apis, database или dataservices:
- apis: Описывает, к каким API этот ключ API предоставляет доступ через атрибут apis:
```
{
      "type": "apis",
      "apis": [
          "sql",
          "maps"
      ]
}
```
- database: Описывает, к каким таблицам и схемам, и какие привилегии на них предоставляет доступ этот ключ API через атрибуты tables, schemas и table_metadata.
  Вы можете предоставить разрешения на чтение (select) или запись (insert, update, delete) таблиц.
  В случае схем, после предоставления разрешения create на схему, вы сможете выполнять SQL-запросы, такие как CREATE TABLE AS...,CREATE VIEW AS... и т.д., для создания сущностей на ней.
  Также вы можете разрешить вывод списка всех метаданных таблиц (например, имя или приватность) с атрибутом table_metadata.
```
{
    "type": "database",
    "tables": [
        {
            "schema": "public",
            "name": "my_table",
            "permissions": [
                "insert",
                "select",
                "update"
            ]
        }
    ],
    "schemas": [
        {
            "name": "public",
            "permissions": [
                "create"
            ]
        }
    ],
    "table_metadata": []
}
```
- dataservices: Описывает, к каким службам передачи данных этот ключ API предоставляет доступ через атрибут services:
```
{
    "type": "dataservices",
    "services": [
        "geocoding",
        "routing",
        "isolines",
        "observatory"
    ]
}
```

Аутентификация

Для аутентификации ваших запросов к API вам нужно включить заголовок Basic Authentication, где username - ваше имя пользователя, а password - токен вашего API-ключа. Этот метод аутентификации будет действителен для всех компонентов Epsilon Metrics (Auth API, Maps API, SQL API). Вы можете создать свой заголовок Authorization следующим образом:

"Basic #{Base64.strict_encode64(username + ':' + api_key.token)}"

Важно: API-ключ, который вы предоставляете для доступа к Auth API, должен быть типа master.

API-ключи

Список API-ключей

GET /api_keys

Возвращает список API-ключей.

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

per_page: integer - Ограничивает количество API-ключей в списке.
page: integer - Определяет, какую страницу выбирать.
order: string - Используется для определения критериев, по которым перечисляются API-ключи. Может быть любым из атрибутов.
target_user: string - Имя пользователя, принадлежащего организации, API-ключи которого будут перечислены.

Ответы

200: Ok
401: Неавторизован. Неправильная или отсутствующая аутентификация.
403: Запрещено. API-ключ не разрешает этот запрос.
404: Указанный ресурс не найден.

Создать API ключ

POST /api_keys

Создает обычный API ключ. API ключи master и default_public автоматически генерируются при создании пользователя.

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

ApiKeyHTTPBasicAuth
ApiKeyQueryParam

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

target_user: строка
- Имя пользователя, принадлежащего организации, для которого будет создан новый обычный API ключ

Схема тела запроса: application/json

name (обязательно): строка
- Для идентификации вашего API ключа
grants (обязательно): массив любых значений

Ответы

201: Создано
401: Неавторизован. Неправильная или отсутствующая аутентификация.
403: Запрещено. API-ключ не разрешает этот запрос.
404: Указанный ресурс не найден.
422: Ошибка параметров запроса.

Получить API-ключ

Запрос:

GET /api_keys/{name}

Описание:

Возвращает API-ключ на основе его name.

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

ApiKeyHTTPBasicAuth
ApiKeyQueryParam

Параметры пути:

name (обязательный, строка): название API-ключа

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

target_user (строка): имя пользователя, принадлежащего организации, которому принадлежит запрашиваемый API-ключ

Ответы:

200: ОК
401: Неавторизован. Неправильная или отсутствующая аутентификация.
403: Запрещено. API-ключ не авторизует этот запрос.
404: Указанный ресурс не найден.

Удалить API-ключ

Запрос:

DELETE /api_keys/{name}

Описание:

Удаляет API-ключ на основе его name. Можно удалить только regular API-ключи.

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

ApiKeyHTTPBasicAuth
ApiKeyQueryParam

Параметры пути:

name (обязательный, строка): название API-ключа

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

target_user (строка): имя пользователя, принадлежащего организации, которому принадлежит API-ключ, который будет удален

Ответы:

200: Ресурс успешно удален.
401: Неавторизован. Неправильная или отсутствующая аутентификация.
403: Запрещено. API-ключ не авторизует этот запрос.
404: Указанный ресурс не найден.

Восстановить токен API-ключа

Запрос:

POST /api_keys/{name}/token/regenerate

Описание:

Восстанавливает токен API-ключа. Остальные поля остаются без изменений.

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

ApiKeyHTTPBasicAuth
ApiKeyQueryParam

Параметры пути:

name (обязательный, строка): название API-ключа

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

target_user (строка): имя пользователя, принадлежащего организации, которому принадлежит API-ключ, токен которого будет восстановлен

Ответы:

200: ОК.
401: Неавторизован. Неправильная или отсутствующая аутентификация.
403: Запрещено. API-ключ не авторизует этот запрос.
404: Указанный ресурс не найден.