Спецификация по api: Классификация моторных масел по API, ACEA, SAE и ILSAC

alexxlabОпубликовано

Содержание

Классификации моторных и трансмиссионных масел API, ACEA, SAE

Классификация моторных масел API впервые появилась в 1947 г. по инициативе Американского института нефти (API: American Petroleum Institute), который классифицировал смазочные материалы согласно уровню их функциональных свойств и вводил новые стандарты, когда это требовал американский авторынок.

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

Условные обозначения:
  • первая буква обозначает применение смазочных материалов:
    • масла для бензиновых двигателей обозначаются буквой S
    • масла для дизельных двигателей — буквой C.
  • вторая буква обозначает уровень свойств моторного масла.

 

Классификация моторных масел API для бензиновых двигателей

SE ***Бензиновые двигатели 1972. Те же требования к моторному маслу, что и для категории SD, но лучше защита двигателя.
SF ***Бензиновые двигатели  1980. Те же требования, что и для категории SE, но улучшена защита от износа и окислительная стабильность.
SG ***Бензиновые двигатели 1988. Те же требования, что и для категории SF, но лучше защита от износа, образования шлама и окисления масла.
SH ***
Бензиновые двигатели 1993. Те же требования, что и для категории SG, но вводится система лицензирования и записи результатов всех моторных тестов и формул с целью гарантии качества. Символ API, который свидетельствует о дейсвтительном соответствии уровню SH помещается на этикетки канистр.
SJБензиновые двигатели 1996. Те же требования, что и для категории SH (включая лицензию и систему сертификатов) с лучшей защитой от окисления масла при высоких температурах и забивания катализатора.   
Начиная с  01/08/97, уровень SJ официально заменяет SH.
SLБензиновые двигатели 2001. Новые тесты на степень износа  (Seq IVA), моющие свойства моторного масла (TEOST MHT4), окисление (Seq IIIF) и низкотемпературные отложения (Seq VG)  для лучшей защиты двигателя и продления интервала замены масла. Стандарт SL заменил  API SJ в середине 2001г.
SMБензиновые двигатели 2004. Улучшены общие свойства для максимально-расширенного интервала замены масла. Ужесточен тест на высокотемпературные отложения (TEOST), новый тест на окисление (Seq. IIIG).
SNБензиновые двигатели 2010.  Представлен в октябре 2010 г. Разработан для автомобилей 2011 года выпуска и более ранних. Улучшенная защита от высокотемпературных отложений на поршнях. Более жесткие требования к контролю сажи и совместимости с уплотнителями.

*** устаревшие классификации, подобно APISA, APISB, APISC и APISD.

 

Классификация моторных масел API для 2-тактных двигателей

Классификация API для 2-тактных двигателей имеет четыре уровня: TA, TB, TC для наземных транспортных средств и TD для использования на лодочных 2-тактных двигателеях. Производители рассматривают данную класификацию моторных масел как устаревшую. Эстафету приняла японская спецификация JASO, признанная в среде профессионалов. Международная специяикация ISO базируется на данной японской спецификации, опубликованной в 1997г.

Спецификации по API для дизельных двигателей.

CE *«Требовательные» коммерческие дизельные двигатели (1987).
Очень жесткие условия эксплуатации для нагруженных дизельных двигателей. Соответствует CD, усиленная защита от износа и высокотемпературных отложений, лучший контроль за окислением и расходом масла.
CF-4 *«Требовательные» коммерческие дизельные двигатели (1991).Те же требования, что и для категории CE, но усиленная защита против отложений на поршнях и высокого расхода масла.
CFДизельные двигатели с непрямым впрыском (1994). Масла для строительной и карьерной техники, а также для двигателей, использующих дизельное топливо с высоким содержанием серы (>0.5%). Могут быть использованы вместо API CD. Иногда используются в дизельных двигателях для пассажирского транспорта.  
CG-4		Коммерческие дизельные двигатели, работающие в под тяжелыми нагрузками (развитие API CF-4, 1995). Масла для двигателей, соответствующих ограничениям по выхлопам в  США 1994 г. (дизельное топливо с содержанием серы ≤ 0.05%).  Могут быть использованы с дизельным топливом, содержащим серу в количестве до 0,5%).
CH-4Дизельные двигатели под очень высокими нагрузками, удовлетворяющие стандартам по выхлопам США (1998). Масла, соответствующие требованиям США 1998г. для двигателей с пониженным уровнем выхлопов, специально разработаны для дизельного топлива с содержанием серы не более 0,5%. Особенно эффективны в борьбе с коррозией, износом, сажей и окислением. Высокая сдвиговая стабильность и устойчивость к вспениванию. Продлевают срок службы двигателей, эксплуатируемых в самых разнообразных условиях. Перекрывая требования предыдущих стандартов, данные масла достаточно гибко могут быть использованы в разнородных парках техники.
CI-4Дизельные двигатели под очень высокими нагрузками (2002). Масла для последних дизельных двигателей с пониженным выхлопом, перекрывает требования CH-4. Особенно подходит для оборудования, работающего на дизельном топливе с очень низким содержанием серы (менее 0,5%). Ужесточенные требования к свойствам масел и одновременное увеличение интервала замены масла в 2 раза. Увеличение срока службы двигателя. Также принимается во внимание более строгие требования к работе с системами доочистки выхлопных газов.

 

