API¶

Общие сведения об API Неба¶

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

При использовании текущей версии API Неба необходимо осознавать, что оно предназначено в первую очередь для функционирования основного клиентского приложения Неба. Все спорные и неоднозначные моменты в данном API возникли из-за того, что в первую очередь максимизировалось удобства разработки и функционирования именно клиентского приложения.

Текущая версия API пока не является фиксированной. Возможны изменения в составе передаваемых данных без предварительного уведомления взаимодействующих внешних приложений. Фиксация API по разделам Неба и последующая его версионность будут реализованы в течение 2014 года.

Также помните, что на текущий момент времени "защита от дурака" в Небе равномерно распределена между клиентским и серверным приложением. Значительная часть ограничений на использование Неба (в основном, некритичных для безопасности и целостности данных) реализованы путем выбора специфической схемы организации клиентского приложения, без их дублирования на серверной части. Поэтому, перед использованием тех или иных операций желательно убедиться, что они не противоречат логике предметной области и текущего поведения Неба в целом (например, посмотрев как требуемая операция реализована в интерфейсе Неба).

Аутентификация внешнего приложения¶

Для аутентификации пользователей применяется общепринятая для Web-приложений схема.

1. Внешнее приложение отсылает GET или POST запрос на URL https://nebopro.ru/loging передавая в параметрах запроса следующие значения:

• login - email зарегистрированного в Небе пользователя;
• pass - его пароль

2. В ответе сервера будет находится JSON объект с {"success": true} при успешной аутентификации, либо {"success": false, "msg": "Текст с причиной, почему не удалось аутентифицировать пользователя"}.

3. В заголовке ответа сервер проставляет cookie с именем sessionid, которое является сессионным ключом данного пользователя. Здесь же сервер указывает максимальный срок жизни сессии - параметр expires.

Полученный sessionid необходимо указывать в cookie всех последующих HTTP-запросов к серверу.

Пример аутентификации с последующим получением списка пользователей в аккаунте¶

Пример приведен на языке python

#coding:utf-8

import urllib, urllib2  # библиотека python, которая позволяет работать с HTTP запросами
import json

def authenticate(username, password):
    u""" 
    Аутентифицирует пользователя в Небе, возвращая строку с sessionid. При неудачной попытке 
    возвращается None
    """ 

    # формируем параметры запроса и энкодим их, чтобы они нормально ушли как параметры GET запроса
    params = urllib.urlencode({
        'login': username,
        'pass': password
    })

    # объект запроса
    req = urllib2.Request('https://nebopro.ru/loging', params)

    # получаем ответ
    resp = urllib2.urlopen(req)

    # читаем содержимое ответа
    data = json.loads(resp.read())  

    result = None
    if data['success']:
        # чтобы не уклоняться от темы, выделим sessionid таким решительным способом
        result = unicode(resp.headers['Set-Cookie'], 'utf-8')[10:42]

    return result

def get_users(sessionid):
    u""" Возвращает JSON объект со списком пользователей """ 

    req = urllib2.Request('https://nebopro.ru/core/nebo-user/list')
    req.add_header('Cookie', "sessionid=" + sessionid + ';')
    resp = urllib2.urlopen(req)

    result = None
    if resp.getcode() == 200 and resp.info().type == 'application/json':
        # В некоторых случаях, в т.ч. при выполнении запроса с невалидным sessionid сервер вернет
        # ответ с типом содержимого text/html. Поэтому, при анализе ответа необходимо проверять
        # HTTP-статус ответа 200 и тип ответа application/json
        result = json.loads(resp.read())['data']
    return result

# получаем ключ доступа
sessionid = authenticate('akvarats@nebopro.ru', '*******')
# получаем список пользователей
users =  get_users(sessionid)

Для аккаунта с одним пользователем в users будет следующий список из одного объекта

[{
    "profile": {
        "status": {
            "name": "\u0420\u0430\u0431\u043e\u0442\u0430\u0435\u0442",
            "id": 3
        },
        "first_name": "akvarats@nebopro.ru",
        "last_name": "",
        "middle_name": "",
        "uid": "*******************",
        "is_active": true,
        "id": 638,
        "phone": "8 927 400 12 05",
        "is_admin": true,
        "full_name": "akvarats@nebopro.ru",
        "phone_binding": {
            "can_bind_phone": false,
            "phone_bound": false
        },
        "auth_user": {
            "id": 647
        },
        "email": "akvarats@nebopro.ru" 
    },
    "cnt": {
        "itsme": true,
        "hd": false
    },
    "permissions": [{
        "chapter": null,
        "access_level": {
            "name": "\u041f\u043e\u043b\u043d\u044b\u0439",
            "id": 1
        },
        "company": {
            "name": "akvarats@nebopro.ru",
            "profiles": [],
            "id": 668
        }
    }, {
        "chapter": null,
        "access_level": {
            "name": "\u041f\u043e\u043b\u043d\u044b\u0439",
            "id": 1
        },
        "company": {
            "name": "\u041a\u043e\u043c\u043f\u0430\u043d\u0438\u044f \u0438\u0437 47 \u0440\u0435\u0433\u0438\u043e\u043d\u0430",
            "profiles": [],
            "id": 9148
        }
    }, {
        "chapter": null,
        "access_level": {
            "name": "\u041f\u043e\u043b\u043d\u044b\u0439",
            "id": 1
        },
        "company": {
            "name": "\u041a\u043e\u043c\u043f\u0430\u043d\u0438\u044f \u0438\u0437 78 \u0440\u0435\u0433\u0438\u043e\u043d\u0430",
            "profiles": [],
            "id": 9149
        }
    }],
    "user": {
        "uid": "7951d057-a19f-47d8-afdd-63d66fe85b8e",
        "user_fio": "akvarats@nebopro.ru",
        "email": "akvarats@nebopro.ru",
        "id": 728
    },
    "phone_binding": {
        "can_bind_phone": false,
        "phone_bound": false
    }
}]