Несколько недель назад, мы публично выпустили Gauges API. Несмотря на уже существующий Gauges, было не мало работы во время написания API. Необходимо подробно разобраться с деталями.

1. Пишите документацию во время создания API

Мы допустили ошибку, занявшись подготовкой документации после того как API был практически готов. Проблема в том, что документирование ― отстой. Оставляя эту рутину на потом, когда вы уже рады бы выпустить в свет API, делает работу вдвойне сложнее. К счастью, у нас были те кто проходил это раньше.

2. Будьте постоянным

При написании документации нашего API, мы заметили много не согласующихся моментов. Например, в некоторых местах мы возвращали хэш, а в других ― массив. Понимая проблему мы начали создавать некоторые правила.

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

Замена массивов на хеши означала то, что нам нужно пространство имен (namespace) для массивов с ключами. Далее мы заметили, что не все имело свое пространство имен. И снова, мы придумали правило. В этом случае, все объекты верхнего уровня должны иметь пространство имен, но детям этих объектов или наборам нескольких объектов не обязательны пространства имен.

{users:[{user:{...}}, {user:{...}}]} // нет
{users:[{...}, {...}]} // да
{username: 'jnunemaker'} // нет
{user: {username:'jnunemaker'}} // да

Ну вы поняли. Постоянство ― важно. Всегда следует придерживаться одного формата.