Новая версия, названная API CI-4 Plus была опубликована в 2004г. с целью улучшить совместимость с системами EGR

CJ-4Представлена в 2006г для 4-тактных высокоскоростных двигателей, удовлетворяющих требованиям к выхлопам 2007 года. Эти масла были разработаны для двигателей, оснащенных сажевыми фильтрами и рассчитанных на использование дизельного топлива с содержанием серы до 0,05%. Могут быть использованы вместо масел стандартов API CF-4, CG-4, CH-4, CI-4 и CI-4 Plus

* устаревшие спецификации, ровно как и API CA, API CB, API CC and API CD. CF и CG-4.

Классификация моторных масел API для 2-тактных дизельных двигателей.

CD-II2-тактные дизельные двигатели, работающие в сложных условиях (1988). Улучшенная защита от износа и отложений. Удовлетворяет требованиям уровня CD.
CF-22-тактные дизельные двигатели, работающие в сложных условиях (1994). Более жесткие требования, чем API CD-II. Усиленная защита от износа поршневых колец и цилиндров.

 

Классификация API трансмиссионных масел

API-GL-1

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

API-GL-2

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

API-GL-3

Трансмиссионные масла с высоким содержанием присадок с уровнем эксплуатационных свойств MIL-L-2105. Эти масла применяются предпочтительно в ступенчатых коробках передач и рулевых механизмах, в главных передачах и гипоидных передачах с малым смещением в автомобилях и безрельсовых транспортных средствах для перевозки грузов, пассажиров и для нетранспортных работ. Обладают лучшими противоизносными свойствами, чем GL-2.

API-GL-4

Трансмиссионные масла с высоким содержанием присадок с уровнем эксплуатационных свойств MIL-L-2105. Эти масла применяются предпочтительно в ступенчатых коробках передач и рулевых механизмах, в главных передачах и гипоидных передачах с малым смещением в автомобилях и безрельсовых транспортных средствах для перевозки грузов и пассажиров и для нетранспортных работ.

API-GL-5

Масла для гипоидных передач с уровнем эксплуатационных свойств MIL-L-2105 C/D. Эти масла предпочтительно применяются в передачах с гипоидными коническими зубатыми колесами и коническими колесами с круговыми зубьями для главной передачи в автомобилях и в карданных приводах мотоциклов и ступенчатых коробках передач мотоциклов. Специально для гипоидных передач с высоким смешением оси. Для самых тяжелых условий эксплуатации с ударной и знакопеременной нагрузкой.

Классификация ACEA

Классификация моторных масел AСEA адаптирована под новые технологии, принимающие во внимание Европейские требования к защите окружающей среды. Начиная с 1996 г. было издано несколько версий стандартов AСEA.

Соблюдение требований ACEA 2008 является обязательным условием с декабря 2010 г.

Версия ACEA 2008 определяет четыре категории бензиновых и дизельных двигателей (A1/B1, A3/B3, A3/B4, A5/B5), четыре категории автомобилей с системами доочистки выхлопных газов (C1, C2, C3, C4), и четыре категории дизельных двигателей, используемых на тяжелой технике (E4, E6, E7, E9), две из которых относятся к тяжелым транспортным средствам, оснащённым системами доочистки выхлопных газов DPF или CRT (E6, E9).

Категория А/B:
A – бензиновые двигатели

B – дизельные двигатели

 Без экономии топливаЭкономия топлива
Увеличенный интервал заменыA3 / B4A5 / B5
Стандартный  интервал заменыA3 / B3A1 / B1

