REST API приложение на Go пошаговый туториал


Оглавление (нажмите, чтобы открыть):

4gophers

Авторизация в Go с использованием JWT

Go замечательный выбор для создания быстрых и масштабируемых API. Стандартный пакет net/http предоставляет весь необходимый функционал, а при использовании различны дополнительных пакетов, например Gorilla Toolkit, вы сможете сократить время написания вашего сервиса до минимума. В этой статье мы разберем как защитить свое Go приложение с использованием JSON веб токенов(JWT). А если нет желания перечитывать все эти тонны букв, то можете сразу читать код в репозитории на GitHub.

Язык программирования Go разработан компанией Google для разработки современного программного обеспечения. Этот язык разрабатывался для более быстрого и быстрого и эффективного решения большинства задач. Основные характеристики этого языка:

  • Строгая типизация и сборщик мусора.
  • Невероятно быстрая компиляция
  • Встроенная поддержка конкурентного программирования
  • Обширная стандартная библиотека

Синтаксис Go способствуем минимальному количеству нажатий на клавиши. Переменные можно легко объявлять и сразу инициализировать с помощью инструкции := , точка с запятой не нужна и не существует сложной системы типов. Go очень «упрямый» язык. Конечный результат получается чистым, очень легко читается и легко понимается другими разработчиками.

Golang песочница

В этом туториале мы будем разрабатывать RESTful API на Go и вам, конечно же, понадобится знание основ самого языка. Изучение основ языка выходит за рамки этой статьи. Если вы новичок в Go, то можете пройти «Tour of Go» в котором очень хорошо описаны базовые концепции Go такие как конкурентность. А уже после этого возвращайтесь к чтению этой статьи. Если у вас уже есть некоторый опыт использования Go, то давайте приступим к написанию API!

Строим API на Go

Go замечательно подходит для написания различных RESTful API. Стандартный пакет net/http предоставляет все ключевые функции для работы с http протоколом. Приложение, которое мы сейчас разрабатываем, называется «We R VR». Приложение обеспечивает обратную связь с разработчиком в тех играх, над которыми он работает.

В Go идиоматически правильно использовать небольшие пакеты вместо больших фреймворков и стараться применять стандартную библиотеку везде где это возможно. Мы тоже будем использовать такой подход и наш код можно будет без боязни использовать в экосистеме Go. Для разработки мы будем использовать несколько пакетов, таких как gorilla/mux для роутинга и dgrijalva/jwt-go для работы с JSON веб токенами.

Golang фреймворки

Перед тем окунуться в код, хочу заметить, что идиоматическая правильность(стараться не использовать фреймворки) не означает, что на Go нет ни одного фреймворка. Beego, Gin Gionic, Echo и Revel предоставляют вполне традиционный функционал для разработки веб-приложений. Но, так как стандартный пакет net/http предоставляет обширные возможности, то все указанные выше фреймворки построены как надстройка над этим пакетом. И работа с любым из этих фреймворков не будет сильно отдалять вас от самого Go, как это бывает в других языках.

Начинаем

Начать стоит с файла main.go . Пока у нас будет только один файл, это позволит запускать наше приложение без явной сборки при внесении любого изменения в код. Мы сможем запускать наше приложение простой командой go run в терминале. Теперь мы готовы,чтобы начать кодить:

Необходимо создать две папки, которые мы указали в файле main.go и назвали их views и static . В папке views сразу можно создать файл с HTML для нашей главной страницы и назвать его index.html . Пока что это очень простая страница:

Давайте убедимся, что наш сервер работает. Для этого выполним команду go run main.go из терминала. Если вы раньше не использовали пакет gorilla/mux , то вам придется установить его у себя с помощью команды go get , которая скачает и установит все необходимые зависимости. Как только приложение запуститься, откройте в браузере адрес localhost:3000 . Если все сделано правильно , то вы должны увидеть текст Welcome to We R VR. Дальше можно переходить к определению API.

Определяем API

Самое время для определения наших роутов. Для нашего демо приложения мы будем использовать только GET и POST запросы. В дополнение к роутам, мы реализуем хендлер NotImplemented . Это будет хендлер по умолчанию для всех роутов, которые мы пока не добавили функциональность. Продолжим добавлять код в main.go :

Неплохое начало реализации API. Давайте запустим сервер снова и попробуем обратиться по каждому роуту. Каждый роут должен вернуть код 200 OK и сообщение Not Implemented . Если все хорошо, то дальше можем начинать добавлять функциональность.

Добавляем функциональность

У нас есть пачка роутов, но в данный момент они ничего не делают. Будем добавлять необходимую функциональность.

Теперь у нас есть хендлеры. Можем добавить их к определению наших роутов.

Хендлеры и прослойки

В Go прослойки работают аналогично хендлерам. Если вы раньше не сталкивались с прослойками, то представляйте их как абстрактный код, который выполняется до срабатывания основной бизнес логики. К примеру, у вас может быть прослойка, которая выполняет логирование каждого запроса. Скорее всего, у вас нет желания добавлять одинаковый код во все ваши хендлеры. Вместо этого вы можете написать прослойку, которая добавляется перед основной функцией при определении роута.

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

Всего две строчки кода, а мы уже добавили функциональность логирования ко всему нашему приложению. Теперь, при каждом обращении к приложению, в терминале будет отображаться определенная информация, тип запроса, код ответа и время ответа на запрос. Если заинтересовались и хотите побольше узнать о этой прослойке/хендлере и о других возможностях пакета gorilla/handlers , то можете почитать документацию.

Библиотеки прослоек

Мы привязываемся к пакету net/http насколько это возможно в рамках нашей реализации. Но нельзя не упомянуть о большом числе различных пакетов, которые предоставляют альтернативные способы реализации прослоек и хендлеров, (например для Auth0). Negroni и Alice — это две прекрасные альтернативы для реализации прослоек в Go.

Защищаем наше API с помощью JSON веб токенов

Давайте уже защитим наше приложение с помощью JWT. Мы сделаем это в два подхода. Для начала, реализуем простой пример, как в Go приложении работать с JSON веб токенами. В дальнейшем мы полностью реализуем все приложение, которое использует Auth0 аутентификацию.

Для базового примера у нас есть роутер, который генерирует новый JWT. И добавим прослойку, которая выполняет проверку токена.

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

Также, необходимо чтобы все наши роуты использовали эту прослойку.

Теперь можно собирать наше приложение, запустить его и попытаться перейти по URL localhost:3000/products . Вы увидите сообщение Required Authorization token not found. Это значит, что наша прослойка работает. Если перейти по URL localhost:3000/get-token , то вы получите токен. Скопируйте этот токен. Теперь вы можете отправить запрос на localhost:3000/products с указанием этого JWT в заголовке вида Bearer (для отправки запроса можно использовать, например, Postman). Все хорошо, вы можете увидеть список продуктов. Прослойка jwtMiddleware проверяет токен перед хендлером ProductsHandler и вам отдаеются продукты.

REST API приложение на Go: пошаговый туториал

4’265 подписчиков
1’728 просмотров на пост

Полезные материалы по всему, что может быть полезно разработчику на Go.

Детальная рекламная статистика будет доступна после прохождения простой процедуры регистрации

  • Детальная аналитика 70’046 каналов
  • Доступ к 28’004’146 рекламных постов
  • Поиск по 112’332’059 постам
  • Отдача с каждой купленной рекламы
  • Графики динамики изменения показателей канала
  • Где и как размещался канал
  • Детальная статистика по подпискам и отпискам

