Нескучный API15.12.2017 15:03

Как создать АПИ для умных? Такое апи, чтобы создание клиента для него было не скучным механическим процессом, а настоящим приключением с элементами детектива, хоррора и мистики? Такое апи, о котором пользователи будут взахлёб рассказываете коллегам? Апи взрывающее мозг, заставляющее смеяться, кричать и плакать? Я постарался отобрать лучшие практики, с которыми пришлось столкнуться.

Делай так

Избегай очевидных названий. checkInDate лучше записать как start_date, еще лучше как sd, еще лучше как d. Тогда длинное и некрасивое checkInDate/checkOutDate превратится в лаконичное d1/d2. Еще больше отличных идей по именованию можно почерпнуть в книге «Совершенный код» в главе «Сила имен переменных»
Не используй стандарты. ISO 8601? Чтобы преобразовывать дату с использованием стандартных библиотек, имеющихся в любом языке программирования и не написав ни одной регулярки? Скукота.
Не используй в названиях термины предметной области. Лучше придумай что-нибудь максимально абстрактное.
Придумай свою систему обозначения состояний. К примеру: 1,2,3 — есть, нет, под заказ. Не вздумай писать состояния напрямую и уж тем более, никогда не используй справочник состояний.

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

{
Jacket: \[{MaterialsIds=”m1,m2”, Pockets: "p1”, Price: 12000}\], 
Materials: \[{Name: "Stormscale”, Color: "Tear of Elune”,  InnerId=”m1”}, 
             {Name: "Feather of Valor”, Color: "unpredictable”, InnerId=”m2”}\], 
Pockets:\[{Type: "Invisible”, Contents: "Soap”, InnerId="p1"}\]}
}

Не повторяйся.

a. Придумай разные системы для обозначения состояний разных объектов. К цифровой, описанной выше, можно добавить цветовую: green, red, yellow.

b. Меняй не только формат данных, но и формат записи названий полей — srart_date: 25/12/05, endDay: 2012.11.23.

c. Не забудь про огромный выбор разделителей: запятая, точка, точка с запятой. Добавь в него что-нибудь нестандартное — знак процента или решетку.

j. Список можно продолжать, будь креативен.
Замени True/False на 1/0, а ещё лучше на 0/1. Превратив простое «has_goods: True» в четыре вопроса — айдишник? количество? просто «да»? или, таки, «нет»?
Используй битовые флаги. Так ты продемонстрируешь свою исключительную образованность. Переведи их в десятичную форму для меньшей очевидности. Не передавай маску вместе с флагами, или даже в отдельном словаре. «flgs: 16» в структуре и список флагов в документации — прекрасный вариант.

Старайся засунуть в каждое поле как можно больше смыслов.

has_goods может принимать значения [-2, -1, 0, любое положительное число], 
что значит: [уточните, нет в продаже, нет в наличии, количество товара в наличии]

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

Добавь в запрос параметр, смысл которого будет менять в зависимости от значения другого, необязательного, параметра.

http://example.com/myService?cloth_type=silk&and_better=1
Где  "cloth_type"  - обозначает конкретный тип ткани (тут, естественно, требуется название ткани строкой, даже если есть справочник тканей, в котором указаны их айдишники), а "and_better" делает его началом диапазона с константным концом. Для "большей гибкости” можно дать параметру "and_better" второе значение (-1, 0, false, not) или добавить необязательный параметр "and_worst" и обрабатывать тот, который стоит первым/последним, либо сначала проверять наличие первого, а при его отсутствии - второго.

Задавай диапазоны на перечислимых данных последовательным списком, а на данных, порядок которых определен только в твоём приложении, началом и концом диапазона, а еще лучше через дефис или другой разделитель по вкусу.
```
http://example.com/myService?d=11.12.05&d=12.12.05&d=13.12.05&colors=green;yellow
```

Используй однотипные названия для полей с разными типами данных.

http://example.com/myService?cats=5&dogs=4&hamsters=0 где cats и dogs интовые поля обозначающие количество, а hamsters битовое поле обозначающее наличие.

Не обрабатывай ошибки. Переданы несовместимые параметры? Пустой ответ должен стать достаточной подсказкой. Или отсутствие ответа. Или отправь эксепшн сгенерированный твоим приложением.
Документация не нужна.

a. Если пришлось документировать, пропусти наиболее «очевидные» места.

b. Не усложняй документацию примерами.

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

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

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

P.S. Напишите о своих героях и их былинных деяниях в комментариях.