Категория C:
Двигатели с системами доочистки выхлопных газов

 Без экономии топливаЭкономия топлива
Низкое содержание SAPSС4С1
Среднее содержание SAPSС3С2

 

Описание требований ACEA 2008 к маслам категории Low SAPS (низкое содержание серы, фосфора и сульфатных зол)

ХарактеристикиПоказателиЭкономия топливаКласс
Высокая экономия топлива
Низкое содержание SAPS		2. 9 ≤ HTHS 
P ≤ 0.05 %; 
S ≤ 0.2%,
CS ≤ 0.5 %		> 3%С1
Высокая экономия топлива
Среднее содержание SAPS		2.9 ≤ HTHS 
0.070 % ≤ P≤ 0.090 %,
S ≤ 0.3 %, 
CS ≤ 0.8 %		> 2.5%С2
Стандартная экономия топлива
Среднее содержание SAPS		HTHS ≥ 3.5 
0.070 % ≤ P≤ 0.090 %, 
S ≤ 0.3 %, 
CS ≤ 0.8 %		> 1% 
(вязкость xW-30)		С3
Сатндартная экономия топлива
Низкое содержание SAPS		HTHS ≥ 3.5 
Пониженная летучесть (≤11%) 
P≤ 0.090%, S ≤ 0.2%, SA ≤ 0.5%		> 1% 
(вязкость xW-30)		С4

HTHS — вязкость масла в условиях высокой скорости сдвига и высокой температуры.

Классификация ACEA для тяжелой техники

 Низкое содержание SAPSСреднее содержание SAPS
Расширенный интервал заменыE6E4
TBN ≥ 12%
Стандартный интервал заменыE9E7
TBN ≥ 9. 0%

TBN — щелочное число

КЛАССИФИКАЦИЯ МОТОРНЫХ МАСЕЛ SAE J300

Классификация SAEJ 300 используется для характеристики вязкости (сопротивления течению) масла при высоких и низких температурах.

SAE: Society of Automotive Engineers (Общество автомобильных инженеров, США).

ASTM

Класс вязкости по SAEНизкотемпературная вязкостьВысокотемпературная вязкость
 Проворачивание1), МПа*с, max при температуре, 
°С		Прокачиваемость2), МПа*с, max при температуре, 
°С		Кинематическая вязкость3), мм2/с при 100 °С
При высокой скорости сдвига4), МПа*с, при 150 °С и 106 с-1, min
   minmax 
0W6200 при -3560000 при -403,8——
5W6600 при -3060000 при -353,8——
10W7000 при -2560000 при -304,1——
15W7000 при -2060000 при -255,6——
20W9500 при -1560000 при -205,6——
25W13000 при -1060000 при -159,3——
20  5,69,32,6
30  9,312,52,9
40  12,516,32,9
(0W-40, 
5W-40, 
10W-40)
40  12,516,33,7
(15W-40, 20W-40,
40)
50  16,321,93,7
60  21,926,13,7

1. ASTMD 2602 – имитатор холодного пуска CCS
2. ASTMD 4684 и D 3829 – мини-ротационный вискозиметр MRV
3. ASTMD 445 – стеклянный капиллярный вискозиметр
4. ASTMD – конический имитатор подшипника HTHS

Пример: SAE 15W- 40

15W — Низкотемпературный класс вязкости.
Буква « W » означает winter (зима) 
Чем ниже класс, тем ниже температура возможного старта двигателя 
40 — Высокотемпературный класс 
Чем выше класс, тем выше температура, которую может выдержать масло (защита двигателя при высоких рабочих температурах).

SAE xxW-yy  — Всесезонное масло, например Quartz 9000 5W-40
SAE xxW  или SAE yy – Сезонное масло, например Rubia S 10W 

Сезонные масла, в основном, используются там, где нет сильных перепадов температуры и среднегодовая температура достаточно высокая. Всесезонные масла предлагаются как с зимней, так и с летней степенью вязкости.

Навигация
  • Главная
  • Качество
  • Продукция
  • О Eurol
  • Подбор масла
  • Спонсорство
  • Партнеры
  • Контакты
  • Карта сайта

Каталог

  • Смазочные материалы для легковых автомобилей
  • Смазочные материалы для грузовых автомобилей
  • Смазочные материалы для мотоциклов
  • Смазочные материалы для сельскохозяйственной техники
  • Смазочные материалы для водного транспорта
  • Смазочные материалы для промышленности
  • Смазочные материалы для мотороллеров и мопедов
  • Автохимия
  • Смазки
