Сложно представить себе программу, в которой ничего не надо было бы конвертировать. Часто требуется читать настройки из YAML-файла и использовать JSON-формат в HTTP-запросах и ответах. Поэтому для разработчика важно уметь работать с разными форматами представления данных, знать возможности и ограничения сериалиации и десериализации.

В начале темы encoding, состоящей из четырёх уроков, разберём основные принципы архитектурного стиля REST, который чаще всего используется для обмена сообщениями в формате JSON. Затем рассмотрим структурные теги — они позволяют указывать метаинформацию об объекте или типе объекта, что даёт возможность соотносить поля структур и конечные данные при сериализации и обратном преобразовании. Два последних урока посвящены стандартным и сторонним сериализаторам данных.

В этой теме вы узнаете:

как применять пакеты сериализации из стандартной библиотеки Go (для форматов JSON, XML и gob);
как добавлять поддержку сериализации пользовательских типов данных и работать с динамическими спецификациями;
в каких случаях альтернативные решения лучше стандартных (на примере внешнего пакета easyjson);
какие внешние библиотеки можно использовать для работы с форматами YAML, TOML, MessagePack и Protocol Buffers.

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

Основы REST API

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

Что такое REST API

API (Application Programming Interface, программный интерфейс приложения) — это набор правил и функций, позволяющих приложениям взаимодействовать друг с другом.

API выступает посредником между приложениями, перенаправляя запросы (requests) и ответы (responses) от клиента к серверу и обратно. Например, аутентификация пользователя в приложении через существующий аккаунт в Яндексе происходит через API Yandex, который разработчики интегрировали в своё приложение.

REST (REpresentational State Transfer, передача состояния представления) — это программная архитектура, которая определяет условия работы API.

API, соответствующие архитектурному стилю REST, называют REST API.

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

Веб-службы, реализующие архитектуру REST, называют RESTful. Как правило, термин RESTful API относится к сетевым API. Но в целом REST API и RESTful API — это взаимозаменяемые понятия.

Архитектура REST не привязана к конкретным технологиям и протоколам, но построение RESTful API почти всегда подразумевает использование методов HTTP и распространённых форматов представления данных, например JSON или XML.

Вот так можно схематически представить REST API:

Элементы REST API

Сетевой API функционирует, как шлюз между основными элементами архитектуры REST — клиентами, ресурсами и серверами.

Клиент (client) — это программа, которая позволяет пользователю получить доступ к информации в интернете и задействует для этого API. Например, разработчики создают приложение, которое получает доступ к данным новостей. Этот доступ можно получить и в браузере, посетив новостной сайт.

Ресурс (resource) — это информация, которую приложение предоставляет своим клиентам. Ресурсами могут быть изображения, видео, тексты, числа и любые другие данные.

Сервер (server) — это компьютер, который отправляет ресурсы клиенту.

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

Принципы REST

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

Клиент-серверная архитектура (client–server architecture). Система должна быть разделена на клиент и сервер таким образом, чтобы клиент не был связан с хранением данных на сервере, а сервер — с интерфейсом и состоянием клиента. Это позволяет разрабатывать клиент и сервер независимо друга от друга, а также упрощать сервер и делать его масштабируемым.
Отсутствие состояния (statelessness). Сервер не должен хранить данные о состоянии сессии в промежутках между запросами и ответами. Вся необходимая информация для обработки запроса и идентификации клиента должна передаваться в самом запросе. Это помогает снизить нагрузку на сервер.
Возможность кешировать ответ (cacheability). Кеширование позволяет повысить производительность за счёт использования сохранённых ранее данных. При этом клиент должен точно знать, какая информация закеширована, а какая нет, чтобы при повторном запросе к серверу не использовать устаревшие или некорректные данные.
Многослойная система (layered system). Между клиентом и сервером можно добавлять промежуточный сервер, что позволяет обеспечивать безопасность и балансировку нагрузки, использовать общий кеш и улучшать масштабируемость. Допускается разделять систему на иерархию слоёв, при этом каждый компонент системы должен видеть только компоненты следующего слоя. Например, если вы вызываете службу PayPal, а она, в свою очередь, вызывает службу Visa, то вы не увидите вызова службы Visa.
Код по требованию (code-on-demand). Допускается загрузка и выполнение кода или программы на стороне клиента, но это необязательно.
Единый интерфейс (uniform interface). Это упрощает архитектуру и позволяет каждой её части развиваться самостоятельно. Вот четыре принципа единого интерфейса:
- Идентификация ресурса. В REST ресурсом является всё, чему можно дать имя: пользователь, изображение, предмет и так далее. У каждого ресурса есть идентификатор, который не меняется при изменении состояния ресурса. Идентификатор в REST — это URI (Uniform Resource Identifier).
- Манипуляции над ресурсами через представления. Представление — это текущее или желаемое состояние ресурса. Например, если ресурсом является пользователь, то представлением может быть XML- или HTML-описание этого пользователя.
- Самодостаточные сообщения. Запрос и ответ содержат всю необходимую информацию для их обработки. Дополнительные сообщения или запись состояния не нужны.
- Гипермедиа как средство управления состоянием. Состояние ресурса передаётся через тело ответа, параметры, заголовки и URI — это и есть гипермедиа. В само XML- или JSON-представление ресурса добавляются гиперссылки, по которым клиент может переходить к другим доступным на данный момент ресурсам.

