javascript get rbx api co api php id 1017883

Первое рабочее место или как начать разработку API на Node.js

Введение

В данной статье хотел бы поделиться своими эмоциями и приобретенными навыками в разработке первого REST API на Node.js с использованием TypeScript, как говорится, с нуля. История достаточно банальная: «Закончил университет, получил диплом. Куда же пойти работать?» Как можно было догадаться меня проблема не обошла стороной, пусть думать особо и не пришлось. Позвал к себе на стажировку разработчик (выпускник той же специальности). Полагаю, что это достаточно распространенная практика и существует множество подобных историй. Я, недолго думая, решил попробовать свои силы и пошел…

День первый. Знакомство с Node.js

Пришёл я на back-end разработку. В данной IT-компании используют платформу Node.js, с которой я абсолютно не был знаком. Я немного убежал вперед, забыв рассказать читателю, что никогда и ничего не разрабатывал на JavaScript (за исключением пары скриптов с копированным кодом). Алгоритм работы и архитектуру веб-приложений в целом я понимал, так как разрабатывал CRUD на Java, Python и Clojure, но этого было недостаточно. Поэтому первый день я полностью посвятил изучению Node.js, очень помог этот скринкаст.

Параллельно изучая веб-фреймворк Express, менеджер пакетов npm, а также такие файлы как package.json и tsconfig.json, голова просто шла кругом от количества информации. Очередной урок, что усвоение всего материала одновременно задача близкая к невозможной. К концу дня я все же справился с настройкой окружения и смог запустить express веб-сервер! Но радоваться было рано, потому что уходил домой с полным ощущением непонимания. Чувство, что я утопал в огромном мире JS не покидало меня ни на минуту, поэтому необходима была перезагрузка.

День второй. Знакомство с TypeScript

Та самая перезагрузка последовала именно в этот день. К этому моменту я полностью узнал свою задачу, к ней мы перейдем чуть ниже. Зная, что предстоит писать не на чистом JavaScipt, обучение от Node.js плавно перетекло к языку TypeScript, а именно, его особенностям и синтаксису. Здесь я увидел долгожданные типы, без которых не представлял программирование буквально 2 дня тому назад не в функциональных языках программирования. Это и было моим самым большим заблуждением, которое мешало мне понять и усвоить код, написанный на JavaScript в первый день.

Ранее писал по большей части на объектно-ориентированных языках программирования, таких как Java, C++, C#. Осознав возможности TypeScript, я почувствовал себя в своей тарелке. Этот язык программирования буквально вдохнул в меня жизнь этой сложной среды, как мне казалось на тот период. Под занавес дня я полностью настроил окружение, запустил сервер (уже на TypeScript), подключил необходимые библиотеки, о которых ниже расскажу. Итог: готов к разработке API. Переходим непосредственно к разработке…

Разработка API

Объяснение принципа работы и прочие разъяснение о том, что же такое REST API мы оставим, так как на форуме очень много статей об этом с примерами и разработкой на различных языках программирования.

Задача стояла следующая:

Сделать сервис с REST API. Авторизация по bearer токену (/info, /latency, /logout). Настроенный CORS для доступа с любого домена. DB — MongoDB. Токен создавать при каждом заходе.

Средства реализации

Итак, я упоминал, что уже изучил во второй день несколько библиотек (фреймворков), с этого и начнем. Для роутинга я выбрал routing-controllers, руководствовался большим сходством с декораторами из Spring Framework (Java). В качестве ORM я выбрал typeorm, хоть и работа с MongoDB в экспериментальном режиме, но для такой задачи вполне достаточно. Для генерации токенов использовал uuid, переменные загружаются с помощью dotenv.

Начальный запуск веб-сервера

Обычно, используется express в чистом виде, но я упоминал выше фреймворк Routing Controllers, который позволяет нам создать express сервер следующим образом:

Подключение к БД

Ранее, мы уже запустили веб-сервер, поэтому продолжим подключением к базе данных MongoDB, предварительно развернув на локальном сервере. Установка и настройка подробно описаны в официальной документации. Мы же непосредственно рассмотрим подключение с помощью typeorm:

Все достаточно просто, необходимо указать несколько параметров:

Теперь соединяем запуск сервера и подключение к БД. Отмечу, что импорт ресурсов отличается от классического, используемого в Node.js. В итоге получаем следующий запускаемый файл, в моем случае main.ts:

Сущности

Напомню, что задача состоит в аутентификации и авторизации пользователей, соответственно нам необходима сущность: Пользователь (User). Но это еще не все, так как каждый пользователь имеет токен и не один! Поэтому необходимо создать сущность Токен (Token).

В таблице User мы создаем поле — массив тех самых токенов для пользователя. Также мы подключаем calss-validator, так как необходимо, чтобы пользователь осуществлял вход через email.

База выглядит следующим образом:

Авторизация пользователя

Для авторизации мы используем authorizationChecker(один из параметров при создании сервера см. выше), для удобства вынесем в отдельный файл:

После аутентификации у каждого пользователя появляется свой токен, поэтому мы можем из заголовков (headers) ответа вытащить необходимый токен, выглядит он примерно так: Bearer 046a5f60-c55e-11e9-af71-c75526de439e. Теперь мы можем проверить, существует ли данный токен, после чего функция возвращает информацию об авторизации: true — пользователь авторизован, false — пользователь не авторизован. В приложении мы можем использовать очень удобный декоратор в контроллере: @Authorized(). В этот момент и будет вызвана функция authorizationChecker, которая вернет ответ.