Контакты

г. Москва,
ул. Рябиновая, 28А, стр. 1
Тел. +7 (495) 380-28-44

Вакансии

более подробная информация о спецификациях ACEA и API для тяжелых условий эксплуатации (4/9)

техническая экспертиза

13.окт.2021

что такое ACEA, что такое API, и как связаны между собой две эти спецификации? читайте здесь.

Это вторая статья о спецификациях из нашей серии материалов, посвященных основам производства масел. Сегодня мы подробно рассмотрим спецификации для крупных транспортных средств, таких как грузовые автомобили и автобусы.


Особая роль спецификаций в сегменте тяжелых условий эксплуатации

Смазочные материалы для тяжелых условий эксплуатации и их усовершенствованные характеристики — главная тема на повестке дня:

  • Без большегрузных автомобилей мировая экономика, как мы ее знаем, была бы невозможна — и они продолжают играть свою ключевую роль. В то же время они оказывают значительное влияние на состояние окружающей среды с точки зрения выбросов парниковых газов. Смазочные материалы помогают ограничить объем таких выбросов.
  • Владельцев автопарков очень заботит эффективность собственного автопарка и показатели общей стоимости владения. И ключевую роль здесь, помимо прочего, играют смазочные материалы.


Класс масла ACEA E

В 1991 году была основана организация ACEA, Association de Constructeurs Européens d’Automobiles (в переводе с французского: Ассоциация европейских производителей автомобилей).

В общих словах, ACEA представляет автомобилестроительную отрасль Европы: производителей пассажирских автомобилей, фургонов, грузовиков и автобусов, предприятия которых расположены в ЕС. Членами Ассоциации являются национальные автомобилестроительные ассоциации и большинство производителей оригинального оборудования.

ACEA устанавливает минимальные стандартные требования к маслам в Европе. Эти требования члены ACEA предъявляют к маслам, используемым в производимых ими транспортных средствах — это так называемые спецификации. Масла, соответствующие классу E, покрывают двигатели для тяжелых условий эксплуатации


Почему ACEA обновила классификацию в 2016 году?

Предыдущая классификация ACEA была опубликована в 2012 году. В 2016 году ACEA установила новую классификацию, в основном, по трем причинам:

  1. Производители двигателей все больше уделяют внимания вопросам окисления и чистоты масел. Это связано с более широким использованием биодизеля и альтернативных видов топлива (таких как метанол и этанол).
  2. Процесс сжигания топлива у новых платформ двигателей имеет более высокую эффективность и происходит при более высоких температурах и более низком уровне образования сажи
  3. Новейшие двигатели используют более новые и более сложные уплотнительные материалы.

Обновление классификации 2016 означает, что смазочные материалы со спецификацией ACEA должны обладать обновленными характеристиками с точки зрения качества и эффективности.

Вы можете определить новые спецификации ACEA по суффиксу, обозначающему обновление 2016: E4-16, E6-16, E7-16 и E9-16.

Выпуск ACEA E6 2016 года обеспечивает защиту цилиндров, высочайший уровень совместимости с системами дополнительной обработки ОГ и защиту от коррозии.


Ключевая роль HTHS

HTHS означает «высокую скорость сдвига при высокой температуре». По мере эволюции двигателей «HTHS» лучше всего описывает их рабочую среду, в особенности, распределительный вал, коренные шейки, поршневые кольца и гильзы цилиндров.

Некоторые моторные масла рассчитаны на эти условия. Они называются «с низким HTHS». Такая характеристика широко ассоциируется с повышенной топливной эффективностью. Номер HTHS означает сопротивляемость текучести масла в горячем двигателе.


Об изменениях классификации API

API — это Американский институт нефтепродуктов, представляющий нефтехимическую и газодобывающую промышленность. Он включает более 625 членов из всех сегментов отрасли.

Как и ACEA, API определяет спецификации моторного масла. И так же, как ACEA, API ввела новые категории в 2016 году для определения вязкости масел с более низким HTHS по запросу производителей оригинального оборудования в 2011 году.

Эти категории включают:

  • API CK-4, превосходящий старый стандарт API CJ-4;
  • и API FA-4, соответствующий параметрам API CK-4, но еще более эффективный с точки зрения расхода топлива.

