Привет, Хабр! Представляю вашему вниманию перевод статьи "REST API Best Practices" автора Krishna Srinivasan.

REST становится общим подходом для представления сервисов окружающему миру. Причина его популярности заключается в его простоте, легкости использования, доступе через HTTP и другие. Существует неправильное представление о том, что все данные, доступные через сеть, считаются REST, но это не так. В этой статье я собираюсь объяснить вам некоторые best practices, которые вы должны всегда помнить при реализации собственного REST приложения. Я бы хотел услышать ваш опыт в REST приложениях, поэтому если вы знаете best practies, которые не упомянуты в этой статье, пожалуйста, поделитесь с нами в комментариях.

Disclamer: все best practies основаны на моем личном опыте. Если вы имеете другое мнение, не стесняйтесь отправлять его мне на email, и мы обсудим его.

Здесь представлен список best practices, которые будут обсуждаться в этой статье:

1. Конечные точки в URL – имя существительное, не глагол
2. Множественное число
3. Документация
4. Версия вашего приложения
5. Пагинация
6. Использование SSL
7. HTTP методы
8. Эффективное использование кодов ответов HTTP

«Только со смертью догмы начинается наука.»
// Галилео Галилей

«Я начал завидовать рабам. Они всё знают заранее. У них твёрдые убеждения.»
// х/ф Марка Захарова «Убить дракона» по мотивам пьесы Евгения Шварца

Уже пару лет и дня не проходит, чтобы я не услышал (или не прочитал) от людей, начинающих новые проекты, фразу типа «Возьмем серверный движок для REST API и MVC, и погнали». Сначала я думал, что у этих слов есть один источник, может книжку какую завезли во все магазины или где-то в топе поисковиков лежит статья, зомбирующая разработчиков. Если же выяснять у них, что они понимают под REST и MVC, то можно повредиться умом. Ну с MVC уже все ясно, об этом я уже давно писал, ничего не изменилось, только усугубилось, стоит набрать в Google Images «mvc» и мы увидим страшное, стрелочки в любые стороны. Ну а про REST отвечают следующее: ну как же, нам нужно из браузерного GUI и мобильного приложения вызывать серверные методы, например: setUserCity(userId, cityId) или calculateMatrix(data) или startVideoConverter(options, source, destination) а потом мы столкнемся с большой нагрузкой и архитектура REST все решит. Дальше я задаю вопросы, от которых глаза округляются уже у тех, кто недавно еще горел праведной верой, рвался в бой и точно знал, что к чему в этом мире. Теперь можно перейти к рассмотрению терминологической катастрофы, в эпицентре которой мы с вами пребываем.

Как правильно построить архитектуру приложения, с учетом специфики REST? Было ли с вами такое, что словом «REST» называют любое HTTP API без разбору — и как донести истинное значение этого термина? Как показать, что преимущества REST проявляются в больших долгосрочных проектах, но для небольшой утилиты лучше взять что-то попроще? Эти и другие животрепещущие вопросы освещает Дилан Битти (Dylan Beattie) в докладе «Real world REST and Hands-On Hypermedia».

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

Вы сможете встретиться с Диланом вживую на конференции DotNext Moscow 2017, куда он приедет с новым докладом «Life, liberty and the pursuit of APIness: the secret to happy code». Напоминаем, что вы можете купить билеты по вкусной цене вплоть до 31 октября включительно.

Эту статью можно либо прочитать в текстовой расшифровке (жмите кнопку «читать дальше» ⇩), либо посмотреть полную видеозапись доклада. Все необходимые для понимания изображения, слайды и диаграммы присутствуют как на видео, так и в текстовой расшифровке, так что вы ничего не потеряете.



Комментарии к статье приветствуются и действительно важны — мы постараемся задать ваши лучшие вопросы напрямую Дилану на DotNext Moscow 2017.

---

Перевод статьи Sashko Stubailo GraphQL vs. REST

---

Два способа отправки данных по протоколу HTTP: в чем разница?

GraphQL часто представляют как революционно новый путь осмысления API. Вместо работы с жестко определенными на сервере конечными точками (endpoints) вы можете с помощью одного запроса получить именно те данные, которые вам нужны. И да — GraphQL гибок при внедрении в организации, он делает совместную работу команд frontend- и backend-разработки гладкой, как никогда раньше. Однако на практике обе эти технологии подразумевают отправку HTTP-запроса и получение какого-то результата, и внутри GraphQL встроено множество элементов из модели REST.

Так в чем же на самом деле разница на техническом уровне? В чем сходства и различия между этими двумя парадигмами API? К концу статьи я покажу вам, что GraphQL и REST отличаются не так уж сильно, но у GraphQL есть небольшие отличия, которые существенно меняют процесс построения и использования API разработчиками.

Так что давайте сразу к делу. Мы определим некоторые свойства API, а затем обсудим, как они реализованы в GraphQL и REST.

