-
Notifications
You must be signed in to change notification settings - Fork 0
/
problems.txt
65 lines (55 loc) · 4 KB
/
problems.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
НЕКОТОРЫЕ ПРОБЛЕМЫ РЕАЛИЗАЦИИ API
которые оставляют не очень приятное впечатление
и потребовали дополнительных затрат на реализацию клиента и его тестирование.
Думаю, что кто реализовывал клиенты на разных языках, а также использовал в своих приложениях столкнулись с теми же проблемами.
Хотелось бы:
- более четкое определение сущностей
- унификация наименований
- разделение API для стронних пользователей и внутренних технологических потребностей
- четкая типизация
- иметь в том числе и не перегруженные ответы
- некоторые свойства по назначению можно объединить в одно свойство типа Flags
- поддержка спецификации OpenAPI
На примере Model: TrackingDocument, Method: GetStatusDocuments
---------------------------------------------------------------
Нет унифицированной политики наименования свойств запросов и ответов (CamelCase или PascalCase, разные имена в методах для одного и того же свойства сущности, ...).
Не всегда информация об ошибке верная
Пример. При определении общей политики наименования CamelCase возвращается ошибка "Error: wrong format. Documents must be array".
Свойства могут иметь разные типы.
Пример. ExpressWaybillAmountToPay - разные типы: string, number
Свойства даты и времени могут не соответствовать стандарту в json (ISO 8601-1:2019)
Примеры
- ScheduledDeliveryDate - в формате "02-09-2022 12:00:00"
- dateScan - "16:08 02.09.2022"
Свойства даты и времени, булевы, целые и десятичные когда не определены, то представлены пустой строкой, а не null
Возвращаемое значение:
- очень перегружено
- есть похожие свойства, но не всегда понятно описание, чем отличаются
- не сгрупированы логически (по подобъектам, например, SenderInfo, RecipientInfo, Cargo, CargoMovement, CargoStorage, Costs, Payments, ...)
Стандартизованные форматы даты и времени для json, xml
------------------------------------------------------
/// <summary>
/// ISO 8601 date time parser (ISO 8601-1:2019).
/// </summary>
/// <remarks>
/// Supports extended calendar date (5.2.2.1) and complete (5.4.2.1) calendar date/time of day
/// representations with optional specification of seconds and fractional seconds.
///
/// Times can be explicitly specified as UTC ("Z" - 5.3.3) or offsets from UTC ("+/-hh:mm" 5.3.4.2).
/// If unspecified they are considered to be local per spec.
///
/// Examples: (TZD is either "Z" or hh:mm offset from UTC)
///
/// YYYY-MM-DD (eg 1997-07-16)
/// YYYY-MM-DDThh:mm (eg 1997-07-16T19:20)
/// YYYY-MM-DDThh:mm:ss (eg 1997-07-16T19:20:30)
/// YYYY-MM-DDThh:mm:ss.s (eg 1997-07-16T19:20:30.45)
/// YYYY-MM-DDThh:mmTZD (eg 1997-07-16T19:20+01:00)
/// YYYY-MM-DDThh:mm:ssTZD (eg 1997-07-16T19:20:3001:00)
/// YYYY-MM-DDThh:mm:ss.sTZD (eg 1997-07-16T19:20:30.45Z)
///
/// Generally speaking we always require the "extended" option when one exists (3.1.3.5).
/// The extended variants have separator characters between components ('-', ':', '.', etc.).
/// Spaces are not permitted.
/// </remarks>
?