The post has been translated automatically. Original language: Russian
A good API is recognized by a simple sign: the integrator connects to the documentation and does not write to you in the chat. The bad one is recognized just as easily, only dozens of questions come, and half of them are about behavior that is not described anywhere.
What most often breaks integration
- Errors without codes. A 400 response with the text "invalid request" forces the client to guess what exactly is incorrect. A machine-readable error code and an indication of a specific field remove most of the correspondence.
- Inconsistent names. There is a user_id in one method, a userId in the other, and an id in the third. It's a small thing, but the integrator stumbles on every method.
- Silent changes. The field has changed its type or stopped coming, and customers will know about it by dropped parsing.
- Lack of idempotence. The customer did not receive a response due to a timeout, repeated the request and created a second order. The problem is not the client, but the lack of an idempotence key.
- Pagination, invented on the fly. The offset breaks when the data changes between pages. Cursor pagination is more reliable.
The minimum that should be laid immediately
- Versioning. Even if there is only one version now, having the version in the path or header will save you the pain of the first breaking change.
- A single error format: a code, a human-readable message, a field, and a support request identifier.
- The correct status codes. 400 for client error, 401 and 403 for access, 404 for absence, 409 for conflict, 429 for limits, 5xx for failures only. Returning 200 with the success field inside is a habit that breaks standard libraries.
- Explicit request limits with remainder headers. The client must understand when they will be restricted before this happens.
- Documentation with examples of the entire request and response, including errors. Describing fields without examples hardly helps.
About backward compatibility
You can add fields, but you cannot delete or rename them. This simple rule saves months. If the change is still breaking, you need a new version, the lifetime of the old one, and a warning in advance. Deprecation without a shutdown date does not work: no one will migrate while the old one is responding.
Maturity check
Ask yourself one question: will an external developer be able to connect to your API without your participation? If the answer is no, the problem is not in his qualifications, but in the design of the interface and documentation.
What do you have more questions about during integration: error format, authorization, or pagination?
Резервные копии есть почти у всех. Проверенные копии есть у немногих. Разница выясняется в худший момент: когда данные уже потеряны и выясняется, что архив пустой, повреждённый или разворачивается двенадцать часов.
Что чаще всего идёт не так
- Копия делается, но никто ни разу не восстанавливал из неё данные. Работоспособность архива это предположение, а не факт.
- Копия лежит рядом с основной базой, на том же сервере или в том же аккаунте. Проблема с сервером или доступом уносит и данные, и копию.
- В копии не всё нужное. База есть, а загруженных пользователями файлов нет, или наоборот.
- Никто не следит за самим процессом. Задание упало три недели назад, ошибка ушла в лог, который никто не читает.
- Неизвестно, сколько занимает восстановление. Час и сутки это разные ситуации, но чаще всего эту цифру просто не измеряли.
Простое правило хранения
Три копии данных, на двух разных носителях или площадках, одна из них вне основной инфраструктуры. Схема старая, но она закрывает и поломку диска, и потерю доступа к аккаунту, и случайное удаление.
Два числа, которые стоит знать заранее
- Сколько данных допустимо потерять. Если копия снимается раз в сутки, вы теряете до суток работы.
- Сколько времени допустимо восстанавливаться. Это определяет, нужна ли вам просто копия или ещё и запасная среда, куда её можно быстро развернуть.
Пока эти числа не назвал бизнес, их назначает случай.
Минимум, который стоит сделать
- Проверить восстановление руками хотя бы один раз, полностью, на отдельной среде.
- Записать инструкцию по восстановлению, доступную не только автору настройки.
- Настроить уведомление о неудачном создании копии и, что важнее, о том, что копия не создавалась вовсе.
- Убрать у обычных сервисных доступов право удалять архивы.
- Ставить проверку восстановления в календарь раз в квартал.
Резервная копия это не файл, а процедура восстановления. Пока процедуру не прошли хотя бы однажды, у вас нет копии, у вас есть надежда.
А вы проверяли восстановление на практике или копии пока просто создаются по расписанию?
Share
