App Conventions

Як ви знаєте, додатки Blackbird можна розглядати як міні-продукти, де кожна подія, дія та випадаючий список забезпечує продуманий користувацький досвід з метою створення робочих процесів якомога простішим способом. Ми створили понад 100 додатків та інтеграцій, і за цей час ми дізналися, яких стандартів і правил слід дотримуватися, щоб забезпечити простий і послідовний користувацький досвід. Правила, які ви знайдете нижче, застосовуються до всіх публічних додатків Blackbird (де можливо) і можуть стати неоціненним ресурсом для вас під час створення власних додатків.

1. Типи

У Blackbird користувачі можуть зустріти такі 5 основних типів: текст (string), число (будь-який числовий тип у .NET), дати (DateTime), файли (FileReference) та булеві значення. Також користувач може знайти “множинні” версії вищезгаданих, які в SDK позначаються як IEnumerable<string>, IEnumerable<FileReference> тощо.

1.1 - Типи ідентифікаторів

Деякі додатки обробляють ідентифікатори як цілі числа, деякі як типи long, деякі як рядки. У Blackbird ми обробляємо всі змінні-ідентифікатори як рядки. Це означає, що будь-яка змінна, яка є ідентифікатором певного виду, повинна бути перетворена в рядок і з рядка. Причина в тому, що якщо у нас є деякі додатки, які обробляють ідентифікатори як числа, а деякі як рядки, ми не можемо забезпечити взаємодію в плані збереження ідентифікаторів в інших місцях. Наприклад, якщо ви хочете зберегти ідентифікатор у користувацькому полі, зазвичай можна зберігати лише рядкові типи. Отже, витягування значення з такого користувацького поля не було б сумісним із числовим вводом ідентифікатора. По-друге, ніхто не повинен виконувати арифметичні операції з ідентифікаторами.

⚠️ Зверніть увагу - System.Text.Json (стандартний десеріалізатор RestSharp) за замовчуванням не десеріалізує з int, float тощо в рядок.

1.2 - Типи дат

Дати використовуються в багатьох додатках. Однак жоден додаток не є послідовним у форматі, який використовується для представлення дат. У Blackbird все, що представляє дату, має бути перетворено на DateTime. Чи то поле ‘створено в’, чи дедлайн. Переконайтеся, що ваші дати є DateTimes, а не рядками чи типами long. Це єдиний спосіб зробити додатки сумісними.

1.3 - Типи масивів

Також називається “multiple” в інтерфейсі Blackbird. Масиви, звичайно ж, позначають колекцію деяких інших примітивних типів або складний об’єкт класу. При поверненні об’єкта класу зауважте, що з цим типом структури не можна виконувати розширені операції. Для типів масивів найважливіше правило полягає в тому, що ніколи не повертайте null, завжди порожні масиви, навіть якщо основний API любить повертати null. Це робить помилки посилання на null менш ймовірними у користувацькому досвіді Blackbird.

2. Найменування

Усі облікові дані аутентифікації, дії, події (webhook), вхідні параметри та вихідні параметри повинні мати дружні для користувача, описові короткі назви. Якщо описової назви недостатньо, то можна додати довший опис, який з’явиться як спливаюча підказка в інтерфейсі Blackbird.

💡 Порада: Ви можете використовувати атрибут [Display()] майже для всього, щоб дати йому назву та додатковий опис.

Усі назви, які відображаються для користувачів в інтерфейсі, повинні бути ретельно вибрані, точно відображати дію/подію/параметр і можуть використовувати опис для пояснення важливої додаткової інформації. Усі правила найменування застосовуються до назв дій, описів дій, назв властивостей, джерел даних і властивостей з’єднання.

2.1 - Великі літери

Перше слово кожної назви має починатися з великої літери. Жодне інше слово не повинно починатися з великої літери. Наприклад:

❌ Create Draft Message

✅ Create draft message

За винятком абревіатур. Усі абревіатури повинні бути повністю у верхньому регістрі. Тобто ID, а не Id, URI, а не uri.

❌ Project id

✅ Project ID

2.2 - Ідентифікатори

Протягом певного періоду ми опускали слово “ID” у вхідних/вихідних змінних, які насправді були параметрами ідентифікаторів, на користь того, щоб просто називати їх тим, чим вони були: Project, Translation, Task. Це була помилка. Користувачу незрозуміло, який параметр представляє, і його часто плутали, наприклад, з вмістом перекладу. Будь-яка змінна, яка є ідентифікатором, повинна містити слово ID. Крім того, ніколи не називайте параметр просто “ID”, завжди будьте більш конкретні, наприклад, “Company ID”.