Одно из улучшений API CK-4 по сравнению с API CJ-4: повышенное загустение при окислении

 

API FA-4: существенное повышение топливной экономичности по сравнению с API CJ-4

Сохраненные действующие спецификации API:

  • API CJ-4: категория активной производительности для всех двигателей, включая высокотехнологичные двигатели с современными системами обработки ОГ.
  • API CI-4 PLUS: категория активной производительности для высокого образования сажи и высокой производительности EGR.
  • API CI-4: категория активной производительности для высокого образования сажи и высокой производительности EGR.
  • API CH-4: категория активной производительности для двигателей без современных систем обработки ОГ.


Что еще ожидается в сфере сокращения объемов выбросов и повышения топливной эффективности?

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

Производители двигателей уже ищут возможности повышения эффективности двигателей и сопутствующей экономии. Оптимизация конструкции двигателей продолжится.

Ожидается выпуск новой классификации ACEA в 2018 году, вероятно, под названием ACEA E8 и ACEA E11. Она будет связана с очередным повышением эффективности потребления топлива. Также, по заявления, в 2018 году появится новая категория «F» смазочных материалов с низким HTHS.

Шаг 2. Разработка спецификации API

Для разработки API, оценки цели и требований:

  • Определите тип API: это простой API, часть интеграции или часть серверной системы?

  • Понимать потоки данных: односторонние, двусторонние и более.

  • Ознакомьтесь с требованиями безопасности.

После того, как вы определите объем и поток своего проекта интеграции, определить спецификацию API в RAML или OAS. Затем, на более поздних этапах, вы будете использовать спецификацию API для быстрой разработки API.

Спецификации API и API

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

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

MuleSoft предоставляет инструменты, упрощающие создание спецификации API, которой вы можете поделиться со своей командой, клиентами или широкой публикой. Использование спецификации API ускоряет внедрение и сокращает время завершения проекта.

Шаг 2.1. Изучение существующих спецификаций API

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

Найти спецификацию API, которая уже делает то, что вам нужно, легко:

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

    Возьми меня на биржу

    1. Выберите Any Type > REST APIs (под строкой поиска), чтобы отобразить только спецификации REST API.

    2. Щелкните любую спецификацию, чтобы просмотреть типы данных и HTTP-запросы, определенные для API.

  • Посмотрите на Exchange для вашей организации (учетной записи). При входе в систему отображается частный Exchange вашей организации.

    Перенеси меня на платформу Anypoint

    1. Войдите в систему Anypoint Platform, если это необходимо.

    2. На целевой странице платформы Anypoint щелкните Обнаружить и поделиться в разделе Exchange .

    3. Щелкните любую спецификацию, чтобы просмотреть типы данных и HTTP-запросы, определенные для API. Если это пробная организация, возможно, вы еще ничего не увидите.

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

Шаг 2.2. Создайте спецификацию API

Создайте собственную спецификацию API для простого API Hello World, отвечающего на простой запрос GET. Для этого используйте API Designer, часть Design Center.

  1. Открытый дизайнер API:

    Перейти к дизайнеру API

  2. Нажмите Создать новый , чтобы открыть редактор API Designer.

  3. Нажмите Новая спецификация API .

  4. Введите hello-world для API Title и не меняйте другие значения по умолчанию.

  5. Нажмите Создать API . Редактор API Designer отображает пример определения RAML.

  6. Удалить существующий текст и вставить следующий RAML:

 #%RAML 1.0
Название: привет, мир
версия: v1
описание: Привет всему миру
типы:
 приветствие:
   характеристики:
     сегодняшнее приветствие: строка
/приветствие:
     получать:
       ответы:
         200:
           тело:
             приложение/json:
               тип: приветствие
               пример:
                 {сегодняшнее приветствие: "тестовое приветствие"}
         404:
           тело:
             приложение/json:
               характеристики:
                 сообщение: строка
               пример: |
                 {
                   "сообщение": "Приветствие не найдено"
                 }

Эта спецификация API содержит:

  • Один HTTP-запрос, GET

  • Один тип данных, приветствие с одним свойством, сегодняшнее приветствие и пример значения

  • Успешный ответ HTTP

  • Ответ об ошибке HTTP

Шаг 2.

3. Проверка спецификации API

Спецификация API hello-world.raml завершена. Теперь протестируйте его, отправив запрос. Служба имитации создает функционирующую конечную точку из вашей спецификации API. и предоставляет простой пользовательский интерфейс для управления аутентификацией, заголовками запросов и заголовками ответов.

