Спецификация дизайна интерфейса API

API спецификация кода

Обзор

В этой статье представлена ​​спецификация дизайна интерфейса API для справки разработчиков.

Нормы мертвы, люди живы, я надеюсь, что нормы, установленные самим собой, не будут оплеваны.

соглашение об именах маршрутов

действие префикс Примечание
Получать get get{XXX}
Получать get get{XXX}List
новый add add{XXX}
Исправлять update update{XXX}
спасти save save{XXX}
Удалить delete delete{XXX}
загрузить upload upload{XXX}
Отправить send send{XXX}

метод запроса

метод запроса описывать
GET получить данные
POST Добавить данные
PUT обновить данные
DELETE удалить данные

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

Query

Параметр после url? хранит данные параметра интерфейса запроса.

Header

В заголовке запроса хранятся общедоступные параметры, requestId, токен, зашифрованные поля и т. д.

Body

Тело, в котором хранятся данные параметров интерфейса запроса.

общедоступный параметр

Сторонний запрос приложения

параметр инструкция Примечание
network Интернет WI-FI, 4G
operator оператор China Unicom/мобильная связь
platform Платформа iOS, Андроид
system система iOS 13.3, Андроид 9
device Модель устройства iPhone XR, Сяоми Ми 9
udid уникальный идентификатор устройства
apiVersion Номер версии API v1.1, v1.2

WEB-запрос

параметр инструкция Примечание
appKey Ключ авторизации нить

Вызывающий должен запросить appKey (используемый во время запроса) и secretKey (используемый во время шифрования) с сервера.

правила техники безопасности

Обработка шифрования конфиденциальных параметров

Пароль для входа и платежный пароль, которые необходимо зашифровать и передать, рекомендуется использовать非对称加密.

Другие характеристики

  • соглашение об именах параметровРекомендуется использовать верблюжий регистр и строчную первую букву.
  • requestIdРекомендуется иметь при себе уникальный идентификатор для отслеживания проблемы.

возвращаемый параметр

параметр тип инструкция Примечание
code Number код результата успех=1
ошибка=-1
Не авторизован=401
Нет разрешения=403
showMsg String Показать информацию Система занята, повторите попытку позже
errorMsg String сообщение об ошибке Содействовать исследованиям и разработке проблем позиционирования
data Object данные формат JSON

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

{
    "code": 1,
    "showMsg": "success",
    "errorMsg": "",
    "data": {
        "list": [],
        "pagination": {
            "total": 100,
            "currentPage": 1,
            "prePageCount": 10
        }
    }
}

правила техники безопасности

Десенсибилизация конфиденциальных данных

Номер мобильного телефона пользователя, адрес электронной почты пользователя, идентификационный номер, номер платежного счета, почтовый адрес и т. д. должны быть десенсибилизированы, а некоторые данные должны обрабатываться с *.

Другие характеристики

  • При именовании имени атрибута рекомендуется использовать верблюжий регистр, а первая буква строчная.
  • Когда значение свойства пусто, значение по умолчанию возвращается строго по типу.
  • Значение атрибута типа суммы/даты времени, если оно используется только для отображения, рекомендуется, чтобы серверная часть возвращала строку, которую можно отобразить.
  • Код состояния бизнес-логики и соответствующую копию рекомендуется, чтобы серверная часть возвращала оба.
  • Свойства, не требуемые вызывающей стороной, не возвращаются.

фирменный дизайн

Определенной спецификации для проверки подписи нет, вы можете сделать это самостоятельно, вы можете использовать его对称加密,非对称加密,单向散列加密Подождите, поделитесь оригинальной проверкой подписи для справки.

Дизайн бревенчатой ​​​​платформы

Платформа журнала способствует обнаружению ошибок и статистическому анализу журнала.

Бревенчатая платформа может быть построена с использованиемELKкомпоненты, используяLogstashДля сбора файлов журнала используйтеElasticsearchДвижок проводит поисковый анализ и попадает вKibanaОтображается платформа.

Идемпотентный дизайн

Мы не можем гарантировать, что каждый вызов интерфейса вернет результат, и мы должны учитывать ситуацию с сетевыми исключениями.

Например, когда заказ создан, нам нужно вычесть инвентарь. В это время интерфейс истекает, и вызывающий абонент повторяет попытку. Будет ли инвентарь вычтен еще раз?

Есть 2 решения этой проблемы:

1.Сервисная сторона предоставляет соответствующий интерфейс запроса.Вызывающий выполняет запрос после истечения времени запроса.Если он найден, это означает, что обработка запроса прошла успешно.Если он не найден, он переходит к процессу отказа.

2. Вызывающему нужно только повторить попытку, а сервер гарантирует, что результат одного и нескольких запросов будет одинаковым.

Для второго решения интерфейс сервера должен поддерживать идемпотентность.

Общая идея конструкции такова:

  1. Перед вызовом интерфейса сначала получите глобально уникальный токен (Token)
  2. При вызове интерфейса поместите токен в заголовок заголовка
  3. Проанализируйте заголовок заголовка, чтобы проверить, является ли он допустимым токеном, если он недействителен, напрямую верните ошибку.
  4. После завершения бизнес-логики сохраните бизнес-результаты в связи с токеном и установите время истечения срока действия.
  5. Не получайте повторно токен при повторной попытке, используйте последний токен

резюме

Токоограничивающий дизайн, дизайн предохранителя, дизайн понижения, о них мало что можно сказать, потому что большинство из них не используются, а когда они используются, эти функции в основном добавляются к шлюзу.

Пока это все, что я могу придумать.Регламенты не статичны.Если вы найдете что-то неуместным, вовремя откорректируйте их.

Названы ли клавиши ввода и вывода вашего интерфейса в верблюжьем регистре или подчеркиванием? Добро пожаловать, чтобы оставить сообщение.

Рекомендуемое чтение

Категории