mirror of
https://github.com/twirl/The-API-Book.git
synced 2025-03-17 20:42:26 +02:00
typos and style fixes
This commit is contained in:
parent
816f22106d
commit
8a339ab06e
@ -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": {
|
||||
|
@ -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.
|
||||
|
||||
|
@ -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": {
|
||||
|
@ -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" },
|
||||
// Предложения напитков
|
||||
|
@ -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_`.
|
||||
|
||||
|
@ -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" },
|
||||
// Предложения напитков
|
||||
|
Loading…
x
Reference in New Issue
Block a user