Найдено 638 постов

Интересные факты по поводу строк в Golang.

Прокси для работы с базой данных ClickHouse.

Создаем RESTful приложение на Golang и MongoDB.

В этом небольшом справочнике вы узнаете, какие бывают баги при многопоточном программировании на Go.

��Golang Senior Fullstack Developer

��от 150 000 до 200 000 рублей ��Удаленно

��Обязательные требования:
— Опыт построения API с помощью Go-Restful, Gin, Go-Micro или любой другой популярной библиотекой;
— Понимание, что такое vendoring, опыт использования glide, godep, go modules;
— Опыт работы с pub/sub (например, go-nsq);
— Опыт работы с gGRPC, Protobuf;
— Опыт работы с каким-либо ORM (gorm, sqlboiler).

�� Общие требования:
— Работа с docker и docker-compose на уровне пользователя;
— Желателен опыт работы с каким-либо CI/CD (CircleCI, TravisCI, Drone);
— Понимание очередей сообщений, опыт работы с RabbitMQ, Kafka или NSQ;
— Опыт работы в Scrum/Kanban команде;
— Знание принципов построения микросервисной архитектуры (choreography vs orchestration);
— Опыт работы с ELK стеком, Graylog или чем-то подобным для логов;
— Опыт работы с Kubernetes. Базовые знания, желательно с опытом написания helm charts.

Еще одно современное, с хорошей документацией хранилище типа ключ-значение.

Вроде бы мелочь, но кто не хотел раскрасить вывод терминала? С этой библиотекой это более, чем возможно.

В этой статье автор покажет, как соединить React с Go и написать простое приложение.

Работает с PDF документами с помощью Go.

Популярные ссылки для начинающих по изучению Go.

Об управлении версиями пакетов в Golang.

Анатомия функций в Golang.


Качественное введение в шаблоны проектирования на Go.

30 лучших книг для освоения языка программирования Go

Ищете книги по Go? Представляем 30 книг для освоения языка программирования Go, которые ответят на вопросы новичков и уверенных разработчиков.

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

Работа с PostgreSQL: от полного нуля до полного просветления

Работа с PostgreSQL не отличается от работы с любой другой СУБД, но знать синтаксис все-таки полезно. Предлагаем вашему вниманию вводный курс по основам.

Библиотека для реализации консольных приложений на Go.

Основы работы Go с популярным нынче языком запросов GraphQL.

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

Огромная статья с советами, как поддерживать проекты на Go в реальном мире.

Введение в REST API

В данной статье я расскажу Вам о том, что такое REST API. Также мы затронем тему HTTP протокола.А также рассмотрим пример архитектурного дизайна REST API.

О том, что такое API, я подробно рассказывал здесь. Напомню, что API – это некий набор правил, с помощью которых приложение или какой-либо один его компонент могут взаимодействовать, общаться, если хотите, с другим приложением или компонентом. Прикладной интерфейс программирования (API) может возвращать данные в разных форматах, например в JSON, XML или в бинарном формате, но в REST API мы будем использовать JSON-формат, как наиболее удобный.

Давайте посмотрим на пример. Возможно, Вы уже знакомы с тем, что такое система контроля версий Git. Ее web-версия – это Github. Так вот, у Github есть собственное API, с помощью которого можно получить какую-либо полезную информацию, например о пользователях и организациях, их проектах, и т.д. Давайте взглянем на пример:

В этом примере мы используем консольную утилиту curl для того, чтобы получить данные через API. Ее можно загрузить с официального сайт проекта. Она позволяет делать все то же самое что и расширение curl в PHP, только для этого не нужно писать код, так как вся функциональность доступна посредством интерфейса командной строки. Вообще, незаменимая вещь для тестирования различных прикладных интерфейсов. Есть еще альтернатива в виде расширения для Chrome – Postman.

Данная команда вернет нам большой JSON-объект, содержащий различные данные о компании.

Теперь остановимся подробнее на том, что же такое REST. Это сокращение может быть расшифровано в следующем виде: представление данных для клиента в формате удобном для него. Очень важно запомнить, что REST – это не протокол, а подход, архитектурный стиль к написанию прикладных интерфейсов.

Если говорить еще проще то, REST – это архитектурный стиль, а RESTful API – это его практическое воплощение, и чем больше приложение отвечает критериям стиля REST, тем более оно RESTful.

RESTful API сводится к четырем базовым операциям:

  • получение данных в удобном для клиента формате
  • создание новых данных
  • обновление данных
  • удаление данных

REST функционирует поверх протокола HTTP, поэтому стоит упомянуть о его основных особенностях. Для каждой операции указанной выше используется свой собственный HTTP метод:

  • GET – получение
  • POST – создание
  • PUT – обновление, модификация
  • DELETE – удаление

Все эти методы в совокупности называют CRUD (create, read, update, delete) – (создать, прочитать, обновить, удалить) операциями.

Фактически в REST существует единственный, непротиворечивый общий интерфейс для запросов, например, к базам данных, что является его важнейшим преимуществом. На следующей картинке показано соответствие HTTP методов SQL операциям и концепции CRUD.

Т.е. HTTP метод POST соответствует SQL операции INSERT, метод GET – операции SELECT и т.д.

Для каждого HTTP запроса есть свой статус. И они нужны, чтобы грамотно с точки зрения REST API оформить ответ и отдать клиенту. Статусов много, поэтому их всех не перечислить, однако важно знать их группировку:

  • 100 – 199 – это статусы несущие информационный характер
  • 200 — 299 – статусы успешной операции
  • 300 – 399 – статусы перенаправления (редиректа)
  • 400 – 499 – статусы ошибок на стороне клиента
  • 500 – 599 – статусы ошибок на стороне сервера

Вообще, как делается API. Создается некая точка входа для запросов, api.php, например. Этому API, могут передаваться, например, такие запросы:

    http://site.com/api.php?action=create.user& >где параметр

  • action – это действие, которое необходимо выполнить
  • id – идентификатор пользователя
  • кey – ключ доступа (фактически, временный пароль)

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

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

Таким образом, REST API призван создать четко структурированный подход в написании прикладных интерфейсов. Так, как с каждым днем становится все больше и больше данных, к которым необходимо открыть доступ.