А ваше приложение — RESTful? Чтобы ответить на этот вопрос нужно сначала разобраться что такое RESTful. Бытует мнение, что отдавать правильные коды ответов в HTTP — это уже RESTful. Или делать правильные идемпотентные HTTP-запросы — это вообще очень RESTful. Мы в Хекслете сделали практический курс по протоколу HTTP (отличия версий, отправка форм, аутентификация, куки и пр.), и в нем мы стараемся рассказать о правильном использовании запросов, но нужно понимать, что RESTful это не про HTTP, это вообще не про протоколы интернета. Современный веб и взаимодействие между браузером и сервером с помощью HTTP и URI могут удовлетворять принципам RESTful, а могут и не удовлетворять.

В сегодняшнем переводе — простое и понятное описание RESTful, и какой должна быть система, чтобы ее можно было так называть.

От переводчика:
Я впервые попробовал перевести статью такого объёма и IT-тематики, с радостью прочту ваши комментарии и замечания. Что же касается самой статьи: я не согласен с автором как минимум потому, что, по сути, он заменяет REST на… REST (!!!), но немного в другом обрамлении. Однако, не смотря на то, что в статье преподносится много очевидных вещей, мне она показалась достойной обсуждения на Хабре.

Почему Вам стоит похоронить эту популярную технологию

Некоторое время назад я гуглил интернет по поводу “REST vs SOAP”, прочитал пару статей и вроде бы все понял, но не почувствовал от этого никакого удовлетворения. Что-то было не так, то ли я не почувствовал основную идею, то ли просто читал, одновременно слушая новый музон и думая о новой фиче в проекте. Как появилось время, решил восполнить этот пробел, заодно написав полезную статью по этому поводу.

Несколько лет назад я разрабатывал для одного большого телекома новую информационную систему. Нам приходилось взаимодействовать со всё нарастающим количеством веб-сервисов, открываемых более старыми системами или бизнес-партнёрами. Как вы понимаете, мы получили добрую порцию SOAP-ада. Заумные WSDL, несовместимые библиотеки, странные баги… Где только возможно мы старались продвинуть — и использовать — простые RPC-протоколы: XMLRPC или JSONRPC.

Данный текст — продолжение серии статей, в которых я рассматриваю структуру (предположительно) готовящейся к выходу в этом году распределенной сети Telegram Open Network (TON). В предыдущей части я описал её самый базовый уровень — способ взаимодействия узлов между собой.

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

Сегодня посмотрим на основной компонент TON — блокчейн.

Уже две недели Рунет шумит про Telegram и ситуацию с его бессмысленной и беспощадной блокировкой Роскомнадзором. Рикошетом задело многих, но всё это — темы для постов на Geektimes. Меня же удивило другое — я до сих пор не видел на Хабре ни одного разбора запланированной к выходу на базе Telegram сети TON — Telegram Open Network. Мне захотелось восполнить этот недостаток, ибо поизучать там есть что — даже несмотря на отсутствие официальных заявлений о нём.

Напомню — ходят слухи о том, что Telegram запустил очень масштабное закрытое ICO, уже собрав в нём невероятные суммы. Предполагается, что уже в этом году будет запущена собственная криптовалюта Gram — и у каждого пользователя Телеграма автоматически появится кошелёк, что само по себе создает немалое преимущество перед остальными криптовалютами.

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

Что же говорится в этом документе? Я попробую пересказать его своими словами, близко к тексту, но по-русски и чуть более человечно (да простит меня Николай со своей склонностью уходить в формальную математику). Имейте в виду, что даже в случае его подлинности, это черновое описание системы и оно, весьма вероятно, изменится к моменту публичного запуска.

Друзья! Мы продолжаем серию публикаций «без купюр» о проектных процессах, IT-технологиях и о том, как работать эффективно. Сегодня поговорим об очень наболевшей теме, вызывающей изжогу в головном мозге — выборе технологий, языков программирования, роли архитекторов, аналитиков, тимлидов и экстрасенсов для решения эпической задачи: запустить программное решение, если возможно, в разумный срок. И отдельно остановимся, ну чтобы совсем не заскучать, на анализе корреляции размеров частей тела одной части коллектива с производительностью работы мозга другой. Наливайте кофе и поехали!

Первая часть короткого и жесткого введения в Haskell. Вторую часть можно найти здесь

tl;dr: Очень краткое и сжатое введение в Haskell.

• Введение
  
  • Установка
  • Без паники
  • Самые основы Haskell
    
    • Объявление функций
    • Пример использование типов
    
    
  
  
• Необходимый минимум из Haskell
  
  • Выражения
    
    • Арифметические
    • Логические
    • Возведение в степень
    • Списки
    • Строки
    • Кортежи
    • Разбираемся со скобками
    
    
  • Полезные вещи для записи функций
  
  
• Сложная часть
  
  • Функциональный стиль
    
    • Функции высшего порядка
    
    
  • Типы
    
    • Вывод типов
    • Создание новых типов
    • Рекурсивные типы
    • Деревья
    
    
  • Бесконечные структуры
  
  

UPD. Если туториал вам понравился, черкните пару строк автору оригинальной статьи. Человеку будет приятно ;)

