search

twirl / The-API-Book

‘The API’ book by Sergey Konstantinov
Other
731 stars 38 forks source link

Fix design api ru #21

Closed Callista-del-Mar closed 2 years ago

Callista-del-Mar commented 2 years ago

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

Татьяна

In src/ru/clean-copy/02-Раздел I. Проектирование API/01.md:

@@ -8,6 +8,6 @@

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

-Может показаться, что наиболее полезные советы приведены в последнем разделе, однако это не так; цена ошибки, допущенной на разных уровнях весьма различна. Если исправить плохое именование довольно просто, то исправить неверное понимание того, зачем вообще нужно API, практически невозможно. +Может показаться, что наиболее полезные советы приведены в последнем разделе, однако это не так; цена ошибки, допущенной на разных уровнях весьма различна. Если исправить плохое именование довольно просто, то исправить неверное понимание того, зачем вообще нужно API практически невозможно. Имеется в виду что понимание (того, зачем нужно API) невозможно исправить, соответственно, обе запятые нужны.

In src/ru/clean-copy/02-Раздел I. Проектирование API/05.md:

@@ -113,28 +113,28 @@ strpbrk (str1, str2)

Если поле называется recipe — мы ожидаем, что его значением является сущность типа Recipe. Если поле называется recipe_id — мы ожидаем, что его значением является идентификатор, который мы сможем найти в составе сущности Recipe.

-То же касается и примитивных типов. Сущности-массивы должны именоваться во множественном числе или собирательными выражениями — objects, children; если это невозможно (термин неисчисляемый), следует добавить префикс или постфикс, не оставляющий сомнений. +То же касается и примитивных типов. Сущности-массивы должны именоваться во множественном числе или собирательными выражениями — objects, children; если это невозможно - термин неисчисляем, следует добавить префикс или постфикс, не оставляющий сомнений. Имеется в виду: если это невозможно (потому что термин неисчисляем), то следует…

In src/ru/clean-copy/02-Раздел I. Проектирование API/05.md:

Отдельное важное следствие: не используйте инкрементальные номера как идентификаторы. Помимо вышесказанного, это плохо ещё и тем, что ваши конкуренты легко смогут подсчитать, сколько у вас в системе каких сущностей и тем самым вычислить, например, точное количество заказов за каждый день наблюдений.

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

Состояние системы должно быть понятно клиенту

-Правило можно ещё сформулировать так: не заставляйте клиент гадать. +Правило можно ещё сформулировать так: не заставляйте клиента гадать. Клиент в данном случае неодушевленное, сторона клиент-серверного взаимодействия.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or unsubscribe. Triage notifications on the go with GitHub Mobile for iOS or Android.