Прежде чем продолжать, нужно подчеркнуть важность того, что значение кода ошибки должно быть уникальным, специфичным и предназначенным для восприятия машиной, а не человеком.
Нередко это свойство интерфейсов называют гибкостью, подразумевая, что те из них, где пользователи могут свободно приспосабливаться к изменениям, являются гибкими, а те, где даже небольшие корректировки (например, переименование поля) приводят к полному сбою — ригидными.
Пользовательские методы — это не что иное, как вызовы API, которые выходят за рамки стандартного метода, в связи с чем не подпадают под строгие требования, которые предъявляются к стандартным методам. В следующем разделе мы увидим, что они могут выглядеть несколько иначе, но с чисто технической точки зрения в них нет ничего особенного.
Стандартные методы предлагают нам невероятно полезные компоненты для построения API, но ценой за столь широкий спектр является обширный набор руководств, правил и ограничений. С другой стороны, пользовательские методы практически ничем не ограничены, что позволяет им делать для сценария все необходимое, не вынуждая его вписываться в структуру и правила стандартных методов.
API редко остаются неизменными. Вместо этого они склонны постепенно развиваться в целях включения новых возможностей и исправления багов в существующих. И один из наиболее частых сценариев, на который мы в итоге опираемся, заключается в возможности добавлять в ресурсы новые поля, сохраняя обратную совместимость новой версии.
Стандартные методы — инструмент, позволяющий повышать согласованность и предсказуемость.
• Критически важно, чтобы все стандартные методы следовали одним и тем же принципам поведения (например, все методы Create должны действовать одинаково).
• Идемпотентность — характеристика, определяющая возможность повторяющегося вызова метода с получением идентичных результатов.
• Не все стандартные методы должны быть идемпотентны, но они не должны иметь побочных эффектов, при которых вызов метода вносит в систему API дополнительные изменения.
. А для остальных сценариев у нас есть пользовательские методы, которые мы изучим в следующей главе. Тем не менее стандартизация использования набора общепринятых строительных блоков настолько полезна, что практически всегда лучшим способом будет создание API с помощью стандартных методов, а пользовательские варианты применяются, только когда этого требует некий непредвиденный сценарий.
. А для остальных сценариев у нас есть пользовательские методы, которые мы изучим в следующей главе. Тем не менее стандартизация использования набора общепринятых строительных блоков настолько полезна, что практически всегда лучшим способом будет создание API с помощью стандартных методов, а пользовательские варианты применяются, только когда этого требует некий непредвиденный сценарий.
Если отвечать коротко, то да: этот механизм замены можно использовать для создания новых ресурсов, но он не должен становиться заменой стандартному методу Create, поскольку возможны случаи, в которых потребители API могут захотеть создать ресурс, если (и только если) этот ресурс еще не существует. Аналогичным образом они могут захотеть обновить ресурс, если (и только если) этот ресурс уже существует. При использовании метода Replace, несмотря на конечный успех, у вас нет возможности узнать, заменяете (обновляете) вы существующий ресурс или же создаете новый. Вместо этого вы знаете только то, что информация, однажды хранившаяся на месте конкретного ресурса, теперь заменена содержимым, переданным в запросе на замену.
Именно для этой цели и предназначен полустандартный метод Replace: заменить весь ресурс информацией, предоставленной в данном запросе. Это значит, что даже если у сервиса есть дополнительные поля, о которых клиенту еще не известно, эти поля, при условии их отсутствия в запросе на замену ресурса, будут удалены,