Преимущества REST API

API можно проектировать в соответствии с разными протоколами и стандартами. Вот несколько из них:

RPC (Remote Procedure Call, удалённый вызов процедур) — класс технологий, позволяющих программам вызывать функции или процедуры в другом адресном пространстве, на удалённых узлах, либо в независимой сторонней системе на том же узле.
XML-RPC — вид RPC, который позволяет организовать обмен функциями между двумя или более сетями, передаёт информацию от клиента серверу по протоколу HTTP, а для описания запросов и ответов использует формат XML.
JSON-RPC — облегчённый RPC, использующий для запросов и ответов формат JSON и предоставляющий возможность асинхронных ответов.
SOAP (Simple Object Access Protocol, простой протокол доступа к объектам) — фреймворк для обмена структурированной информацией при реализации веб-сервисов в компьютерных сетях. SOAP использует формат XML, позволяет клиентам вызывать веб-сервисы и получать ответы независимо от языка и платформы.

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

Перечислим преимущества REST перед описанными стандартами:

Масштабируемость. Отсутствие хранения состояния снижает нагрузку на сервер: ему не нужно фиксировать информацию о предыдущих запросах клиента. Кеширование уменьшает количество взаимодействий между сервером и клиентом. В конечном счёте это позволяет увеличить пропускную способность сервиса, не уменьшив при этом производительность.
Гибкость. Большинство программных интерфейсов работают в формате приложение-приложение, а веб-службы REST API поддерживают полное разделение сервера и клиента. Это позволяет каждому компоненту системы развиваться независимо. Изменения платформы или технологии в серверном приложении не влияют на клиентское приложение. Возможность разделения функций на уровни ещё больше повышает гибкость. Например, разработчики могут вносить изменения в уровень базы данных, не переписывая логику приложения.
Независимость. REST API не зависит от используемой технологии. Можно создавать как клиентские, так и серверные приложения на разных языках программирования, не затрагивая структуру API.
Разноформатность. Обычно API используют конкретные форматы сообщений, например, SOAP использует XML. В REST обмен сообщениями может быть организован в JSON, XML и любом другом формате.

Как работает REST API

Клиент связывается с сервером через API, когда ему требуется доступ к какому-либо ресурсу. Вот основные этапы работы REST API:

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

Что содержит клиентский запрос

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

Уникальный идентификатор ресурса

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

Метод

Как правило, разработчики реализуют RESTful API с помощью HTTP. Метод HTTP сообщает серверу, что ему необходимо сделать с ресурсом. Ниже приведены четыре распространенных метода HTTP:

GET
Клиенты используют GET для доступа к ресурсам, расположенным на сервере по указанному URL. Они могут кэшировать запросы GET и отправлять параметры в запросе, чтобы сообщить серверу о необходимости фильтровать данные перед отправкой.
POST
Клиенты используют POST для отправки данных на сервер. При этом они включают в запрос представления данных. Отправка одного и того же запроса POST несколько раз имеет побочный эффект — многократное создание одного и того же ресурса.
PUT
Клиенты используют PUT для обновления существующих на сервере ресурсов. В отличие от POST, отправка одного и того же запроса PUT несколько раз дает один и тот же результат в веб-службе.
DELETE
Клиенты используют запрос DELETE для удаления ресурса.

