From 8a339ab06e5f6f21db4937a062cbf4b69752d802 Mon Sep 17 00:00:00 2001 From: Sergey Konstantinov Date: Sun, 28 Feb 2021 23:35:08 +0300 Subject: [PATCH] typos and style fixes --- src/en/clean-copy/02-Section I. The API Design/04.md | 3 ++- src/en/clean-copy/02-Section I. The API Design/05.md | 4 ++-- src/en/clean-copy/02-Section I. The API Design/06.md | 2 +- src/ru/clean-copy/02-Раздел I. Проектирование API/04.md | 3 ++- src/ru/clean-copy/02-Раздел I. Проектирование API/05.md | 2 +- src/ru/clean-copy/02-Раздел I. Проектирование API/06.md | 2 +- 6 files changed, 9 insertions(+), 7 deletions(-) diff --git a/src/en/clean-copy/02-Section I. The API Design/04.md b/src/en/clean-copy/02-Section I. The API Design/04.md index adcf0e6..9669c4d 100644 --- a/src/en/clean-copy/02-Section I. The API Design/04.md +++ b/src/en/clean-copy/02-Section I. The API Design/04.md @@ -200,6 +200,7 @@ Let's take a look at a simple example: what the coffee machine search function r { "results": [ { + "coffee_machine_id", "coffee_machine_type": "drip_coffee_maker", "coffee_machine_brand", "place_name": "The Chamomile", @@ -253,7 +254,7 @@ Let's try to group it together: // Place data "place": { "name", "location" }, // Coffee machine properties - "coffee-machine": { "brand", "type" }, + "coffee-machine": { "id", "brand", "type" }, // Route data "route": { "distance", "duration", "location_tip" }, "offers": { diff --git a/src/en/clean-copy/02-Section I. The API Design/05.md b/src/en/clean-copy/02-Section I. The API Design/05.md index 4f9046e..cc68553 100644 --- a/src/en/clean-copy/02-Section I. The API Design/05.md +++ b/src/en/clean-copy/02-Section I. The API Design/05.md @@ -978,7 +978,7 @@ You may note that in this setup the error can't resolved in one step: this situa ##### No results is a result -If a server processed a request correctly and no exceptional situation occurred — there must be no error. Regretfully, an antipattern is widespread — of throwing errors when zero results are found . +If a server processed a request correctly and no exceptional situation occurred — there must be no error. Regretfully, an antipattern is widespread — of throwing errors when zero results are found. **Bad** ``` @@ -1021,7 +1021,7 @@ The thing is that lots of parameters potentially affecting data formats depend n Sometimes explicit location passing is not enough since there are lots of territorial conflicts in a world. How the API should behave when user coordinates lie within disputed regions is a legal matter, regretfully. Author of this books once had to implement a ‘state A territory according to state B official position’ concept. -**Important**: mark a difference between localization for end users and localization for developers. Take a look at the example in \#12 rule: `localized_message` is meant for the user; the app should show it if there is no specific handler for this error exists in code. This message must be written in user's language and formatted according to user's location. But `details.checks_failed[].message` is meant to be read by developers examining the problem. So it must be written and formatted in a manner which suites developers best. In a software development world it usually means ‘in English’. +**Important**: mark a difference between localization for end users and localization for developers. Take a look at the example in rule \#19: `localized_message` is meant for the user; the app should show it if there is no specific handler for this error exists in code. This message must be written in user's language and formatted according to user's location. But `details.checks_failed[].message` is meant to be read by developers examining the problem. So it must be written and formatted in a manner which suites developers best. In a software development world it usually means ‘in English’. Worth mentioning is that `localized_` prefix in the example is used to differentiate messages to users from messages to developers. A concept like that must be, of course, explicitly stated in your API docs. diff --git a/src/en/clean-copy/02-Section I. The API Design/06.md b/src/en/clean-copy/02-Section I. The API Design/06.md index b0c910e..63002f9 100644 --- a/src/en/clean-copy/02-Section I. The API Design/06.md +++ b/src/en/clean-copy/02-Section I. The API Design/06.md @@ -20,7 +20,7 @@ POST /v1/offers/search // Place data "place": { "name", "location" }, // Coffee machine properties - "coffee-machine": { "brand", "type" }, + "coffee-machine": { "id", "brand", "type" }, // Route data "route": { "distance", "duration", "location_tip" }, "offers": { diff --git a/src/ru/clean-copy/02-Раздел I. Проектирование API/04.md b/src/ru/clean-copy/02-Раздел I. Проектирование API/04.md index 67c95f9..d0271b8 100644 --- a/src/ru/clean-copy/02-Раздел I. Проектирование API/04.md +++ b/src/ru/clean-copy/02-Раздел I. Проектирование API/04.md @@ -204,6 +204,7 @@ POST /v1/orders { "results": [ { + "coffee_machine_id", // Тип кофе-машины "coffee_machine_type": "drip_coffee_maker", // Марка кофе-машины @@ -261,7 +262,7 @@ POST /v1/orders // Данные о заведении "place": { "name", "location" }, // Данные о кофе-машине - "coffee-machine": { "brand", "type" }, + "coffee-machine": { "id", "brand", "type" }, // Как добраться "route": { "distance", "duration", "location_tip" }, // Предложения напитков diff --git a/src/ru/clean-copy/02-Раздел I. Проектирование API/05.md b/src/ru/clean-copy/02-Раздел I. Проектирование API/05.md index a3d9d4f..c38fdf5 100644 --- a/src/ru/clean-copy/02-Раздел I. Проектирование API/05.md +++ b/src/ru/clean-copy/02-Раздел I. Проектирование API/05.md @@ -1015,7 +1015,7 @@ POST /search Следует иметь в виду, что явной передачи локации может оказаться недостаточно, поскольку в мире существуют территориальные конфликты и спорные территории. Каким образом API должно себя вести при попадании координат пользователя на такие территории — вопрос, к сожалению, в первую очередь юридический. Автору этой книги приходилось как-то разрабатывать API, в котором пришлось вводить концепцию «территория государства A по мнению официальных органов государства Б». -**Важно**: различайте локализацию для конечного пользователя и локализацию для разработчика. В примере из п. 12 сообщение `localized_message` адресовано пользователю — его должно показать приложение, если в коде обработка такой ошибки не предусмотрена. Это сообщение должно быть написано на указанном в запросе языке и отформатировано согласно правилам локации пользователя. А вот сообщение `details.checks_failed[].message` написано не для пользователя, а для разработчика, который будет разбираться с проблемой. Соответственно, написано и отформатировано оно должно быть понятным для разработчика образом — что, скорее всего, означает «на английском языке», т.к. английский де факто является стандартом в мире разработки программного обеспечения. +**Важно**: различайте локализацию для конечного пользователя и локализацию для разработчика. В примере из п. 19 сообщение `localized_message` адресовано пользователю — его должно показать приложение, если в коде обработка такой ошибки не предусмотрена. Это сообщение должно быть написано на указанном в запросе языке и отформатировано согласно правилам локации пользователя. А вот сообщение `details.checks_failed[].message` написано не для пользователя, а для разработчика, который будет разбираться с проблемой. Соответственно, написано и отформатировано оно должно быть понятным для разработчика образом — что, скорее всего, означает «на английском языке», т.к. английский де факто является стандартом в мире разработки программного обеспечения. Следует отметить, что индикация, какие сообщения следует показать пользователю, а какие написаны для разработчика, должна, разумеется, быть явной конвенцией вашего API. В примере для этого используется префикс `localized_`. diff --git a/src/ru/clean-copy/02-Раздел I. Проектирование API/06.md b/src/ru/clean-copy/02-Раздел I. Проектирование API/06.md index 071e4c3..a7774a3 100644 --- a/src/ru/clean-copy/02-Раздел I. Проектирование API/06.md +++ b/src/ru/clean-copy/02-Раздел I. Проектирование API/06.md @@ -20,7 +20,7 @@ POST /v1/offers/search // Данные о заведении "place": { "name", "location" }, // Данные о кофе-машине - "coffee-machine": { "brand", "type" }, + "coffee-machine": { "id", "brand", "type" }, // Как добраться "route": { "distance", "duration", "location_tip" }, // Предложения напитков