Для проверки спецификации API:

  1. Открыть hello-world.raml , если он еще не открыт:

    Перейти к дизайнеру API

  2. Щелкните значок «Документация», если панель «Документация» еще не открыта.

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

  4. Нажмите GET для отображения запроса GET и дополнительной информации о спецификации.

  5. Нажмите Примеры кода , чтобы просмотреть образцы для каждого протокола.

  6. Нажмите 200 и 404 в разделе Responses , чтобы просмотреть ответы, определенные в спецификации API.

  7. Нажмите синюю кнопку Попробовать .

  8. Нажмите Отправить , чтобы отправить ваш запрос на временный URL-адрес запроса, созданный фиктивной службой на основе вашей спецификации.

    На этом экране можно безопасно игнорировать любые сообщения об ошибках. Успешный запрос возвращает 200 OK и тестовое сообщение:

  9. Щелкните Сведения об ответе в меню kebab, чтобы изучить заголовки ответов и заголовки запросов в фиктивной службе, чтобы помочь диагностировать проблемы или понять поведение вашей спецификации API.

  10. После завершения тестирования откройте панель Mocking Service Configuration , затем в Local Settings включите Select By Default .

Шаг 2.4. Опубликуйте спецификацию API

После того, как вы протестировали свой API, опубликуйте его на своем частном сервере Exchange, чтобы другие сотрудники вашей организации могли повторно использовать вашу работу.

  1. Открыть hello-world.raml , если он еще не открыт:

    Перейти к дизайнеру API

  2. Нажмите Опубликовать .

  3. Щелкните Опубликовать на Exchange .

  4. Примите все значения по умолчанию и введите номер версии в поле Версия актива .

  5. Нажмите Опубликовать на Exchange , а затем Готово .

После публикации любой сотрудник вашей организации может просмотреть спецификацию API hello-world и повторно использовать ее.

Что дальше

Теперь, когда вы разработали API и создали для него спецификацию API, используйте Anypoint Studio (Studio) для создания приложения Mule, которое содержит реализацию и интерфейс для API.

Подробные сведения для разработчиков

Если вам интересны подробности, переходите прямо сейчас.

Подробные сведения: Exchange

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

  • Помимо общедоступной биржи, вы можете ознакомиться с внутренними предложениями своей организации.

    Возьми меня на биржу

  • Если вы создали общедоступный портал для разработчиков, вы также можете просмотреть его, нажав Общедоступный портал .

Глубокое погружение: функции API

В типичном проекте API вы, вероятно, захотите сделать еще несколько вещей:

  • Добавить аутентификацию.

  • Добавьте аннотации, как определено в спецификации RAML.

    Перейти к спецификации RAML

  • Добавьте активы из Exchange с помощью API Designer или Studio.

  • Смоделируйте данные, предоставляемые вашей спецификацией API, с помощью Studio.

  • Модульность спецификаций для повторного использования с фрагментами API.

Разработчик и партнер Deep Dive

Чтобы поделиться и поддержать вашу спецификацию API, соберите отзывы о вашей спецификации API для следующей версии.

Как писать документацию API: лучшие практики и примеры

Время чтения: 9 минут

API заставляют мир вращаться. Разработчики используют API почти каждый день — по некоторым оценкам, они тратят более 10 часов в неделю на работу с API. Это относится не только к их использованию, но и к поиску поддержки, поиску поддержки в Google, изучению обзоров и, конечно же, копанию в документации. То, насколько понятным, простым, полезным и поддерживаемым является ваш API, определяет весь опыт разработчика (DX) — эмоциональную реакцию разработчиков на продукт. В экономике API фундаментальным является большой опыт разработчиков. API-интерфейсы, которые помогают разработчикам добиваться успеха и доставляют удовольствие при использовании, получат массу пользователей и превзойдут конкурентов. И это начинается именно в тот момент, когда они впервые открывают документацию.

Посмотрите это видео, чтобы познакомиться с документацией по API.

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

Что разработчики ненавидят в документации по API

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

Это написано не простым человеческим языком . Это распространенная проблема для автоматически созданных документов или документов, которыми пренебрегают создатели. Хотя многие инструменты для создания документации отлично справляются с комментированием кода, они не могут заменить фактические объяснения на английском языке, написанные разработчиком или техническим писателем.

