1 В избранное 0 Ответвления 0

OSCHINA-MIRROR/noear-marsh

Присоединиться к Gitlife
Откройте для себя и примите участие в публичных проектах с открытым исходным кодом с участием более 10 миллионов разработчиков. Приватные репозитории также полностью бесплатны :)
Присоединиться бесплатно
Клонировать/Скачать
API.md 6.7 КБ
Копировать Редактировать Web IDE Исходные данные Просмотреть построчно История
gitlife-traslator Отправлено 26.11.2024 21:05 85c531e

Соглашение:

  1. Клиентская версия определяется как трёхчастная строка, и каждая часть ограничена 1 или 2 цифрами. Пример: 1.0.1, 2.1.0
  2. При передаче протокола клиентской версии он определяется цифрами и соответствует номеру версии приложения (каждая часть заменяется одной цифрой). Пример: 1.0.1 соответствует 101; 2.0.0 соответствует: 200

Запрос:

  1. Добавить информацию о подписи в заголовке для предотвращения изменения данных пакета
  2. Добавить канал, каждый канал имеет свой собственный независимый ключ; настроить с помощью «access key» от water («ak/sk»)
  3. Использовать имя интерфейса как часть пути
  4. Использовать формат JSON в теле сообщения + метод POST
  5. Зашифровать весь запрос тела
  6. Использовать кодировку: «UTF-8»

Общие параметры:

  1. g_lang — язык, использовать международный стандартный код (китайский: zh_CN, английский: en_US, японский: ja_JP)
  2. g_region — регион, использовать международный стандартный код (Китай: CN, США: US, Япония: JP)
  3. g_platform — платформа, определить в соответствии с ситуацией (например: 1ios, 2android, 3web)
  4. g_deviceId — идентификатор устройства клиента (необязательно)

Ответ:

  1. Использовать формат ответа JSON
  2. Зашифровать ответ тела целиком
  3. Включить вывод подписи в заголовок ответа [Sign]
  4. Изменить код состояния протокола на числовой (заимствовать настройки кода HTTP: 200 для успеха, 400xxxx для ошибки. См. документацию по протоколу для конкретных деталей)
  5. Использовать кодировку: «UTF-8»
Формат примера
  • Формат запроса
POST /api/v2/app/config.get   //запрос адреса вне
HEADER Sign=$sign   //протокол подписи (сессия данных подписи, избежать изменения)
HEADER Token=$token //протокол токена (информация о сессии)
HEADER Content-type=application/json
BODY ::зашифрованный{  //параметры, зашифрованные целиком
  "tag":"water"
}
  • Формат ответа
HEADER Sign=$sign   //протокол подписи (сессия данных подписи, избежать изменения)
HEADER Token=$token //протокол токена (информация о сессии)
BODY ::зашифрованный{
   "code": 200, 
   "description":"",          
   "data": null     //val или map или list  
}
Приложение: пример упаковки протокола (javascript):
var app_id     = "abc138356a624c15b1d1defb7c50ee23";                    //номер канала, назначен бэкэндом
var app_secret = "e6eQ1hM2OrOFdfL8";   //ключ канала (используется для шифрования и подписи)

var client_ver_id = 101;             //номер версии клиента 1.0.1

//
// Упаковка вызова протокола (токен передан через header[Token] из бэкэнда, просто передайте его обратно)
//
function call(var apiName, var args, var token) {

    let json1 = JSON.stringify(args);
    let json_encoded1 = base64Encode(aesEncrypt(json1, app_secret, "AES/ECB/PKCS5Padding", "utf-8")); //использование алгоритма aes для кодирования


    //создание подписи
    let timestamp = new Date().getTime();
    let sign_content = `${apiName}#${client_ver_id}#${json_encoded1}#${app_secret}#${timestamp}`;
    let sign_md5 = md5(sign_content, 'utf-8');
    let sign = `${app_id}.${client_ver_id}.${sign_md5}.${timestamp}`;

    //запросить и получить результат
    let response = path("/api/v2.app/" + apiName)
            .header("Token", token)
            .header("Sign", sign)
            .bodyTxt(json_encoded1)
            .post();
            
    let json_encoded2  = response.body().toString();  
    let sign2  = response.header("Sign");
    let sign22 = md5(`${apiName}#${json_encoded2}#${app_secret}`, "utf-8");
    
    //проверка подписи данных
    if(sign2 != sign22){
        throw "Данные были изменены!";
    }
    
    //расшифровка результата
    let json2 = aesDecrypt(base64Decode(json_encoded2), app_secret, "AES/ECB/PKCS5Padding", "utf-8"); //использование алгоритма aes для декодирования

    return JSON.parse(json2);
}

//
//Упаковка вызова интерфейса (на основе упаковки протокола, бизнес-упаковка)
//
function config_get(var tag){
    return call("config.get", {tag:tag} , null);
}

//Пример вызова интерфейса
config_get("water");

Основные коды состояния:

Код состояния Описание
200 Успех
400 Ошибка, неизвестная ошибка
4001010 Канал не существует или больше не поддерживается
4001011 Интерфейс не существует или больше не поддерживается
4001012 Не соответствует стандарту
4001013 Проверка подписи не удалась
4001014 Недостающие или ошибочные параметры
4001015 Слишком часто
4001016 Вне белого списка
4001017 Превышение лимита
4001018 Шифрование и дешифрование не удалось
4001021 Сессия истекла или не была установлена
1
https://api.gitlife.ru/oschina-mirror/noear-marsh.git
git@api.gitlife.ru:oschina-mirror/noear-marsh.git
oschina-mirror
noear-marsh
noear-marsh
main