Разработка API: недокументированные ключи объекта и массив объектов - PullRequest
Новая
       29

Разработка API: недокументированные ключи объекта и массив объектов

0 голосов
/ 15 января 2019

Для этой проблемы разработки JSON API у меня есть произвольный набор пар ключ-значение, которые должны быть предоставлены в теле запросов / ответов API. И ключи, и значения неизвестны. Каков наилучший способ структурировать это?

Насколько я могу судить, есть два способа сделать это:

1. Недокументированные ключи объекта 

{
    "fruit": "Apple",
    "sport": "Hockey",
    ...
    "keyN": "valueN"
}
  • PROS: Очень чистый, простой для анализа приложением логика
  • CONS: Этот объект не может быть надлежащим образом задокументирован - форма объекта бесконечно произвольна.

2. Массив объектов 

[
    {
        "key": "fruit",
        "value": "Apple"
    },
    {
        "key": "sport",
        "value": "Hockey"
    },
    ...
    {
        "key": "keyN",
        "value": "valueN"
    }
]
  • PROS: Легко документировать и понимать как массив объектов с известной структурой.
  • CONS: логика приложения будет более многословной.

Каков наилучший способ структурировать это?

ПРИМЕЧАНИЕ. Это вопрос к документации API, а не к логике приложения. Как отмечалось выше, я хорошо знаю, что # 1 - лучшее решение для манипуляций в коде. Но мне пока неясно, как документировать это в API-документах таким образом, чтобы они всегда были правильно интерпретированы

Ответы [ 3 ]

0 голосов
/ 15 января 2019

Я очень, очень настоятельно рекомендую # 1. № 2 - извращение. Ваша структура данных - это словарь. Не используйте массив для реализации словаря, но с половиной функций.

Подумайте об этом: вы говорите, что не можете документ № 1. Так как вы собираетесь документ № 2? Если # 1 не должен содержать ключ «клубника», как вы документируете, что # 2 не должен содержать словарь с парой (ключ, значение) ключ = «ключ», значение = «клубника»?

Как вы проверяете, содержит ли # 1 или # 2 ключ "фрукты", и каково значение? # 1 - прямой доступ. dict ["фрукт"]. В # 2 вам нужно перебрать элементы массива, убедиться, что все они являются словарями, проверить, есть ли один с ключом ввода: «fruit», проверить, что у него есть еще одна запись «value». Может быть, если вам платят строки кода, вы бы это сделали.

Достаточно забавно, три совершенно разных ответа, каждый с понижением. Очевидно, что по крайней мере два downvoters глупы.

0 голосов
/ 15 января 2019

Лично я не вижу большой разницы между # 1 и # 2 с точки зрения документации. Если поля неизвестны, тогда пустая карта / объект или пустой массив на самом деле не имеют значения.

Я видел, что это называется «Json Junk Drawer».

Одно добавление, которое я видел, это именованная карта / объект, специфичный для 'Json Junk Drawer', такой как: 

{
  "fieldsThatDontChange" : "example",
  "attributes" :{
    "unknownfield" : "unknown"
  }
}

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

Вот еще немного информации о ящиках мусора JSON, на которых есть несколько ссылок на видео YouTube, обсуждающие эту тему:

http://apievangelist.com/2015/01/21/rest-api-design-bridging-what-we-have-to-the-future-by-organizing-the-json-junk-drawer/

0 голосов
/ 15 января 2019

Лучшее решение:

2. Массив объектов 

[
    {
        "key": "fruit",
        "value": "Apple"
    },
    {
        "key": "sport",
        "value": "Hockey"
    },
    ...
    {
        "key": "keyN",
        "value": "valueN"
    }
]

Массивы - это именно тот шаблон, который следует использовать, когда задействована произвольная длина. Это более многословно, но легче понять. Благословение многословия.

...