Идею, короткий план и ссылки на основные источники для этой статьи мне подал хабраюзер z6Dabrata, за что ему огромнейшее спасибо.

UPD: в текст внесены некоторые изменения с целью сделать его более понятным. Смысловая составляющая осталась прежней.

Вступление

Возможно, у этой системы найдутся приложения не только
в роли логического исчисления. (Алонзо Чёрч, 1932)

Вообще говоря, лямбда-исчисление не относится к предметам, которые «должен знать каждый уважающий себя программист». Это такая теоретическая штука, изучение которой необходимо, когда вы собираетесь заняться исследованием систем типов или хотите создать свой функциональный язык программирования. Тем не менее, если у вас есть желание разобраться в том, что лежит в основе Haskell, ML и им подобных, «сдвинуть точку сборки» на написание кода или просто расширить свой кругозор, то прошу под кат.

14й выпуск computer science student и второй, посвященный языку Scheme. В сегодняшнем коротком скринкасте я расскажу о том, что такое лямбда в функциональном языке программирования.

Видео доступно на vimeo, youtube и rpod.

В очередном опусе Итана Сигеля резанула фраза

Пронаблюдав за удалёнными сверхновыми и измерив, как Вселенная расширялась миллиарды лет, астрономы обнаружили нечто удивительное, загадочное и неожиданное.

И нет, с переводом всё в порядке, в оригинале ещё желтее:

By observing distant supernovae and measuring how the Universe had expanded over billions of years, astronomers discovered something remarkable, puzzling and entirely unexpected

wat?

О какой неожиданности может идти речь? Там ведь совершенно шикарная история длиной в 80 лет с яркими открытиями и закрытиями. История про то, как на самом деле делается настоящая наука. История скорее про физиков, чем про физику.

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

В этой статье я расскажу о том как мы столкнулись со сложностью написания хороших тестов при разработке компонента на Go и как решали эту задачу используя библиотеку RSpec в Ruby on Rails.

Перевод статьи "Дяди Боба". Оригинал

В последнее время меня критикуют за то, что я связываю TDD с профессионализмом. Я признаю себя виновным и утверждаю, что связь существует.

От переводчика. Давид Хейнемейер Ханссон данной статьей поднял острую тему обязательности использования TDD и, даже, возможного вреда от написания тестов перед написанием кода. Именно эта статья послужила лейтмотивом уже пяти встреч на тему жив ли TDD, на которых Давид, Кент Бек и Мартин Фаулер обсуждают достоинства и недостатки TDD, рамки применимости и ограничения. Для тех у кого восприятие устного английского оставляет желать лучшего, SergeyT публикует краткие саммари в своем G+.

Итак, моя последняя запись: стартап-ловушка (здесь её перевод — прим. переводчика) наделала много шуму. Среди людей, выражающих согласие и поддержку, нашлась и группа людей, которая была категорически не согласна. Я не буду здесь резюмировать все разногласия, ибо в этом месяце я уже исчерпал свой лимит ругательных слов. Но одним альтернативным мнением я проникся и считаю нужным его обсудить.
Речь о старом конфликте «прагматизм против догматизма».

Примечание от переводчика: мой опыт знакомства с разработкой через тестирование во многом схож с тем, что описывает автор (хотя и начался на несколько лет позже). Я начинал изучать TDD самостоятельно, на работе, исправляя баги и создавая новые модули с нуля. Эффект от применения TDD произвёл на меня настолько мощное впечатление, что породил желание делиться умением применять эту технику с другими. Я также проводил Code Retreat-ы внутри и вне своей компании. И я вижу те же проблемы в своих тренингах — очень сложно взять и «впихнуть» понимание сути TDD в чужие головы.

Поэтому в данной статье я вижу свежий взгляд на проблему, который, возможно, даст новый толчок в изучении TDD мне и моим коллегам. Думаю, она пригодится и прочим интересующимся разработкой через тестирование. Буду рад увидеть Ваши комментарии.

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

TL;DR?

Многие сторонники TDD рекомендуют подход под названием «интенсивная практика», но я догадываюсь, что у Вас не будет возможности тратить много рабочего времени на практику. Я советую людям «применять TDD осознанно», но до сих пор не знал хорошего способа достаточно доступно объяснить смысл этих слов, что снижало ценность моего совета. Вы можете начать применять оба подхода (интенсивный и осознанный) одновременно, если начнёте исправлять баги через тесты. Даже если Вы до сих пор не умеете проектировать софт на экспертном уровне, то, по крайней мере, Вы уже можете учиться как эксперт. И исправление багов через тесты даст Вам естественную и не слишком рискованную возможность делать это. У Вас будет возможность практиковаться в TDD усердно и осознанно. Если у Вас есть возможность исправлять баги на работе в одиночку, то Вы можете использовать эти практики, не привлекая лишнего внимания, которое обычно возникает при разговорах об «интенсивной практике». Просто говорите всем, что Вы исправляете баги. Это всем понравится.

Вам всего лишь надо начать с написания теста, который будет падать до тех пор, пока Вы не исправите баг. Если Вам нужно больше подробностей, прежде чем начать, продолжайте чтение.