Как обстоят дела с вашим API?

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

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

• Включение проверки запроса через ресурс Request Validator (AWS API Gateway API)
• Выполнение поиска клиента с помощью ресурса поиска клиентов (Google Customer Search API)
• Выполнение мощных проверок кода через ресурс Check Runs (Github API)

В английской грамматике существительные, которые на самом деле являются двумя существительными, соединенными каким-либо образом, называются составными существительными, а в английской грамматике составные существительные следуют одному из трех шаблонов:

1. Все одним словом: стрижка, зубная паста
2. Два слова: тропический лес, мороженое
3. Перенесенный: самоуважение, зять

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

Чехол верблюда

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

1. Начальный верхний регистр (также известный как регистр Паскаля ) — это то, где первая буква также является заглавной, например: IceCream . Случай Паскаля популярен в языках программирования для именования классов, например, Java.
2. Начальная строчная буква — это когда начальная буква всегда строчная , например: iceCream . Этот подход популярен в языках программирования ( опять же, Java — хороший пример ) для именования переменных. Когда люди говорят «случай верблюда», они обычно ссылаются на исходный формат нижнего регистра.

Кебаб Кейс

В случае с кебабом отдельные слова разделяются дефисами. Мороженое выражается как мороженое . Этот подход используется в языке программирования Lisp во многих URL-адресах (например, в каждом сообщении в блоге на сайте www.blogger.com, например, http://dublintech.blogspot.com/2018/08/oauth-20-authorisation-code- grant.html).

Наблюдатель среди вас заметит, что слово « тире» иногда используется в технических справочниках вместо « дефис». Так в чем же разница? В грамматике английского языка дефис — это то, что используется для объединения двух слов в одно, а тире — это то, что обычно добавляет какой-то стилистический акцент в конец предложения, например: «У меня может быть интересный момент — вы никогда знать » .

В программировании нас не волнует, является ли термин дефисом и тире . Они используются взаимозаменяемо и означают одно и то же.

Подход кебаба стал популярным в веб-URI, потому что поисковые системы знали, что дефис означал отдельные слова и могли правильно индексировать URI. Это соглашение, используемое поисковыми системами, означало, что дефисы стали стандартом де-факто для URI.

Чехол змея

В этом подходе подчеркивание используется для разделения слов. Мороженое становится мороженым. Этот подход используется в Python и Ruby для всего, кроме имени класса или статической константы.

Присоединяйся слова

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

API-интерфейсы

Должны ли мы использовать camelCase, kebab-case или snake_case в API? К сожалению, диссертация мистера Филдинга не вдавалась в такие подробности. Так что же на самом деле делают люди? И является ли этот подход согласованным для URL-адреса API и тела JSON. Давайте взглянем.

AWS

У AWS разные стили API для разных сервисов. Ссылка API REST API Gateway показывает, что полезная нагрузка JSON использует случай верблюда
но URL ничего не использует, это просто:

Google

Сюрприз, сюрприз Google также имеет много API . Google

API пользовательского поиска аналогичен API-интерфейсу AWS API Gateway. Составное существительное в URL — это всего лишь одно слово, а тело JSON — верблюжий падеж.

Google Gmail API имеет верблюжий регистр в теле запроса и в некоторых URL, например, API адресов переадресации .

Google YouTube API иногда использует кебаб в URL, например
yt-analytics, но в других случаях будет использоваться одно слово, например youtubepartner. Но полезная нагрузка JSON — верблюжий случай.

Github

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

Однако, еще немного, и вы найдете составное существительное, такое как проверка выполнения, выраженная с использованием регистра kebab в URL, и его тело JSON с использованием регистра snake.

нашивка

Полоса использует случай змеи в URL и в теле JSON. Например,
PaymentsIntents API .

и тело JSON …

Paypal

В Paypal больше составных существительных, чем в других проверенных API. API для ресурсов, таких как соглашение о выставлении счетов, API будет использовать регистр кебаба в URL, а затем использовать регистр змеи в полезных нагрузках JSON.

щебет

Твиттер использует регистр змей в URL-адресе, например, / save_searches /, и регистр змей в полезных нагрузках JSON.

facebook

API Graph Facebook имеет тенденцию избегать именования ресурсов в URL, а в телах JSON это случай змеи.

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

Все разные, что мне делать?

Таким образом, в отрасли отсутствует согласованность. Однако есть смысл сделать следующее:

1. Вообще составные существительные лучше избегать. Во всех проверенных API (кроме PayPal) они отображаются в менее чем 5% API. Это означает, что разработчики не расстраиваются, когда их любимый подход не используется.
2. Единственным веб-API в приведенном выше выборе, в котором более 5% API-интерфейсов использовали составные существительные, был PayPal, и они использовали кебаб-кейс в URI.
3. kebab-case никогда не используется ни в одном теле JSON. Синтаксис разрешен. Так что движет этой тенденцией? Это более чем вероятно, потому что веб-интерфейсы JavaScript, возможно, являются самым популярным клиентом, вызывающим API, и аналогичным образом наиболее популярным внутренним языком, обслуживающим API, является Java, и оба этих чувака не допускают ни в одном из своих объявлений.

Принять решение

1. Избегайте составных существительных, если можете. Это не всегда возможно. Придерживаться вездесущего языка важно и полезно. Если у вас сложное бизнес-приложение, у вас будет много составных существительных.
2. Если вы не можете избежать составных существительных, и более 5% API будут включать составные существительные, используйте регистр кебаба для ваших URI. Почему? Потому что если у вас сложная бизнес-сфера, вам нужно думать не только о разработчиках. Многие бакалавры, архитекторы продуктов, любопытные менеджеры также будут смотреть на ваши API. Кебаб-кейс легче всего читать всем.
3. Для тела JSON, я думаю, что можно использовать camelCase, потому что это проще всего отобразить обратно на JavaScript и код Java. Google также рекомендует использовать camelCase в JSON.
4. Если вам нужно использовать camelCase в ваших URI, рассмотрите возможность использования подхода с заглавной буквой для URI, поскольку URI должны маркировать ресурсы, а не атрибуты. Ресурсы более аналогичны Java-классам, которые также используют начальный буквенный формат; тогда как атрибуты полезной нагрузки JSON аналогичны атрибутам Java, которые используют начальный нижний регистр.

До следующего раза, береги себя.