CRUD

Здесь стоит упомянуть про CRUD-операции RESTful API.

CRUD — это аббревиатура от команд Create, Read, Update и Delete. Эти четыре основные операции помагают разработчикам взаимодействовать с базами данных. Несмотря на то, что термин CRUD пришел из базы данных, теперь он отражает принцип разработки динамических приложений, например таких как HTTP, SQL и DDS (Data Distribution Service, cлужба распространения данных).

Задачи, выполняемые командами CRUD:

Create — это процедура создания новой записи.
Read — это процедура чтения/извлечения данных на основе требуемых входных параметров.
Update — это процедура для изменения записей.
Delete — процедура для удаления (одной или нескольких) записей.

Заголовки HTTP

Заголовки запросов — это метаданные, которыми обмениваются клиент и сервер. Например, заголовок запроса указывает формат запроса и ответа, предоставляет информацию о статусе запроса и так далее.

Данные

Запросы REST API могут включать данные для успешной работы POST, PUT и других методов HTTP.

Параметры

Запросы RESTful API могут включать параметры, которые предоставляют серверу более подробную информацию о необходимых действиях:

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

Что содержит ответ сервера

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

Строка состояния

Строка состояния содержит трехзначный код состояния, который сообщает об успешном или неудачном выполнении запроса. Например, коды 2XX указывают на успешное выполнение, а коды 4XX и 5XX — на ошибки. Коды 3XX указывают на перенаправление URL.

Текст сообщения

Текст ответа содержит представление ресурса. Сервер выбирает подходящий формат представления на основе содержания заголовков запроса. Клиенты могут запрашивать информацию в форматах, например XML или JSON: они определяют запись данных в виде обычного текста. Например, если клиент запрашивает имя и возраст человека по имени Саша, сервер возвращает представление JSON в следующем формате:

JSON

{"name":"Sasha", "age":30}

Заголовки

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

Идемпотентность

С точки зрения RESTful-сервиса, операция (или вызов сервиса) идемпотентна тогда, когда создание большого количества идентичных запросов имеет такой же эффект, как и один запрос. Заметьте, что в то время, как идемпотентные операции производят один и тот же результат на сервере, ответ сам по себе может не быть тем же самым (например, состояние ресурса может измениться между запросами).

Например, методы PUT и DELETE по определению идемпотентны. Тем не менее, есть один нюанс с методом DELETE. Проблема в том, что успешный DELETE-запрос возвращает статус 200 OK или 204 No Content, но для последующих запросов будет все время возвращать 404 Not Found. Состояние на сервере после каждого вызова DELETE то же самое, но ответы разные.

Методы GET, HEAD, OPTIONS и TRACE определены как безопасные. Это означает, что они предназначены только для получения информации и не должны изменять состояние сервера. Они не должны иметь побочных эффектов, за исключением безобидных эффектов, таких как: логирование, кеширование, показ баннерной рекламы или увеличение веб-счётчика.

По определению, безопасные операции идемпотентны, так как они приводят к одному и тому же результату на сервере. Безопасные методы реализованы, как операции только для чтения. Однако безопасность не означает, что сервер должен возвращать каждый раз тот же самый результат .

Почему именно REST API

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

Кроме прочих, к его плюсам можно отнести и то, что он простой в реализации и понимании. Большинство пользователей интернета интуитивно понимают, как им пользоваться. Когда пользователь вводит URL в строку браузера и нажимает Enter, он отправляет запрос на REST API сервера.

Саша

REST — это набор рекомендаций для получения преимуществ, которые были описаны в уроке. Чем больше рекомендаций удастся соблюсти, тем более «рэстовым» получится приложение. Но обычно REST-ориентированными сервисы получаются только отчасти. Использование REST, как догмы, ни к чему хорошему не приведёт. Выбор решения зависит от ситуации и предъявляемых к сервису требований.

Дополнительные материалы

Хабр | Архитектура REST — статья о стиле REST.
Хабр | Hypermedia — то, без чего ваше API не совсем REST — подробнее о гиперссылках в сообщениях.
REST API Tutorial — лучшие практики в разработке RESTful-сервисов.