❌ ID

❌ Translation

✅ Translation ID

2.3 - Довжина назв

Назви в редакторі birds не мають багато місця для роботи. Ось чому назви властивостей і дій повинні бути відносно лаконічними. Як правило, назви повинні бути не більше ~40 символів.

❌ Add business phone number to contact’s business details

✅ Update contact

3. Помилки

Ми хочемо завжди надавати користувачам описові та придатні для дій повідомлення про помилки. Наші користувачі можуть бути нетехнічними, і ми хочемо допомогти їм найкращим чином. Особливо це стосується помилок, з якими користувач може щось зробити, наприклад, коли вони вводять неправильну змінну, коли їхні дані аутентифікації неправильні або коли їхня система неправильно налаштована.

3.1 - Відображення помилок

Помилки в Blackbird просто генеруються як винятки, і Blackbird виводить повідомлення про виняток користувачам при перевірці польоту. При використанні throw new Exception("Моє повідомлення про помилку тут") повідомлення про помилку буде відображатися користувачу. Однак ми віддаємо перевагу завжди усувати звичайні винятки, які бачить користувач. Замість цього слід використовувати два класи винятків PluginMisconfigurationException і PluginApplicationException. Прочитайте сторінку про помилки для детального опису.

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

3.2 - Обмеження швидкості

Майже кожен API має налаштовану політику обмеження швидкості. Це обмеження швидкості часто можна знайти в документації API. Обов’язок розробника додатків - переконатися, що помилки обмеження швидкості не доходять до користувача Blackbird на рівні дій. Це означає, що про обмеження швидкості потрібно подбати, ідентифікуючи відповіді про помилки обмеження швидкості (іноді вони додаються до заголовків відповіді) і реалізуючи затримки завдань, щоб сповільнити кількість запитів, які робить ваш код.

4. З’єднання

З’єднання Blackbird можна визначити з будь-якою кількістю “полів визначення з’єднання”. Вони також мають можливість налаштовувати спеціальні з’єднання OAuth2. OAuth2 забезпечує неймовірний користувацький досвід. А саме, він дозволяє нашим користувачам підключатися до Blackbird лише одним кліком. Якщо можливо, ми завжди хочемо використовувати OAuth2 і уникати необхідності наших користувачів вводити ідентифікатори клієнтів, секрети клієнтів, дозволи тощо.

По-друге, врахуйте, що поля з’єднання також можуть мати назви для відображення, описи та додатковий чутливий параметр. Паролі та ключі API повинні мати прапорець Sensitive = true, який зробить їх видимими як паролі в Blackbird.

Назви полів з’єднання повинні бути короткими, описовими та зрозумілими. З назви поля користувач повинен зрозуміти, які саме дані від них потрібні.

5. Джерела даних

Багато вхідних параметрів для дій мають лише певну кількість дозволених входів. Для зручності користувачів і загального досвіду ми дозволяємо вам визначати джерела даних, які повідомляють Blackbird, які значення дозволені, і користувач може вибирати з цих значень.

5.1 - Статичні джерела даних

Статичні джерела даних призначені для змінних, які є попередньо визначеними і кінцевими. Це означає будь-яку форму перерахованих типів, ідентифікаторів, які представляють перераховані типи, налаштовані мови тощо. Замість того, щоб користувач мав здогадуватися, які значення очікує API, ми повинні завжди використовувати статичні джерела даних для входів з кінцевою кількістю можливих варіантів, які можна заздалегідь визначити. Прикладами статичних джерел даних є:

• Статуси для проектів або завдань у TMS або додатку управління проектами.
• Мови, коли вхідний параметр - це вихідна/цільова мова, і додаток не дозволяє налаштовувати власні мови.

5.2 - Динамічні джерела даних

Динамічні джерела даних, як і підказує слово, використовуються, коли дані потрібно завантажити з з’єднання. Класичними прикладами динамічних джерел даних є:

• Проекти, коли вхідний параметр - це ідентифікатор проекту в додатку TMS.
• Канали, коли вхідний параметр - це ідентифікатор каналу для Slack.
• Мови, коли вхідний параметр - це вихідна/цільова мова, і мови налаштовані в додатку.
• Папки в діях управління файлами при виборі місця для оновлення/завантаження файлів в/з.

Будь-який вхідний параметр, який має кінцеву кількість можливих значень, але залежить від з’єднання користувача, повинен мати визначене динамічне джерело даних.

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