## Имена методов Имена API считаются «хорошими», когда им присущи функциональность, выразительность, простота и предсказуемость Самое важное в имени — его способность четко передавать значение элемента, которому оно присвоено. Элемент может быть функцией или RPC (например, CreateAccount), ресурсом или сообщением (например, WeatherReading), полем или свойством (например, postal_address) либо чем-то совсем другим, тем же значением перечисления (например, Color.BLUE) Имена методоов должны быть выразительными, но только до той степени, в какой каждая часть имени оправдывает свое присутствие. ## Императивные действия У стандартных глаголов REST есть один важный общий аспект: они все представлены в повелительном наклонении. Иначе говоря, они все являются командами или приказами: "Удали эту информацию о погоде!", "Заархивируй эту запись журнала!" ### Важный вопрос при разработке - «Как должен выглядеть ответ?» Например, метод isValid(). Должен ли он возвращать простое логическое поле, указывающее на валидность входных данных? А может, в случае недействительности этих данных он должен возвращать список ошибок? С другой стороны, GetValidationErrors() оказывается более понятным: он возвращает либо пустой список при полностью валидных входных данных, либо список ошибок. Здесь в отношении формы ожидаемого ответа сомнений не возникает. ## Множественное число Чаще всего выбрают имена в единственном числе, такие как Book, Publisher и Author. Так как в дальнейшем имена будут обретать в API новые значения и цели. Например, на ресурс Book где-то может быть создана ссылка из поля Author.favoriteBook. Тем не менее, когда речь идет о множестве этих ресурсов, порой возникает дополнительная путаница. Если API использует RESTful URL, то имя коллекции из нескольких ресурсов почти всегда прописывается во множественном числе. К примеру, когда мы запрашиваем один ресурс Book, имя коллекции в URL почти однозначно будет выглядеть примерно так: /books/1234. ## Регистры Конкретный выбор не столь важен при условии, что он используется согласованно во всей программе. ``` UserSettings user_settings user-settings ``` Использование терминов "new" и "old" для называния методов API может быть неудачным подходом из-за нескольких причин: 1. **Неясность:** - Термины "new" и "old" не предоставляют ясного понимания того, что делает каждый метод. Они не описывают функциональность или назначение метода, что может затруднить понимание для разработчиков, использующих ваш API. 2. **Несогласованность во времени:** - Методы, обозначенные как "new" и "old", могут вызывать путаницу, особенно если в будущем появятся ещё новые методы. Как только метод "new" станет старым, возникает вопрос о том, как обозначать следующее поколение методов. 3. **Изменение предпочтений:** - Предпочтения и стандарты могут меняться со временем, и то, что сегодня считается "новым", завтра может быть устаревшим. Это может привести к тому, что название метода теряет актуальность и смысл. 4. **Неопределенность:** - Если методы представлены как "new" и "old", это может вызвать вопросы о том, что произойдет, если разработчики все равно решат использовать старый метод. Более ясные и информативные названия могут предотвратить подобные ситуации. Вместо использования "new" и "old" лучше давать методам более описательные и информативные имена, чтобы обеспечить понимание их функциональности. Это помогает сделать API более интуитивно понятным и уменьшить вероятность ошибок при использовании. ## АНТИПАТТЕРНЫ API ### Ресурсы для всего Cоздать ресурсы даже для малейшего компонента API ### Глубокие иерархии излишне углубленные иерархии могут сбивать с толку и создавать сложности в работе. ### Встраивание всего Зачастую возникает склонность денормализовать (или встроить) все данные, включая те, которые в прошлом были бы четко разбиты по отдельным таблицам для объединения с помощью модных SQL-запросов. ### РЕЗЮМЕ * В случае ошибок, которые являются краткосрочными или привязаны ко времени (например, 429 Too Many Requests), запрос, скорее всего, можно повторить. Если же ошибка связана с неким устойчивым состоянием (например, 403 Forbidden), то в большинстве случаев повтор окажется небезопасным. * Если код автоматически повторяет запросы, то должен полагаться на некую форму экспоненциальной выдержки с установленными лимитами для количества повторов и задержки между ними. В идеале он также должен вводить определенный джиттер, позволяющий избежать проблемы столпотворения, когда все запросы повторяются согласно одинаковым правилам, в связи с чем всегда прибывают на сервер в одно время. * Если сервису API известна какая-либо информация о том, когда запрос должен завершиться успешно, то он должен сообщить об этом клиенту с помощью заголовка Retry-After. * Для каждого значения необходимо учитывать и null, и undefined, или отсутствующее значение, которые могут как иметь, так и не иметь общий смысл. * Логические типы лучше всего подходят для флагов и должны именоваться так, чтобы истинное значение означало положительный аспект (например, enableFeature вместо disableFeature). * Численные значения должны нести смысл, а не просто состоять из цифр. * Чтобы избежать проблем с огромными числами (больше 32 или 64 бит) либо сложностей в арифметике с плавающей точкой в языках, не имеющих подобающих нативных представлений, численные значения нужно сериализовать в виде строк. * Строки нужно кодировать в UTF-8, а те, которые используются в качестве идентификатора, необходимо нормализовать в форму Normalization Form C. * Перечислений обычно желательно избегать, используя вместо них строковые значения и выполняя проверку на стороне сервера, а не клиента. * Списки необходимо рассматривать как атомарные элементы-коллекции, индивидуально адресуемые только на стороне клиента. * Как для списков, так и для карт нужно ограничивать общее количество до- пустимых в коллекции элементов. Однако карты должны дополнительно ограничивать размеры ключей и значений. * Идентификаторы— это значения, с помощью которых можно уникально указать на конкретные ресурсы в API. * Хорошие идентификаторы просты в использовании, уникальны, постоянны, непредсказуемы, легко читаются, копируются и передаются. При этом они также быстро и легко генерируются и имеют высокую информационную плотность. * С точки зрения клиента идентификаторы должны быть строками, которые используют набор символов ASCII, в идеале опираясь на формат сериали- зации Base32. * В идентификаторах должен присутствовать символ контрольной суммы для того, чтобы отличать несуществующий ресурс от ID, который никогда не мог указывать на ресурс (и скорее всего, является результатом ошибки).