Логика

Для начала я хотел бы описать бизнес логику, так как контроллер — это одна строчка вызова методов ниже представленного класса. Также, в контроллере мы будем принимать все данные, в нашем случае это будет JSON и Query. Рассмотрим по отдельным задачам методы, а в конце сформируем итоговый файл, который назван UserService.ts. Отмечу, что на тот момент знаний для устранения зависимостей попросту не хватало. Если вы не встречались с термином инъекция зависимостей, очень советую прочитать об этом. На данный момент пользуюсь DI-фреймворком, т. е. использую контейнеры, а именно инъекцию через конструкторы. Вот, я считаю, хорошая статья для ознакомления. Возвращаемся к задаче.

Контроллер

Многим не нужно объяснять для чего нужен и как используется контроллер в паттерне MVC, но два слова я все же скажу. В кратце, контроллер является связующим звеном между пользователем и приложением, который переправляет данные между ними. Выше полностью была описана логика, методы которой вызываются в соответствии с роутами, состоящий из URI и ip сервера (пример: localhost:3000/signin). О декораторах в контроллере я уже упоминал ранее: Get, POST, @Authorized и самый важный из них это @JsonController. Еще одна очень важная фишка данного фреймворка состоит в том, что если мы хотим отправлять и получать JSON, то используем именно данный декоратор вместо Controller.

Заключение

В данной статье я хотел отразить больше не техническую составляющую правильного кода или чего-то такого, а просто поделиться тем, что человек может с абсолютного нуля за пять дней собрать веб-приложение, использующее базу данных и содержащее хоть какую-то, но логику. Только вдумайтесь ни один инструмент не был знаком, вспомните себя или просто поставьте на мое место. Ни в коем случае это не случай, который говорит: «я самый лучший, вы так никогда не сможете». Наоборот, это крик души человека, который в данный момент находится в полном восторге от мира Node.js и делится с Вами этим. А также тем, что ничего нет невозможного, нужно просто брать и делать!

Конечно, нельзя отрицать, что автор ничего не знал и первый раз сел писать код. Нет, знания ООП, принципы работы REST API, ORM, база данных присутствовали в достаточном объеме. И это может говорить только о том, что средство достижения результата абсолютно не играет никакой роли и высказывания в стиле: «Не пойду на эту работу, там язык программирования, который я не учил», для меня теперь просто проявление человеком не слабости, а скорее защиты от незнакомой внешней среды. Да что там скрывать, страх присутствовал и у меня.

Подведем итоги. Хочу посоветовать студентам и людям, которые еще не начали свою карьеру в IT, не бояться средств разработки и неизвестных технологий. Вам обязательно помогут старшие товарищи (если повезет также как и мне), подробно разъяснят и ответят на вопросы, потому что каждый из них оказывался в таком положении. Но не забывайте, что Ваше желание — это самый важный аспект!

Источник

Запросы к Rest API из JavaScript компактно и красиво

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

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

Кандидаты

Итак, мне был нужен джаваскриптовский клиент для 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, но какая разница? Главное-то что б использовать удобно было!

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

Небольшое лирическое отступление

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

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

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

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

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

restful.js

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

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

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

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

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

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

Что же я сделал?

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

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

Источник

Как сделать красивую документацию для Web API, за которую будет не стыдно

Я хотел бы рассказать вам об утилите, с которой вы сможете забыть о боли создания документации для Web API. О том как это сделать прошу всех под кат.

Итак, добро пожаловать под кат, ! Ты возможно спросишь с помощью чего так красиво получается? Ответ: apiDoc. Что еще за apiDoc? apiDoc — это утилита для генерации документации основываясь на комментариях в коде. Но с одной оговоркой, эти комментарии должны быть определенного вида. Можно создавать документацию для проектов на: C#, Dart, Erlang, Go, Java, Javascript, PHP, Python, Ruby, Perl и прочих. Но в этой статье я расскажу как сделать такую красивую документацию на основе проекта на Python.

Для этого вам понадобится:

Установка Node.js

Установка apiDoc

Надеюсь все справились с установкой Node.JS и мы можем перейти далее. Для установки apiDoc откройте терминал (командную строку в Windows) и запустите команду:

И на выходе вы должны получить что-то вроде этого.

Подготовка к созданию документации

Ну вот мы и добрались до создания документации. Для того чтобы сгенерировать документацию необходимо сделать комментарии в коде. Вот пример комментария в коде.

Что есть что? Приведу описание некоторых основных «тегов» для генерирования документации. Все теги можно посмотреть здесь.

Обязательный тег для генерации документации.

method — типа запроса (GET,POST,PUT и т.д.)
path — путь до метода например /2/get_news
title — название метода которое будет отображаться в документации

Пример использования:

@apiName

Тег определяющий название блока документации. Рекомендуется всегда использовать.

name — название метода

Пример использования:

@apiGroup

Тег связывающий блоки документации в одну группу на сайте документации.

name — название группы

Пример использования:

@apiVersion

version — версия метода согласно семантическому версионированию подробнее по ссылке здесь.

Пример использования:

@apiSuccess

Тег используется для описания параметра передаваемого в метод

type — тип объекта(, , ,