Очень мало примеров кода . Это другой конец спектра, где объяснений много, но есть минимум примеров фактического кода.

Доступно только зарегистрированным пользователям . Этот не очень ловкий маневр ничего не делает для вашего маркетинга. Это только расстраивает людей, которые хотят знать, что делает ваш API, прежде чем решить, хотят ли они этого (как сделал бы любой здравомыслящий человек).

Это слишком длинно/не может быть найдено/неточно/не обновлялось лет и т. д. Создание хороших документов почти так же важно, как создание хорошего API. Потому что плохо написанные документы или те, которые нельзя найти, просто погуглив «Product API», сводят на нет все усилия по разработке. Если вам интересно, мы уже изложили особенности технической документации в целом. Но документы API заслуживают отдельной статьи. Так как до вы пишете отличные документы по API?

Внедрение разработки на основе спецификаций

Разработка на основе спецификаций (SDD) похожа на разработку на основе тестирования, при которой вы пишете тестовые сценарии для каждой функции, а затем пишете код, который должен их пройти. В SDD вы создаете документы или, по крайней мере, некоторые их части параллельно с созданием API, часто следуя определенному формату описания API, называемому спецификацией .

Спецификация API — это своего рода шаблон вашей будущей документации, единый язык, описывающий структуру вашего API, объясняющий, как он работает и чего от него ожидать. Существует несколько спецификаций, таких как RAML (язык моделирования RESTful API), OpenAPI (ранее Swagger) и API Blueprint, но существует тенденция объединения всех спецификаций под капотом OpenAPI.

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

Консоль API позволяет создать веб-портал для документов API на основе спецификаций RAML и OpenAPI.
Источник: Pawel Psztyc , созданные сообществом разработчиков для сообщества разработчиков, имеют парсеры на разных языках программирования и постоянную поддержку создателей.

Пишите для начального уровня

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

API, как и любой программный продукт, создается для определенной аудитории. Но аудитория документации обширна. Существует три основные группы пользователей документации:

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

И даже в каждой из этих групп есть люди с разными навыками, ролями и потребностями, и все они должны иметь положительный опыт работы с документами. Как вы ориентируетесь на них всех? Ориентируясь на наименее опытных пользователей. Итак, как вы пишете документы для новичка?

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

Документация по Amazon Alexa API начните с объяснения того, что делает Alexa и какую пользу она может принести клиенту

Покажите, с чего начать. Документы API печально известны тем, что они слишком громоздки и предполагают, что пользователи имеют большой опыт работы с API. Раздел «Начало работы» обязателен, и его следует написать с терпением для потенциального пользователя.

Facebook предоставляет четкую справочную информацию для начинающих и шаг за шагом описывает процесс начала работы

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

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

Обучение работе с внешними инструментами. Если ваш API требует использования и понимания сторонних продуктов и концепций, таких как OAuth или npm, включите ссылки на документы или руководства по установке.

Учиться легко. Документы API не являются инструкциями по сборке ИКЕА, они являются источником обучения. Дополните свою документацию часто задаваемыми вопросами, учебными пособиями, блогами и даже видео, когда это возможно.

Включить обязательные разделы

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

SmartBear опросила 3000 специалистов по API

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

Состояние и ошибки. Существуют стандартные коды состояния и коды, специфичные для вашего API. Рекомендуется включить все ошибки, которые могут быть вызваны вашим API. Ошибки часто помещаются на специальную страницу документов, но имеет смысл дублировать некоторые из них непосредственно в конечной точке, где они появляются чаще всего.

Аутентификация . Большинство документов API начинаются с проверки подлинности и авторизации. Он должен содержать информацию о том, как получить ключ API и как аутентифицировать запросы, включая возможные ошибки, время истечения срока действия токена и объяснение чувствительности аутентификации (в основном напоминая, что ключи не могут быть переданы и где их можно использовать).

HTTP-запросы . Предоставление веб-запросов в HTTP — это минимум документации. Обычно предполагается, что разработчики знают, как отправлять HTTP-запросы на выбранном ими языке, но иногда создатели API включают запросы на разных языках. Это можно сделать автоматически с помощью инструментов спецификации API и инструментов управления API, таких как Postman.

Использовать стандартный макет

Если вы используете генератор документации, макет уже выбран за вас. Большинство документов API выглядят одинаково. Если вы использовали несколько из них, вы знаете, как подходить к новым документам. Тем не менее, организовать большие объемы данных, сделать их доступными и удобными для навигации — сложная задача. Вот некоторые особенности наиболее функциональной планировки.

