Нужно ли обновлять основную версию API при добавлении нового поля в ответ JSON (HTTP GET)?

Question

Например, я создал API 1.0.0:

HTTP GET / getInfo без параметров.

Ответ:

{
    "info1": "..."
}

После выпуска 1.0.0 я хочу добавить новое поле:

{
    "info1": "...",
    "info2": "..."
}

1) Я не знаю, кто клиенты API. Но возможно (теоретически), что они используют не гибкую десериализацию / сериализацию, и у них будут проблемы. Это реальные случаи? Опасно ли это для клиентов?

2) Нужно ли обновлять версию API до 2.0.0 в этом случае? Или это будет 1.1.0?

3) Аналогичный вопрос о HTTP POST и его теле с новым полем.

Answer 1

Как правило, это не считается серьезным изменением, поэтому нет, основное изменение версии, вероятно, не требуется. Это все равно будет обратно совместимо, потому что старые клиенты могут просто игнорировать эти поля при десериализации JSON. (Большинство десериализаторов, таких как Newtonsoft в C#, уже будут автоматически игнорировать любые дополнительные поля, поэтому изменение кода не требуется).

Если вы удалили поля, добавили новые обязательные параметры и т. Д. c., тогда вам, вероятно, понадобится, потому что это может привести к поломке.

Answer 2

Я бы предложил подумать в рамках совместимости. Если вашим клиентам придется переписывать код, потому что вы их сломаете (например, из-за отсутствующих свойств), вам нужно будет изменить версию. Это также позволяет всем знать, что что-то существенно изменилось.

PS Возможно, вам следует сохранить старые версии конечной точки, если это возможно, или уведомить их заранее и (посредством ответа - возможно, устарели), что вы будете изменить вещи для них.