Копирование материалов разрешается только с указанием автора (Михаил Русаков) и индексируемой прямой ссылкой на сайт (http://myrusakov.ru)!

Добавляйтесь ко мне в друзья ВКонтакте: http://vk.com/myrusakov.
Если Вы хотите дать оценку мне и моей работе, то напишите её в моей группе: http://vk.com/rusakovmy.

Если Вы не хотите пропустить новые материалы на сайте,
то Вы можете подписаться на обновления: Подписаться на обновления

Мастер Йода рекомендует:  Изучаем WP_Query Завершение

Если у Вас остались какие-либо вопросы, либо у Вас есть желание высказаться по поводу этой статьи, то Вы можете оставить свой комментарий внизу страницы.

Порекомендуйте эту статью друзьям:

Если Вам понравился сайт, то разместите ссылку на него (у себя на сайте, на форуме, в контакте):

Она выглядит вот так:

  • BB-код ссылки для форумов (например, можете поставить её в подписи):
  • Комментарии ( 0 ):

    Для добавления комментариев надо войти в систему.
    Если Вы ещё не зарегистрированы на сайте, то сначала зарегистрируйтесь.

    Copyright © 2010-2020 Русаков Михаил Юрьевич. Все права защищены.

    Телеграм канал Библиотека Go разработчика

    Статистика telegram канала @goproglib

    �� 2108 место в рейтинге каналов -59

    �� Количество подписчиков на сегодня 4267
    Прирост за 24 часа +5 подписчиков или рост на 0.12 %

    �� Приблизительная цена канала Библиотека Go разработчика

    �� Пессимистическая $ 1280.1
    �� Оптимистическая $ 21335

    Читайте популярные записи в канале Библиотека Go разработчика онлайн

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

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

    Кэширование в Golang.

    Создаем REST API приложение на Go и MongoDB.

    Создаем микросервисное приложения на Go, используя библиотеку Gin.

    . Golang Senior Fullstack Developer


    . от 150 000 до 200 000 рублей . Удаленно

    . Обязательные требования:
    — Опыт построения API с помощью Go-Restful, Gin, Go-Micro или любой другой популярной библиотекой;
    — Понимание, что такое vendoring, опыт использования glide, godep, go modules;
    — Опыт работы с pub/sub (например, go-nsq);
    — Опыт работы с gGRPC, Protobuf;
    — Опыт работы с каким-либо ORM (gorm, sqlboiler).

    . Общие требования:
    — Работа с docker и docker-compose на уровне пользователя;
    — Желателен опыт работы с каким-либо CI/CD (CircleCI, TravisCI, Drone);
    — Понимание очередей сообщений, опыт работы с RabbitMQ, Kafka или NSQ;
    — Опыт работы в Scrum/Kanban команде;
    — Знание принципов построения микросервисной архитектуры (choreography vs orchestration);
    — Опыт работы с ELK стеком, Graylog или чем-то подобным для логов;
    — Опыт работы с Kubernetes. Базовые знания, желательно с опытом написания helm charts.

    Возможно, на раннем этапе программирования вы не используете паттерны и пишете тяжело читаемый и сложно связанный код. Эта статья познакомит вас с методами исправления связности, которые помогут вам легко рефакторить и писать код.

    Простой веб-сервер на Go для обработки статических страниц.

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

    До сих пор не умеете пользоваться интерфейсами в Go? Исправляем недоразумение следующей статьёй.

    Пакет для работы со звуком в Go приложениях.

    REST API приложение на Go: пошаговый туториал

    В этой статье мы рассмотрим, как создать REST API приложение на языке Go: лучшая пошаговая инструкция с использованием популярной архитектуры.

    Предрелиз Go 1.12. Какие будут изменения — читаем в статье.

    О языке SQL на примере SQLite, MySQL и PostgreSQL

    Говоря о БД, нельзя не вспомнить о языке SQL, СУБД и запросах, непонятных на первый взгляд. После нашей статьи вы освоите основы SQL.

    Простой туториал по работе с SQL на Go.

    Библиотека для работы с нативными SQL запросами в Go.

    Пример еще одного роутинга на Go для создания веб-приложений.

    Лучшие практики использования языка Go с хорошими примерами кода.

    Качественное введение в шаблоны проектирования на Go.

    16 трюков для консоли Linux

    Сделали новую подборку трюков для консоли Linux. Будет полезно и новичкам, и профессионалам.

    Композиция интерфейсов в Go.

    ​​Хочешь стать программистом с высоким чеком оплаты? Пришло время действовать!
    Онлайн-университет Skillbox с 11 по 29 марта проводит ряд бесплатных вебинаров по программированию.

    Лучшие преподаватели-практики страны поделятся своими знаниями и секретами!

    Каждый участник получит электронный сертификат!

    Реализация паттерна Event Bus на Go.

    Список известных паттернов проектирования на Go.

    Что, зачем и когда: подробнее об операторе nil в Go.

    Анатомия срезов в Golang.

    Изучаем параллелизм на Go.

    Деплоим проект на Go через Docker.

    Список популярных паттернов проектирования, реализованных на языке Go.

    Если вы собираетесь написать веб-приложение на Go, советуем посмотреть в строну этого небольшого фреймворка.

    История про тестирование в Go.

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

    Библиотека реализованных структур данных на Go.

    В этой статье автор покажет, как писать простые приложения для командной строки.

    Лучшие практики по работе с JSON в Go.

    Анатомия функций в Golang.

    Об управлении версиями пакетов в Golang.

    Работает с PDF документами с помощью Go.

    Создаем RESTful приложение на Golang и MongoDB.

    Дайджест по Go с последней недели:
    — состояние Go на февраль 2020 года;
    — что ждать от Go в 2020: дженерики, модули, улучшенный обработчик ошибок;
    — алгоритмы и структуры данных на Go.

    Основы Go для самых начинающих. Вы узнаете, что такое Go, какие у него особенности, где часто применяется и многое другое.

    Интерактивная шпаргалка по Go для начинающих.

    Очередной HTTP клиент для Go.

    Пример создания подписок на Go. Возможно, вам как раз очень не хватает такого функционала в ваших скромных приложений.

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

    Огромная статья с советами, как поддерживать проекты на Go в реальном мире.

    Поговорим о недостатках и преимуществах языка Go.

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

    Теория современного Go.

    На данном сайте вы можете решать задачи и получать экспертизу от профессиональных разработчиков.

    Android для начинающих: использование REST API

    Russian (Pусский) translation by Ilya Nikov (you can also view the original English article)

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

    Это может звучать сложно, но с большим количеством сайтов, которые раскрывают свои ресурсы через REST API, на самом деле это довольно просто. (Смотрите руководство для начинающих по HTTP и REST для примера.)

    В этом уроке я расскажу вам, как использовать классы и методы, доступные в Android SDK, для подключения к удаленным веб-серверам и взаимодействия с ними с использованием их REST API.

    1. Включение доступа к Интернету

    Использование REST API, очевидно, связано с использованием Интернета. Тем не менее, приложения Andro >android.permission.INTERNET . Поэтому перед началом написания любого сетевого кода вы должны убедиться, что в файле манифеста вашего проекта присутствуют следующие uses-permission теги:

    Поскольку android.permission.INTERNET не считается опасным разрешением, вам не нужно запрашивать его во время выполнения на устройствах с уровнем API 23 или выше.

    2. Создание фоновых потоков

    Платформа Andro >execute() класса AsyncTask . В качестве единственного аргумента execute() ожидает объект Runnable .

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

    3. Создание HTTP-соединения

    Используя метод openConnection() класса URL , вы можете быстро настроить соединение с любой конечной точкой REST. Возвращаемое значение openConnection() должно быть передано в экземпляр HttpURLConnection или HttpsURLConnection , в зависимости от доступа к конечной точке через HTTP или HTTPS. Оба HttpURLConnection и HttpsURLConnection позволяют выполнять такие операции, как добавление заголовков запросов и чтение ответов.


    В следующем фрагменте кода показано, как настроить соединение с корневой конечной точкой API GitHub:

    Обратите внимание, что HttpsURLConnection является подклассом класса HttpURLConnection .

    4. Добавление заголовков запросов

    Большинство веб-сайтов, предлагающих REST API, хотят иметь возможность однозначно идентифицировать ваше приложение. Самый простой способ помочь им сделать это — включить уникальный заголовок User-Agent во все ваши запросы.

    Чтобы добавить заголовок User-Agent в ваш запрос, вы должны использовать метод setRequestProperty() объекта HttpURLConnection . Например, вот как вы устанавливаете заголовок User-Agent в my-rest-app-v0.1:

    Вы можете добавить несколько заголовков к своему запросу, вызвав несколько раз метод setRequestProperty() . Например, следующий фрагмент кода добавляет заголовок Accept и кастомный заголовок Contact-Me :

    5. Чтение ответов

    После того как вы передали все заголовки запросов, вы можете проверить, есть ли у вас валидный ответ, используя метод getResponseCode() объекта HttpURLConnection .

    Если класс HttpURLConnection получает код ответа на перенаправление, например 301, он автоматически обрабатывает его и следует за перенаправлением. Поэтому, как правило, вам не нужно будет писать дополнительный код для проверки перенаправления.

    В случае отсутствия ошибок вы можете теперь вызвать метод getInputStream() , чтобы получить ссылку на входящий поток соединения.

    Большинство REST API в наши дни возвращают данные, отформатированные как документы JSON. Поэтому, вместо прямого чтения из объекта InputStream , я предлагаю вам создать для него InputStreamReader .

    6. Разбор JSON ответов

    Andro >JsonReader , передав объект InputStreamReader его конструктору.

    То как вы извлекаете определенную часть информации из документа JSON, зависит от его структуры. Например, документ JSON, возвращаемый корневой конечной точкой REST API GitHub, выглядит следующим образом:

    Как вы можете видеть, ответ — это только один большой объект JSON, содержащий несколько ключей. Чтобы извлечь из него значение с именем organization_url, вам нужно будет написать следующий код:

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

    После того как вы извлечете всю необходимую информацию, вы всегда должны вызвать метод close() для объекта JsonReader , чтобы он освобождал все сохраненные ресурсы.

    Вы также должны закрыть соединение, вызвав метод disconnect() объекта HttpURLConnection .

    7. Использование разных HTTP методов

    HTTP-интерфейсы REST используют методы HTTP для определения типа операции, которая должна выполняться над ресурсом. На предыдущих шагах мы использовали метод HTTP GET для выполнения операции чтения. Поскольку класс HttpURLConnection использует по умолчанию метод GET , нам не нужно было его явно указывать.

    Чтобы изменить метод HTTP вашего объекта HttpURLConnection , вы должны использовать его метод setRequestMethod() . Например, следующий фрагмент кода открывает соединение с конечной точкой, принадлежащей httpbin.org, и устанавливает свой HTTP-метод в POST :

    Как вы уже знаете, POST -запросы используются для отправки данных на сервер. При записи в выходной поток соединения вы можете легко добавить любые данные в тело запроса POST . Однако, прежде чем вы это сделаете, вы должны убедиться, что вы вызываете метод setDoOutput() объекта HttpURLConnection и передаете ему значение true .

    В следующем фрагменте кода показано, как отправить на сервер простую пару «ключ-значение»:

    8. Кэширование ответов

    Всегда рекомендуется кэшировать ответы HTTP. Таким образом, вы можете не только сократить потребление пропускной способности вашего приложения, но и сделать его более отзывчивым. Начиная с уровня API 13, Andro >HttpResponseCache , который позволяет легко реализовать кэширование без каких-либо изменений в вашей сетевой логике.

    Чтобы установить кэш для вашего приложения, вы должны вызвать метод install() класса HttpResponseCache . Метод ожидает абсолютный путь, указывающий, где должен быть установлен кеш, и число, определяющее размер кеша. Вы можете использовать метод getCacheDir() , если вы не хотите указывать абсолютный путь вручную.

    В следующем фрагменте кода устанавливается кеш размером 100 000 байт:

    Как только кеш установлен, класс HttpURLConnection начинает использовать его автоматически. Чтобы проверить, работает ли ваш кеш, вы можете использовать его метод getHitCount() , который возвращает количество HTTP-ответов, которые были отправлены из кеша.

    Заключение

    Существуют тысячи REST API-интерфейсов, которые вы можете свободно использовать в своих приложениях для Andro >HttpURLConnection для использования таких REST API. Вы также узнали, как создать кеш ответов HTTP, который снижает использование потребление сетевого трафика вашим приложением.

    Если вы считаете, что использование HttpURLConnection слишком сложное, вам следует обратить внимание на сторонние библиотеки, такие как например, Volley. Библиотеки, подобные этой, используют класс HttpURLConnection внутри, но предоставляют множество удобных методов, которые позволяют сделать ваш код более кратким и читаемым.

    Чтобы узнать больше о работе с сетью на платформе Android, вы можете обратиться к руководству по сетевым операциям Android.

    Как правильно работать с REST API

    Коротко обо мне

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

    Вступление

    Скорее всего вам уже приходилось слышать о таком термине, как REST API, особенно если вы сталкивались с необходимостью получения данных из другого источника (такого как Twitter или Github). Но что же все-таки это такое? Что мы можем с этим делать и как мы можем это использовать?

    В данной статье вы узнаете все о REST API для того, чтобы работать с ними и читать связанную с ними документацию.

    Что же такое REST API?

    Давайте представим, что вы пытаетесь найти фильмы о Бэтмене на YouTube. Вы открываете сайт, вбиваете в форму поиска слово «Бэтмен», жмакаете «Окей» и видите список фильмов о супергерое. Похожим образом работает и WEB API. Вы ищите что-то и получаете список результатов от запрашиваемого ресурса.

    Дословно API расшифровывается как Application Programming Interface. Это набор правил, позволяющий программам «общаться» друг с другом. Разработчик создает API на сервере и позволяет клиентам обращаться к нему.

    REST – это архитектурный подход, определяющий, как API должны выглядеть. Читается как «Representational State Transfer». Этому набору правил и следует разработчик при создании своего приложения. Одно из этих правил гласит, что при обращении к определенному адресу, вы должны получать определенный набор данных (ресурс).

    Каждый адрес маршрутом, пакет данных — запросом, в то время как результатирующий ресурс – ответом.

    Анатомия запроса

    Важно понимать структуру запроса:

    1. Маршрут отправки
    2. Тип метода
    3. Заголовки
    4. Тело (или данные)

    Маршрут – это адрес, по которому отправляется ваш запрос. Его структура примерно следующая:

    Root-endpoint — это точка приема запроса на стороне сервера (API). К примеру, конечная точка GitHub – https://api.github.com.

    Путь определяет запрашиваемый ресурс. Это что-то вроде автоответчика, который просит вас нажать 1 для одного сервиса, 2 для другого и так далее.

    Для понимания того, какие именно пути вам доступны, вам следует просмотреть документацию. К примеру, предположим, вы хотите получить список репозиториев для конкретного пользователя на Git. Согласно документации, вы можете использовать следующий путь для этого:

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

    Последняя часть маршрута – это параметры запроса. Технически запросы не являются частью REST-архитектуры, но на практике сейчас все строится на них. Так что давайте поговорим о них более детально. Параметры запроса позволяют использовать в запросе наборы пар «ключ-значение». Они всегда начинаются знаком вопроса. Каждая пара параметров после чего разделяется амперсантом (что-то вроде этого):

    Как только вы пытаетесь получить список репозиториев для пользователя, вы добавляете эти три опциональных параметра и после чего получаете следующий результат:

    Если же вы желаете получить список моих недавно запушеных репозиториев, вам следует ввести следующее:

    Итак, как же понять, что маршруты рабочие? Что ж, пришло время проверить их на практике!

    Тестирование при помощи Curl

    Вы моете отправить запрос при помощи любого языка программирования. JavaScript может использовать методы вроде Fetch API или JQuery`s Ajax Method. Руби использует другое. И так далее.

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

    Мастер Йода рекомендует:  Как я попал в Cisco на позицию разработчика

    Перед тем, как продолжить, вам следует убедится, что Curl установлен на вашей машине.

    Ели же он не установлен, самое время установить. В таком случае вы получите ошибку «command not found».

    Для того, чтобы использовать утилиту, необходимо ввести следующее (по примеру):

    И как только вы подтверждаете ввод, вы получаете ответ (наподобие этого):

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


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

    Также попробуйте другие команды и произведите запросы! В результате вы получаете похожие ответы.

    JSON

    JSON – JavaScript Object Notation – общий формат для отправки и приема данных посредством REST API. Ответ, отправляемый Github, также содержится в формате JSON.

    Содержание объекта этого формата примерно следующее:

    Возвращаемся к анатомии запроса

    Вы изучили, что запрос состоит из четырех частей:

    1. Маршрут отправки
    2. Тип метода
    3. Заголовки
    4. Тело (или данные)

    Теперь же давайте попробуем разобраться с остальным.

    Тип метода

    Метод обозначает тип производимого запроса, де-факто он является спецификацией операции, которую должен произвести сервер. Всего существует пять типов запросов:

    GET – используется для получения со стороны севера определенного ресурса. Если вы производите этот запрос, сервер ищет информацию и отправляет ее вам назад. По сути, он производит операцию чтения на сервере. Дефолтный тип запросов.

    POST – нужен для создания определенного ресурса на сервере. Сервер создает в базе данных новую сущность и оповещает вас, был ли процесс создания успешным. По сути, это операция создания.

    PUT и PATCH – используются для обновления определенной информации на сервере. В таком случае сервер просто изменяет информацию существующих сущностей в базе данных и оповещает об успехе выполнения операции.

    DELETE – как и следует из названия, удаляет указанную сущность из базы или сигнализирует об ошибке, если такой сущности в базе не было.

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

    GET запрос в этом случае необходим, чтобы получить список всех репозиториев указанного пользователя. Также можно использовать curl:

    Попробуйте отправить этот запрос. В качестве ответа вы получите требование об аутентификации.

    Заголовки

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

    Заголовки представляют из себя пары ключей-значений. Пример:

    Также пример с использованием curl:

    (Примечание: заголовок Content-Type в случае Github для работы не является обязательным. Это всего лишь пример использования заголовка в запросе, ничего более.)

    Для просмотра отправленных заголовком можно использовать следующее:

    Здесь звездочка относится к дополнительной информации, предоставленной посредством curl. > относится к заголовкам запроса, а

    Записки программиста

    Как легко и просто написать REST-сервис на языке Go (гостевой пост Владимира Солонина)

    В этой заметке я опишу реализацию простого REST API для телефонной книги, созданной в прошлый раз. Должен сразу оговориться, что интерфейс к базе данных был изменен. Во-первых, прошлая реализация была направлена скорее на демонстрацию возможностей пакета database/sql, чем на решение задачи, а во-вторых, она была подвержена SQL-инъекциям.

    Примечание: Другие статьи Владимира вы найдете по следующим ссылкам:

    Сначала, как и прежде, считываются параметры подключения к базе из файла конфигурации и создается таблица, если ее еще нет. Далее создается роутер, регистрируются обработчики, запускается сервер на 8080 порту:

    Вместо стандартного http.ServeMux в качестве роутера я выбрал httprouter. Он проще в использовании и славится высокой производительностью. Есть, впрочем, у него и недостатки. В гибкости настройки он уступает многим другим роутерам. И он несовместим напрямую со стандартным интерфейсом http.Handler. Но для данной задачи это не проблема.

    Для кодирования/декодирования JSON используется пакет из стандартной библиотеки encoding/json. Его особенность в том, что он может работать только с экспортируемыми полями структур. А так как в языке Go экспортируемые идентификаторы всегда начинаются с заглавной буквы, они будут такими же и после кодирования в JSON. Изменить это поведение можно с помощью тегов.

    Тег — это строковый литерал, состоящий, по соглашению, из одной и более пар ключ:»значение» , разделенных пробелом. Теги могут быть присвоены полям структуры в качестве атрибутов и становятся в таком случае частью типа структуры. Программно теги могут быть получены с помощью рефлексии времени выполнения (пакет reflect). Так пакет encoding/json при разборе структуры Record считает теги и заменит имена ключей в JSON на заданные в тегах:

    Первый хэндлер, помимо возврата всех записей, поддерживает параметры запроса и может вернуть записи, содержащие заданную подстроку в поле имени.

    То есть, GET-запрос:

    … вернет все записи, где name содержит строку «abc». В случае некорректного параметра запроса вернется ошибка 400 Bad Request. В случае ошибки базы данных или проблем с кодированием в JSON — 500 Internal Server Error. Кроме того, сервер может вернуть ошибку 404 Not Found или 405 Method Not Allowed, если запрошенный URL не существует или не поддерживает данный метод.

    Второй хэндлер возвращает запись с заданным id или ошибку 404 Not Found, если такого id нет в базе. Но сначала id проверяется на корректность:

    func get >( w http . ResponseWriter , ps httprouter . Params ) ( int , bool ) <
    >, err := strconv . Atoi ( ps . ByName ( «id» ))
    if err != nil <
    w . WriteHeader ( 400 )
    return 0 , false
    >
    return >, true
    >

    func getRecord ( w http . ResponseWriter , r * http. Request ,
    ps httprouter . Params ) <
    >, ok := get >( w , ps )
    if ! ok <
    return
    >
    rec , err := readOne ( >)
    if err != nil <
    if err == sql . ErrNoRows <
    w . WriteHeader ( 404 )
    return
    >
    w . WriteHeader ( 500 )
    return
    >
    w . Header () . Set ( «Content-Type» , «application/json; charset=utf-8» )
    if err = json . NewEncoder ( w ) . Encode ( rec ); err != nil <
    w . WriteHeader ( 500 )
    >
    >

    Третий хэндлер добавляет запись в базу и возвращает код 201 Created в случае успеха. Если во время декодирования JSON возникла ошибка, возвращается код 400 Bad Request.

    Четвертый хэндлер изменяет запись с данным id. В случае успеха возвращается 204 No Content. Если такого id нет в базе, возвращается ошибка 404 Not Found.

    Пятый хэндлер удаляет запись с данным id. В случае успеха возвращается 204 No Content.

    Проверить работу приложения можно с помощью curl примерно таким образом.

    Получение всех записей:

    Получение всех записей имеющих в поле name подстроку «Маша»:

    Получение записи с >

    Создание новой записи:

    Редактирование записи с >

    Удаление записи c >

    Полный листинг программы доступен по этой ссылке (зеркало).

    Понравился пост? Узнайте, как можно поддержать развитие этого блога.

    Также подпишитесь на RSS, Facebook, ВКонтакте, Twitter или Telegram.

    Коротко о себе

    Популярные заметки

    • Моя шпаргалка по работе с Git, 8290 просмотров за месяц
    • Моя шпаргалка по работе в Vim, 6797 просмотров за месяц
    • Краткая шпаргалка по сочетаниям клавиш в IntelliJ IDEA, 4404 просмотра за месяц
    • Начало работы с PostgreSQL, 3064 просмотра за месяц
    • Быстрое введение в Kubernetes, 2339 просмотров за месяц
    • Настройка фаервола с помощью iptables за пять минут, 2281 просмотр за месяц
    • Пишем под микроконтроллеры STM32 в Arduino IDE, 2207 просмотров за месяц
    • Шпаргалка по основным инструкциям ассемблера x86/x64, 2131 просмотр за месяц
    • Шпаргалка по использованию умных указателей в C++, 2124 просмотра за месяц

    • Как спроектировать схему базы данных, 1545 просмотров за месяц
    • Зачем нужен Docker и практика работы с ним, 1540 просмотров за месяц
    • Устанавливаем связку из Prometheus и Grafana, 1471 просмотр за месяц
    • Основы сборки проектов на С/C++ при помощи CMake, 1459 просмотров за месяц
    • Советы и примеры задач, которые помогут вам в освоении нового языка программирования, 1441 просмотр за месяц
    • Построение диаграмм на Python с помощью Matplotlib, 1384 просмотра за месяц
    • Потоковая репликация в PostgreSQL и пример фейловера, 1358 просмотров за месяц
    • Установки и настройка OpenVPN в Ubuntu Linux за 5 минут, 1272 просмотра за месяц
    • Перестаем бояться виртуализации при помощи KVM, 1141 просмотр за месяц
    • Памятка по virtualenv и изолированным проектам на Python, 1127 просмотров за месяц
    • Памятка по отладке при помощи GDB, 1111 просмотров за месяц

    Копирование представленных на данном сайте материалов любыми способами не возбраняется.
    Указание ссылки на оригинал приветствуется. © 2009–2020 Записки программиста

    REST API приложение на Go: пошаговый туториал

    Getting started Tutorial — Restful APIs with Golang

    After couple years of developing web applications, I wanted something new, something different. I was looking for new technologies which have good support, good community and good perspectives. You will say that it may sounds obvious, nobody will turn to Basic Programming right now and you are right. But I needed a nice introduction for my tutorial.

    So, in fact, few weeks ago, I didn’t even know anything about Go Programming, just strict basics like who’s behind and what’s it made for but nothing more. I want to share with you, the way I learned Golang, that allow me today to start developing RestFul APIs as I wanted. To do so, what better way than creating bar/brewery! It may sound crazy but it’s not, we will together understand the concepts behind this by serving beers.

    Before any beers, we need to introduce what is Golang. Its development began at Google in 2007 and was released in 2009. It was thought to be a robust and fast language. It combines the benefits of few other technologies such as C, C++ and Python while avoiding some features of modern languages (methods, type inheritance). It was also design for clarity with user-friendly syntax. It is one of the best for quick compilation, concurrency developments and parallel executions. I did not made it up, this is one of the creators of the language, Rob Pike, that said: «You can compile and run a go program faster than some interpreters can even start». More recently, it can also be used to build mobile apps on Android and iOS devices.

    This tutorial is not about learning Go syntax, if you want to do so, I truly recommend you to visit the websites that I suggest at the end of this tutorial.

    Its favorite playgrounds :

    • Multicore performance
    • Concurrency
    • Cloud Computing
    • Microservices / API

    This is exactly what we are looking for. We need an efficient way to build our brewery and serve beers quickly to our customers.

    What is more obvious than installing Go on your machine? For this, nothing more easy, go to: https://golang.org/dl/ and follow the instructions depending of your OS. Personally, I use a Linux distribution and I use Goland from JetBrains as IDE, but you can also use Visual Source Code which have good support and plugins for Go.

    We will also need something to call your routes, something like Postman.

    As I said before we are going to build a bar/brewery. Here come some explanations. There will be 2 services, one for the bar, and another for the brewery. The customers will ask for beers to the bar and it will give beers to the customers. If the bar is out of stock, it will ask for barrels of beer to the brewery. If the brewery is out of barrels, it will start producing new barrels.

    Here, stocks can be related to databases. For the sake of simplicity, this tutorial won’t aboard part about working with databases, but I’ve linked some useful information at the end of it.

    The complete project is available on GitHub. The link is at the end.

    Our bar’s name is going to be The green dragon, reference to The Lord of the Rings, so let’s create our project folder into the $GOPATH directory.

    If you want more information about this, I invite you to visit: How to write go code by Golang Team and this article about go project layout

    Note that structuring files in a go project is a bit confusing. For a while, I wanted something like I always known, well divided packages and not too many files. But I understood that in Go, it does not really matter. In fact, organizing code like it would be done in Java, Python, or NodeJS is a bad thing, you’re probably fighting with the language if you do so. This article has helped me feeling better about my project architecture.

    We will use a third-party library for routing called Mux. To install it, if it’s not already done, just execute the command below:

    Any Go program start with a func called main in the package main , so let’s create main.go at the root of our workspace, and fill it with some basic instructions:

    Once you’ve done this, you have 2 possibilities:

    • Run $ go run main.go
    • Run $ go build . It’s going to compile and create an executable. Then, run $ ./theGreenDragon

    Remember these commands, you will need them each time you want to execute your program.

    You’ve now opened your bar, or at least a server on port 8000 . Next step, we will add routes and handlers.

    Routes and Handlers

    We are going to create separates routes for the bar and for the brewery:

    • /bar (GET) : All the informations about the bar and the beers they’re serving
    • /bar/ (GET) : Additional informations about a beer
    • /bar (POST) : Order a beer
    • /bar (DELETE) : When you’re too drunk, it can happens that you break your mug of beer.
    • /brewery (POST) : Order a barrel of beer
    • /brewery (PUT) : Produce new barrels

    Some of these routes should be restricted with authentication, but this is not the purpose of the tutorial, we will try to keep things simple.

    To add a route/handler, it’s quite easy:

    Let’s see, what it looks like with our project:

    You should see red right now :D. That’s because we have to implement those functions. For that, I decided to create to more file barHandlers.go and breweryHandlers.go . Let’s add to them the handlers of our routes.

    Let’s explain quickly how are composed these functions. There are 2 parameters, their names are quite evoking, the writer allows managing what is related to the response and the request contains everything you have to know about. request.

    Since we add new files and if you use the bash command go run main.go you may want to add the newer files following this command. For example go run main.go barHandlers.go breweryHandlers.go . If you don’t want to, you can always execute the go build command.

    You should now be able to run your program and access these routes.

    We talked about beers, barrels and mugs but we don’t know how to represent those in our application. It’s time to see how to create types! For this, I decided to create a file database.go which will be our database. So, it will contain the models and the lists we need.

    The types’ attributes are annoted with json properties, this is how you can create a link between your types and json objects. As we can see, Barrel and Mug contains a reference to the Beer they contain. I also created a method in order to initialize the lists. I call this method in my main() function, right before I build the routes.

    Let’s add some code into our handlers in order to do something when we ask for beers ! To begin, we will complete the GET methods for the bar.

    It’s quite easy for now, we iterate over the beers and when it matches with the query, we use the library json to encode the response. You can see a function FindBeerByID in database.go This is used in order to simulate a query to my database. We definitely should test if the return of the function is not empty but let’s say it always return what we asked for. Now that we know what to order, we will implement the feature!

    I’ve created a little structure which represents the order. It contains the ID of the beer the customer wants to drink, the quantity and the money to pay the bar.

    As you can see, I’ve also created one function serveBeer in barHandlers.go . It checks if there is enough beer, if not, it will ask to brewery a new barrel by calling the path /brewery via POST method. Then it serves the beers and returns the mugs.

    To keep this tutorial short, I did not include those codes inside, please visit or clone the GitHub project associated with the tutorial. You may have noticed that some of the functions’ name begins with a capital letter and some other is not. You can visit this StackOverflow thread or the official documentation.

    I skip the part about breaking a mug, there is nothing very interesting to see here. You can implements whatever you like. Personally, I added a counter that counts every mug that broke. But we could imagine a limited number of mugs where people have to give back their mugs after finishing their beers or something like that. This could be a great exercise for concurrency 😉

    In the previous chapter, we saw that the ServeBeer function ask for a new barrel if the bar is out of stock. Here’s the code of the brewery:

    We could totally call directly the function ProduceBarrels() from OrderBarrels but I wanted to show how to create a HTTP request. It could be useful when it comes to accest another service. The ProduceBarrels function is quite easy. Each time we call it, we create one barrel of each type of beer. Despite everything, we should think about checking that after producing the barrels, we have enough beer to satisfied the initial order, otherwise, we should produce new barrels until we fulfill the need. But once again, keep this tutorial simple.

    You can now launch the program and try to get infos about beers, order one and produce barrels of beer by calling the API. In this tutorial, I chose to not explain how create simple CRUD operations over REST method using Golang. You will find easily one on the Internet. Personally, I wanted something a bit fun, with a different approach. I especially wanted to talk about being called and calling other services. Note that all the code is available right here.

    Be aware that I add several comments in the final project, if some of those lines above was not clear, you probably want to check it.

    There is a lot of things that we could do to improve this getting started tutorial. We could write book about this ! If you want to go further, here some ideas:

    • Authentication
    • Validation
    • Unmock the database
    • Testing
    • Refactoring


    Thanks for reading, I hope you’ve learned something. If you liked the tutorial, please share it and give me your feedbacks !

    Go. REST или gRPC?

    В этой статье поговорим о двух подходах и нескольких инструментах, чтобы сделать HTTP API в Go.

    Глобально рассмотрим REST и gRPC и пройдемся по инструментарию.

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

    Разобраться в том, что такое REST и как его готовить мне помог гайдлайн от Zalando. Этот документ появился примерно тогда же, когда и инициатива OpenAPI. Также появился Design First подход, где вы сначала описываете API и только после этого уже начинаете реализовывать бизнес логику. С документом можно ознакомиться тут.

    Для построения REST API хорошо помогает swagger. Правда, инструментария в мире Go мало. Зато с ним очень удобно работать в каком-нибудь node.js. В случае с Go приходиться придумывать какие-то костыли в виде тестов, которые проверяют есть ли дока на эндпоинты, либо генераторы структур данных для Go из swagger.yml файла.

    Как без полной поддержки swagger сделать полноценную и поддерживаемую REST API в Go?

    Один из вариантов:

    1. Пишем swagger.yml
    2. Описываем модель
    3. Реализуем CRUD со стороны API и слоя работы с БД
    4. Пишем на второй пункт тесты
    5. Унифицируем и делаем на основе этого генератор

    В конечном итоге получается так. Описываем модель, генерируем код, реализуем бизнес логику.

    Также мы можем из swagger.yml генерировать модели дополнительно.

    Все приложения c REST API в большинстве строятся по обычной трехзвенной архитектуре.

    Обычно строил приложения с помощью echo фреймворка. У него хороший дизайн и нормальная скорость. Для слоя БД берем sqlx и с помощью этого набора и самописных кодогенераторов можно довольно быстро построить API. Хотя, все же порекомендую взять Python с какой-нибудь Django или Flask и на них сделать апишку. Но это в случае, если вам не нужно держать большую нагрузку.

    gRPC — инструмент от гугла, который активно пиарится и в го сообществе и за его пределами, позволяет делать хорошие внутренние API поверх HTTP/2 по умолчанию.

    В gRPC много крутого функционала, но самая важная фича — это кодогенерация и пропаганда Design first подхода по умолчанию.

    При использовании swagger есть большой соблазн не поддерживать доку, ведь это чаще всего дополнительный геморрой. При использовании gRPC этого не получится, потому что инструмент продуман более хорошо и он упрощает жизнь разработчику. У вас не получиться сгенерировать код, не написав proto файл и не расшарив его между командами разработки.

    Идеальный вариант использования gRPC — это общение между микросервисами и построение коммуникации с сервером для мобильных приложений.

    gRPC — это в первую очередь RPC фреймворк и он больше про методы в стиле UpdateBalance, GetClient и прочие. REST же — он про ресурсы. GET /users, POST /users и так далее. В gRPC можно спокойно пилить кучу методов, пока не упретесь в ограничение гошных интерфейсов в 512 метод на один интерфейс. Но обычно за это отрывают руки, потому что вовремя не вынесли часть логики в другой сервис.

    Так как эта статья больше про gRPC, то давайте возьмем обычный helloworld пример из доки grpc-go и будем его дополнять плагинами. Мы добавим валидацию данных, REST API к gRPC сервису и будем генерировать swagger.json с документацией к нему.

    Структура проекта у нас будет следующей:

    1. pb — пакет для хранения протофайлов и сгенерированного кода
    2. main.go — сервис, который будет конфигурировать и запускать наше приложение
    3. server — пакет для реализации логики нашего приложения
    4. Makefile — мейкфайл для автоматизации рутины

    Чтобы сгенерировать код, достаточно запустить

    На первых порах для автоматизации рутины нам хватит несколько команд, описанных в Makefile.

    Makefile нам нужен тут для того, чтобы всегда вводить make proto для генерации кода из протофайлов. К тому же эта часть будет расширятся и команд будет становиться больше и они будут длиннее.

    Сгенерировав код и реализовав основные интерфейсы для сервера, и сделав небольшую API, мы получаем следующий код

    Который запускается из main.go следующим образом

    gRPC-gateway или подружи REST с gRPC

    Недавно в одном из проектов мы решили использовать gRPC для общения между сервисами. Также нам нужен был адекватный REST для внешних клиентов.

    Ранее мы уже сталкивались с этим инструментом, изучали его и даже сделали проект с помощью этого плагина. Поэтому вспомнили о нем, ведь нас ждала неприятная перспектива поддержки нескольких сервисов, которые делают одно и тоже. gRPC-gateway в этом случае нам очень помогает, потому что в одном протофайле у нас будет и gRPC и REST описание.

    Устанавливаем его по инструкции, описанной в README, преобразуем наш протофайл в следующий вид

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

    Теперь команда proto сгенерит нам интефейсы для реализации логики, rest gateway и swagger документацию.

    Есть теперь небольшая проблема в том, что наш сервер будет слушать два сокета. Один для обеспечения работы grpc механизмов, а второй для обеспечения REST. Плюс гейтвей будет выходить посредником, конвертируя JSON HTTP REST представление в gRPC на протофайлах.

    Модифицируем наш код для запуска сервера и приведем его в такой вид

    Теперь мы запустим наш сервер и попробуем погонять rest запросы

    Таким образом у нас получилась REST API поверх GRPC. Но в этом примере не хватает валидации. Для валидации мы будем использовать https://github.com/lyft/protoc-gen-validate. Следуя примерам в документации, приведем наш протофайл в следующий вид

    Добавим еще одну команду для генерации нужного кода

    После перегенерации кода, мы видим, что валидация теперь для нас работает.

    Заключение

    gRPC экосистема очень дружелюбна для web сервисов на Go. Благодаря ей, можно ускорять разработку сервисов, генерируя бОльшую часть кода, который повторяется из раза в раз. Полный код проекта можно посмотреть тут.

    Если вы до сих пор пишете REST API и не знаете как хорошо документировать вашу API, то переходите на gRPC и экономьте время на программирование web сервисов на Go!

    Создание RESTful API: пошаговая инструкция

    Большинство из нас, разработчиков веб-приложений, в повседневной жизни создают REST API. API — основные средства связи между системами. В этой статье я расскажу, как лучше разрабатывать API, чтобы не совершать типичные ошибки.

    Требования Джеффа Безоса: ключ к успеху

    Многие из вас уже наверняка знают о требованиях Джеффа Безоса к разработчикам в Amazon. Если вы не слышали об этом, ниже перечислены основные его положения:

    1. Отныне все группы разработчиков должны раскрывать свои данные и функциональные средства через сервисные интерфейсы;
    2. Группы разработчиков должны связываться друг с другом с помощью этих интерфейсов;
    3. Больше никаких форм межпроцессного взаимодействия не допускается: никаких прямых ссылок и считываний данных других групп, никакой модели общей памяти, никаких «лазеек». Единственная разрешенная форма связи осуществляется через служебные интерфейсы по сети;
    4. Неважно, какую технологию используют разработчики: HTTP, Cobra, Pubsub, встроенные протоколы;
    5. Больше никаких форм межпроцессного взаимодействия не допускается: никаких прямых ссылок и считываний данных других групп, никакой модели общей памяти, никаких «лазеек». Единственная разрешенная форма связи осуществляется через служебные интерфейсы по сети;
    6. Все без исключения сервисные интерфейсы с самого начала должны проектироваться выгружаемыми. Это значит, что группа должна планировать интерфейс так, чтобы его можно было раскрыть остальным разработчикам. Исключения не допускаются;
    7. Все, кто не слушаются этих правил, будут уволены.

    В итоге эти требования оказались ключом к успеху Amazon. Компания смогла создавать эластичные системы, а позднее могла предложить эти услуги в лице Amazon Web Services.

    Принципы разработки RESTful API

    Для разработки RESTful API нужно следовать следующим принципам:

    Простота

    Нужно убедиться в простоте базового URL для API. Например, если нужно разработать запрос для продуктов, должно получаться так:

    Первый запрос к API — для всех продуктов, второй — для специфического продукта.

    Используйте существительные, а не глаголы

    Многие разработчики совершают эту ошибку. Обычно они забывают, что у нас есть HTTP методы для лучшего описания API, и в итоге используют глаголы в URL. Например, запрос для получения всех продуктов звучит так:

    Так часто поступают при создании URL.

    Правильные HTTP методы

    В RESTful API существуют различные методы, которые описывают тип операции, которую будет осуществлять API.

    • GET — для получения ресурса или группы ресурсов;
    • POST — для создания ресурса или группы ресурсов;
    • PUT/PATCH — для обновления уже существующего ресурса или группы ресурсов;
    • DELETE — для удаления уже существующего ресурса или группы ресурсов.

    Нужно обязательно убедиться в том, что вы используете верный HTTP метод для каждой операции.

    Не забывайте о множественном числе

    Эта тема еще стоит под вопросом. Некоторым нравится называть URL ресурсов во множественном числе, некоторым — в единственном. Пример:

    Мне нравится использовать множественное число, потому что в таком случае не создается путаница: работаем ли мы с одним ресурсом или с группой ресурсов? Также не нужно дополнять базовые URL, например, добавлением all: /product/all .

    Кому-то может не нравиться мой подход. Мой единственный совет — делайте так, чтобы в проекте все было единообразно.

    Параметры

    Иногда нужен API, который должен работать не только по имени. В таком случае для разработки API понадобятся параметры запроса.

    • нужно использовать /products?name=’ABC’ , а не /getProductsByName ;
    • нужно использовать /products?type=’xyz’ , а не /getProductsByType .

    В таком случае URL не будут слишком длинными, а структура останется простой.

    Правильные HTTP коды

    Существует множество HTTP кодов. Многие из нас используют только два из них: 200 и 500! Это плохая методика. Ниже перечислены часто используемые HTTP коды:

    • 200 OK — самый часто используемый код, свидетельствующий об успехе операции;
    • 201 CREATED — используется, когда с помощью метода POST создается ресурс;
    • 202 ACCEPTED — используется, чтобы сообщить, что ресурс принят на сервер;
    • 400 BAD REQUEST — используется, когда со стороны клиента допущена ошибка в вводе;
    • 401 UNAUTHORIZED / 403 FORBIDDEN — используются, если для выполнения операции требуется аутентификация пользователя или системы;
    • 404 NOT FOUND — используется, если в системе отсутствуют искомые ресурсы;
    • 500 INTERNAL SERVER ERROR — это никогда не используется просто так — в таком случае произошла ошибка в системе;
    • 502 BAD GATEWAY — используется, если сервер получил некорректный ответ от предыдущего сервера.

    Версии

    Версии API — важная вещь. Различные компании используют версии по-разному: кто-то — как даты, кто-то — как параметры запросов. Мне нравится указывать версии до названия ресурса. Пример:

    Мне также кажется, что стоит избегать использования /v1.2/products , так как это подразумевает, что API часто меняется. К тому же, точки в URL не так легко заметить. Так что чем проще, тем лучше.

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

    Разбиение на страницы

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

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

    В таком случае стоит использовать limit и offset. Пример: /products?limit=25&offset=50 . Также стоит установить эти настройки по умолчанию.

    Поддерживаемые форматы

    Также нужно выбирать то, как будет отвечать API. Большинство современных приложений используют JSON. Приложения старых версий должны пользоваться XML ответами.

    Верные сообщения об ошибках

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

    Я также видел некоторые примеры, в которых люди помещают в сообщения ссылку на ошибку, в которой рассказывается о ней и о способах избавления от проблемы.

    Open API Specification

    Чтобы все группы разработчиков в компании подчинялись одним и тем же принципам, будет полезно использовать Open API Specification. Open API позволяет проектировать API и делиться ей с потребителями в более простой форме.

    Заключение

    Довольно очевидно, что для лучшей связи отлично подойдут API. Если же они неудачно спроектированы, это вызовет только больше путаницы. Так что выкладывайтесь на полную в разработке, а дальше уже последует этап реализации.

    Мастер Йода рекомендует:  Интересные проекты инструмент командной строки, воссоздающий эффект дешифровки данных из фильма
    Добавить комментарий