Как правильно написать API сервиса?

Question

[arturich]

Здравствуйте, надо написать API к сервису.

Задача вроде бы понятная и вопрос уже много раз задавали тут, но… тут все посложнее. Собственно сейчас я поделюсь своим мнением и призываю к обсуждению оного.

Что хочется:

1. Версионность
2. Нет дублированию кода

Версионность

Неплохо, когда у сервиса есть API, но беда, когда он готовит новую версию, релизит её и все старые клиенты возможно перестают работать. Для этого и нужна версионность. И поддержка старых версий.

Я не сторонник архитектуры REST (не будем о ней), поэтому версию и тип данных будем передавать в урл, например service.com/api/v3/json/. Так же хочется ограничиться
только POST запросами с указанием вызываемого метода и сопутствующими параметрами. На данный момент жизни я считаю, что с этим сторонним разработчикам будет удобнее всего работать.

Нет дублированию кода

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

Думал так — если все же какую-либо обработку делать в контроллерах, то все равно от модификации моделей вы не убережетесь, а при правке моделей изменения будут влиять на все версии, поэтому модели все равно надо будет копировать или придумывать разноверсионное храниение — это не важно, главное, что изменениея будут в двух местах.

Приглашаю хорошенечко обсудить это решение.

Comments

[Mikhail Osher]

Вы уверены, что нужно дублировать модели?

[arturich]

Miraage Я писал, что «надо будет копировать или придумывать разноверсионное хранение». Я не против того, что копирование — это плохо. Но если кончается поддержка версии, то можно просто смело удалить папку моделей и всё.

Answer 1

[Алексей Журбицкий]

Занимался недавно подобным. У меня получились модели общие, обработка в контроллерах. И кстати уже когда делал — пытался представить ситуацию что необходимо будет делать еще одну версию — не получилось. Все гипотетические изменения укладывались в текущую версию с учетом обратной совместимости, но возможность версионности оставил.

Перед написанием изучил довольно много литературы, блогов и презентаций, начал даже писать статью на хабре но пока что лень победила. Самое полезное что я читал — REST API Design Rulebook, рекомендую.

Comments

[arturich]

Да, тут палка о двух концах. Google Api AdWords — прекрасный представитель, но там правда SOAP. Они в одной из последних версий очень много всего поменяли — модели и пр. А старые версии работали, поэтому решение есть, но какое-либо стройное решение в голову не идет.

Например, у меня есть объекты пользователей и действия с ними. А так же возможность ставить задачи на пересчет статистики по ним. И как бы хочется как методы типа getUsers, так и refreshUsersStatistics, а последнее вроде не особо вяжется с тем же REST full, хотя, я могу ошибаться, конечно же.

[Алексей Журбицкий]

Вяжется, нужно только немного привыкнуть. Например, можно так:

getUsers -> GET /users
refreshUsersStatistics -> POST /users/statistics/refresh

или даже так

refreshUsersStatistics -> POST /users-statistics/refresh

[arturich]

blo А как же версионность? Тут докладчик говорит, что REST предполагает, что все будет передаваться в http заголовках. Но тогда как же в вашем случае делать версионность методов? Надо будет следить за контролерами и экшенами. В моем случае будет один контроллер и один экшен — остальное в моделях.

[Вячеслав Слинько]

А что мешает на основе заголовка применить контролер иной версии.

[Алексей Журбицкий]

+arturgspb Лично у меня это выглядит так (как и во многих рекомендациях):

GET http://v1.api.example.com/users
Accept: application/json

Во фронт контроллере определяется версия и уже дальше используется соответствующий неймспейс/папка, в которой и лежат контроллеры, соответствующие версии.

[arturich]

KeepYourMind Да просто в url нагляднее это

[arturich]

blo А если мне надо получить список пользователей, у которых ДР 1988 года, то я в GET параметрах это должен передавать? А если условий не дай бог больше 4Кб? =)

[Алексей Журбицкий]

arturgspb Вы так спрашиваете как будто я сам придумал концепцию REST API :) Хотя признаю, у меня по началу тоже были такие вопросы. А фильтры да, нужно передавать в GET параметрах. Если GET запрос вышел больше 4Кб (хотя сложно представить) то или вы не правильно спроектировали свое API, либо REST конкретно в вашем случае не подходит.

/users?birth_year=1988

[arturich]

blo Да, я тут подумал, что если речь идет о фильтрации данных с передачей массива int64, то url вполне может не хватить, а жаль. Но в процессе разбора полетом RESTful, пожалуй, он мне понравился

Answer 2

[arturich]

KeepYourMind Да просто в url нагляднее это

Comments

[arturich]

не туда написал

Answer 3

[Андрей Григорьев]

jacobian.org/writing/rest-worst-practices/ хорошая статья

Comments

[arturich]

Спасибо, но мой вопрос был не про REST. Я уже писал, что REST предполагает делать грубо говоря select через GET запрос с GET-параметрами, а если у меня параметров много, то есть риск, что они в http запрос просто не поместятся. И что мне тогда с RESTархитектуры переводить все?)

[Алексей Сундуков]

«Кролики, это не только ценный мех, но и… » (с)
REST это не только GET, но и POST, PUT и даже DELETE методы!

[arturich]

alekciy Окей, мне DELETE не нужен в силу того, что объекты не должны удаляться никогда. Нужна смена статусов — ENABLE, PAUSE, ARCHIVE и получается это надо делать через POST или PATCH (но PATCH не в стандарте)

Answer 4

[egorinsk]

Дублировать модели нельзя по определению. У вас изменилась структура данных в хранилище (например, в БД), а вы работаете с новой таблицей при помощи старого кода?

Выход только один — сделать API из как можно более простого и тонкого слоя контроллеров, и при изменении моделей править их. Можно подумать над генерацией АПИ автоматически, например, на основе описания (имя функции АПИ — задействованные модели — передаваемые поля и их преобразование), если это возможно. Из этого же описания можно при особо удачном раскладе генерировать документацию на АПИ.

Comments

[egorinsk]

В любом случае, какие-то затраты на поддержку совместимости и версионности будут, вы можете их как-то минимизировать, но они все равно будут.

[arturich]

«Дублировать модели нельзя по определению.» Где написано?
" У вас изменилась структура данных в хранилище (например, в БД), а вы работаете с новой таблицей при помощи старого кода" все равно что-нибудь придется менять — либо модели, либо контроллеры.

А что вы имеете ввиду под «как можно более простого и тонкого слоя контроллеров»? Какую логику вы предлагаете перенести в контроллеры?

У нас в проекте модель — не просто, образно говоря, представление записи в таблице, а довольно толстая и сложная вещь, и работа теоретически с ними может меняться от версии к версии. У меня идея вообще избавиться от контроллеров — будет только один с одним индексным экшеном, который будет решать к какому методу какой модели слать запрос.

P.s. Единовременно можно поддерживать только две версии и тогда копия моделей будет всего одна, зато вся логика в них.