Динамический макет . Вы можете распознать устаревший API по его статической документации. В 2020 году одной страницы или даже документа в формате PDF недостаточно. Динамические документы легко просматривать, обновлять и добавлять в закладки.

Липкое содержимое . Нет, панель навигации не отвлекает и не занимает драгоценное место на экране. Всегда держите содержимое на виду.

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

Документы API HubSpot использовать трехколоночный макет

Использовать контрастные цвета для синтаксиса . Разработчики тратят много времени на просмотр ваших примеров кода, поэтому сделайте их читабельными и разделите разные компоненты по цвету.

Этот пример из Facebook Graph API документации также показывает, как вы можете использовать различные вкладки для выбора между SDK

Сохраненное состояние прокрутки . Это небольшая деталь, которую оценит любой разработчик. Вы также можете использовать якорные ссылки для указания разных разделов страницы на случай, если они копируют URL-адрес.

Поощрять обратную связь . Ваши документы — ваш главный маркетинговый инструмент. Если людям они понравятся, они будут использовать ваш API, а не API конкурентов, и привлекут к нему внимание сообщества. Обычное «Была ли эта страница полезной?» сообщение позволит вам узнать, насколько хорошо вы отвечаете на вопросы разработчиков, и форма обратной связи будет использоваться часто, пока вы ее выполняете.

Не бросайте свои документы

Устаревшие документы — самая большая проблема пользователей API. Это также одна из самых распространенных ошибок. Разработчики часто пишут об обновлениях через несколько дней после их выпуска, иногда ограничиваясь несколькими предложениями. Это происходит из-за того, что нет установленного процесса обновления документов, и за это никто не отвечает. Вот как обеспечить регулярные и полезные обновления документов.

Подготовить документы до обновления . Сделайте это дополнительным шагом в своем плане запуска, не развертывайте их, пока у вас не будет хорошо написанных, подробных и отредактированных абзацев для представления ваших обновлений.

Регулярно удалять устаревшие данные . Документы должны пересматриваться часто, по крайней мере, раз в несколько месяцев. Функции обратной связи с пользователями позволят вам раньше выявлять несоответствия, и всегда должен быть член команды, ответственный за их рассмотрение и реагирование на обновления.

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

Отличные примеры документации по API

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

Документация по Medium API

Документация по Medium API не обязательно соответствует всем правилам, которые мы перечислили сегодня, но они отлично подходят для ограниченной функциональности, поддерживаемой этим API — публикации и поиска публикаций на Medium. Они выложены на GitHub, имеют действительно короткое, но понятное содержание с кучей примеров, каждый из которых заканчивается расшифровкой всех параметров, упомянутых в коде, включая возможные ошибки. Это удивительно просто, но надежно — все предложения можно делать прямо на GitHub, а документация регулярно обновляется.

Документация API Mailchimp

Mailchimp осознает, что большая часть его аудитории — профессионалы в области маркетинга, и использует язык, который позволяет даже нетехническим людям понять, как работать с его API. На первый взгляд, каждый раздел имеет одинаковую структуру:

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

Для каждого фрагмента кода есть даже кнопка копирования — деталь, которую наверняка оценят нетехнари.

Документация по Twilio API

У Twilio очень хорошая документация по API. Хотя документы — это лишь верхушка айсберга всей помощи, которой делится Twilio, есть SDK на нескольких языках и примеры приложений для iOS, Android и Интернета. Во-первых, они следуют трехколоночной логике с кодом прямо справа от руководства. Самые простые действия объясняются подробно и содержат множество ссылок на дополнительную информацию и скриншоты. Отзывы также поощряются с помощью кнопки «Оценить эту страницу» и ссылок на службу поддержки и тега на StackOverflow.

Документация по API Spotify

Хотя документация по веб-API Spotify очень типична, в платформе Spotify for Developers содержится много дополнительной информации. Есть демонстрации основных функций, фиктивные приложения, живые примеры, созданные с использованием API и виджетов Spotify, оболочки для разных языков программирования и, конечно же, консоль. Консоль — это, по сути, интерактивная документация, в которую вы можете вводить свои (или образцы) данные и исследовать конечные точки в реальном времени. Мощные продукты наряду с обширной базой знаний делают Spotify надежным партнером, с которым любят работать разработчики.

Бережно относитесь к документам

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

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *