[Из песочницы] Запросы к Rest API из JavaScript компактно и красиво31.05.2016 15:33

Делал я тут небольшой проект на чистом JS и в ходе оного потребовалось работать с Rest API. Ну не ручками ведь XMLHttpRequest дёргать, решил я, наверняка есть бесчисленное количество готовых решений для такой простой задачи?…

Как можно догадаться по КДПВ, я несколько ошибался; впрочем, обо всём по порядку. Но если вкратце — получился вот такой симпатичный велосипедик, с которым запросы к Rest API получаются, как и обещано в заголовке, компактными и красивыми.

image

Итак, мне был нужен джаваскриптовский клиент для Rest API. Гугл выдал чуток библиотек — restful.js, rest, amygdala. На самом деле, была ещё вот такая библиотечка, но это плагин к jQuery. jQuery в проекте не используется и тащить его как-то не хотелось; но, отчасти, предлагаемый библиотекой синтаксис мне понравился и это ещё всплывёт впоследствии.

Amygdala отпала сразу — нет Promise, а значит нет и async/await. Ещё и границы функциональности у неё странные, amygdala скорее претендует на что-то вроде недо-data-layer; про отсутствие сбилженной версии и лишние зависимости я тактично умолчу.
Осталось два кандидата — restful.js и rest.

rest предлагает некое минимальное ядро и даёт широкие возможности по его кастомизации с помощью так называемых «перехватчиков» — interceptors в оригинале. Не знаю насколько это круто — перспектива строить полные урлы и указывать метод руками при каждом запросе меня вовсе не прельщала, перехватчиков для модификации этого поведения не наблюдалось, да и документация восторга не вызывала. Я перешёл к последнему варианту — restful.js.


A pure JS client for interacting with server-side RESTful resources. Think Restangular without Angular.

Вообще-то я предпочитаю Ember, но какая разница? Главное-то что б использовать удобно было! 

const articleCollection = api.all('articles');  // http://api.example.com/articles

// http://api.example.com/articles/1
api.one('articles', 1).get().then((response) => {
    const articleEntity = response.body();

    // if the server response was { id: 1, title: 'test', body: 'hello' }
    const article = articleEntity.data();
    article.title; // returns `test`
    article.body; // returns `hello`
    // You can also edit it
    article.title = 'test2';
    // Finally you can easily update it or delete it
    articleEntity.save(); // will perform a PUT request
    articleEntity.delete(); // will perform a DELETE request
}, (response) => {
    // The reponse code is not >= 200 and < 400
    throw new Error('Invalid response');
});

Это пример из документации. Выглядит неплохо в сравнении с конкурентами, да и документация достаточно внятная… Вариантов-то всё равно больше не наблюдается. Берём? Берём.

Есть такая концепция «разумного умолчания», которая предполагает, если пересказывать своими словами, что решение некоей проблемы заточено, условно, под 90% юзкейсов, а в остальных 10% нужно явно сказать что имеются особенные обстоятельства.

Тривиальный пример этой концепции — параметры по умолчанию в большинстве языков программирования.

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

Общая стратегия этих оптимизаций одинакова — 90% пользователей для достижения своих целей должны производить так мало действий, как это вообще возможно. Не будет большим преувеличением сказать что это общая формула прогресса — изобретение всё более и более простых, с точки зрения количества необходимых телодвижений, интерфейсов для решения всё тех же задач.
И, в общем-то, эти самые разумные умолчания — один из главных способов упрощения.

Зачем я играю в Капитана Очевидность, растекаясь мысью по древу? Потому что очередной велосипед — это просто очередной велосипед, а вот велосипед с подведённой под него философской базой уже не просто очередной велосипед, а даже может издали и на мотоцикл смахивать!
Конец небольшого лирического отступления.

Итак, restful.js. Использовал я его крайне недолго — и пары дней не прошло, как я понял что:


  1. Каждый раз явно вызывать all () — не круто.

    let games = api.all('games');  //<-- не круто
games.get();
//...
games.post();

    Ресурсы API — это то, что лежит в основе всего фронтенда, так какого ж они каждый раз создаются вручную? Это как раз те вещи, которые должны быть вшиты в ткань проекта. api.games.get(); api.games.post() — выглядит куда лучше (да, это как раз всплыло влияние синтаксиса той библиотечки на jQuery). Впрочем, это ещё можно было обойти, мы же динамические бояре: api.games = api.all('games');


  2. Ручное разворачивание ответа и entity — вообще не круто! 

    let games = (await api.games.get()).body().data();  //<-- that sucks

    Глаза б мои не видели, пальцы б не писали;, но приходилось. Тут бы вот те перехватчики из rest пригодились бы, там функциональность разворачивания сырого ответа в объект как раз реализована. В restful.js тоже есть перехватчики, но тут они поскромнее, не то.


  3. Ох, а ещё — вышеприведённая строчка кода аж дважды неправильная. Во-первых, не get, а getAll, мы же коллекцию запрашиваем, а не отдельный инстанс. Во-вторых, data () у коллекции не определён — получится Uncaught (in promise) TypeError: _temp.body(...).data is not a function. Будь добр, используй forEach, определённый как метод у entity, которую возвращает body () у response, который возвращает getAll ().

В общем, классический пример неудобного интерфейса. Я не знаю, влияние ли это ангуляра, который вроде славится своей академичностью, или ориентация скорее на бытиё фреймворком, нежели библиотекой, но предлагаемый restful.js интерфейс мне сильно не понравился. На самом деле, по итогу он понравился мне, наверно, даже меньше чем интерфейс конкурентов — видимо, эффект зловещей долины сказывается: близко к идеалу, но не дотянуло, а от любви до ненависти всего один велосипед.

Выкинул restful.js и накидал два класса, которые за 150 строк кода делали в принципе то же, что и restful.js за 6000 (шесть тысяч, это не опечатка).
Потом подумал, выложил на github, порефакторил, освоил webpack (замечательная штука!), mocha+chai, sinon и travis, выложил на npm и bower, написал документацию, запилил пример и в итоге написал эту статью, чтобы облегчить жизнь тем, кто столкнётся с такой же проблемой.

На данный момент (июнь 2016) там маловато тестов, нет методов HEAD и OPTIONS, сложно получить сырой ответ и слишком мало бейджей в README (всего один, что за позор!…).
Впрочем, это всё легко исправить. Главное что another-rest-client предоставляет понятный и простой интерфейс, с которым мне нравится работать; надеюсь что и не только мне.

Использование github API: 

var api = new RestClient('https://api.github.com');
api.res({repos: 'releases'});

api.repos('Amareis/another-rest-client').releases('latest').get().then(function(release){
    console.log(release);
    document.write('Latest release of another-rest-client:
');
    document.write('Published at: ' + release.published_at + '
');
    document.write('Tag: ' + release.tag_name + '
');
});

Вложенные ресурсы? Запросто: 

var api = new RestClient('http://example.com/api/v1');
api.res({       //or it gets object and returns object where resource is available by name
    dogs: [
        'toys',
        'friends'],
    cats: 0,
    humans:
        'posts'
});
/* last string is equal to:
api.res('dogs').res(['toys', 'friends']);
api.res('cats');
api.res('humans').res('posts'); */

api.dogs(1337).toys.get();          //GET http://example.com/api/v1/dogs/1337/toys
api.dogs(1337).friends(2).delete(); //DELETE http://example.com/api/v1/dogs/1337/friends/2

//POST http://example.com/api/v1/humans/me/posts, body="{"site":"habrahabr.ru","nick":"Amareis"}"
api.humans('me').posts.post({site: 'habrahabr.ru', nick: 'Amareis'});

С async/await код получается куда веселей: 

var me = api.humans('me');
var i = await me.get();
console.log(i);    //just object, i.e. {id: 1, name: 'Amareis', profession: 'programmer'}
var post = await me.posts.post({site: 'habrahabr.ru', nick: i.name})
console.log(post);  //object


  1. Почему такое название? Ну, изначально он был просто rest-client. Но это название (а также ещё несколько похожих) занято в npm, да и уникальность так себе, так что я добавил чутка самоиронии и он стал another-rest-client.
  2. В самом начале своего существования restful.js была очень похожа на первые версии another-rest-client. Потом, видимо, скатилась в энтерпрайзщину.
  3. В коде another-rest-client всего два комментария (и я возмущён тем, что их слишком много) и оба они содержат проклятья в сторону Javascript, который не позволяет сделать код полностью красивым.
  4. Я так и не понял чем WTFPL отличается от MIT лицензии.

Спасибо за внимание.

© Habrahabr.ru