Api

Методы HTTP

— getById

В случае успеха сервер возвращает с полями объекта в формате JSON в теле ответа (без дополнительного оборачивания в какой-либо объект)

В случае, если объект с такими id не существует, сервер возвращает

В ответе обязательно должны быть заголовки, касающиеся политики кэширования, т.к. браузеры активно кешируют GET и HEAD запросы. При остутствии какой-либо политики управления кэшем должно быть:

— списочный get

Простой случай: в случае успеха сервер возвращает с массивом объектов в формате JSON в теле ответа (т.е. ответ начинается с и заканчивается ).

Если массив получился пустой, всё равно вовзращается с пустым масивом в теле ответа.

Более сложный вариант: возвращается объект, в одном из полей которого — искомый массив. В остальных полях — данные о пагинации, фильтры, счётчики и пр. Только держите это консистентным по всем api.

— запрос заголовков

Полный аналог GET с таким же URI, но не возвращает тело ответа, а только HTTP-заголовки.

Реализация поддержки HEAD запросов веб-сервером обязательна.

Активно используется браузерами в качестве автоматических pre-flight запросов перед выполнением потенциально опасных, по их мнению, операций. Например, браузер Chrome активно кидается head-запросами для получения политик CORS при кросс-доменных операциях (виджеты и пр). При этом ошибка обработки такого head-запроса приведёт к тому, что основной запрос вообще не будет выполнен браузером.

Может использоваться для проверки существования объекта без его передачи (например, для больших объектов типа мультимедиа-файлов).

— создаёт новый объект типа :entity

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

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

указывающим на месторасположение созданного объекта.

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

Также метод POST используется для удалённого вызова процедур (RPC), в этом случае ответ будет иметь статус и результаты в теле. Вообще смешивать REST и RPC в одном api — идея сомнительная, но всякое бывает.

Единственный неидемпотентный некешируемый метод, т.е. повтор двух одинаковых POST запросов создаст два одинаковых объекта.

— изменяет объект целиком

В запросе должны содержаться все поля изменяемого объекта в формате JSON.

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

Идемпотентный запрос, т.е. повторный PUT с таким же телом не приводит к каким-либо изменениям в БД.

— изменяет отдельные поля объекта

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

В случае успеха возвращает с телом, аналогичным запросу getById, со всеми полями изменённого объекта.

Используется с осторожностью, т.к. два параллельных PATCH от двух разных клиентов могут привести объект в невалидное состояние

Идемпотентный запрос.

— удаляет объект, если он существует.

В случае успеха возвращает с пустым телом, т.к. возвращать уже нечего.

Идемпотентный запрос, т.е. повторный DELETE с таким же адресом не приводит к ошибке 404.

Получает список методов, доступных по данному URI.

Сервер должен ответить с дополнительным заголовком

Некешиуремый необязательный метод.

Главные возможности API Google Карты

Прежде чем переходить к профессиональному использованию API Google Карты нужно иметь определенный уровень знаний в объектно-ориентированном программировании. В этих целях отлично подойдет JavaScript. Для полноценной работы нужно получить ключ (для приложений, которые работают не на сервере, этот пункт не обязателен). С помощью уникального ключа компания Google может не только отслеживать приложения работающие с сервисом API, но и в случае надобности связаться с владельцем приложения. Очень удобно и практично для работы с картами использовать наложения (слои), за счет которых по координатам можно строить геометрические фигуры – примитивы, с их помощью происходит визуализация на карте.

К примеру: аналогом точки считается marker. Чтобы обозначить положение маркера на карте достаточно указать два сферических координата. Линия (line) задается координатами ее начала и конца, а вот полигон (polygon) с помощью множества сферических координат из положения узловых точек. Таким образом, важные точки на карте обозначаются маркером, рассчитать расстояние между двумя ключевыми точками можно за счет линии, а отобразить площадь, которую мы вычисляем можно при помощи полигона.

Типы API

Наиболее распространены во всемирной паутине так называемые Web API, которые используются в качестве платформы для создания HTTP-служб. Среди них выделяют:

• RPC (Remote Procedure Call ) – удаленный вызов процедур,
• SOAP (Simple Object Access Protocol) – простой протокол доступа к объектам,
• REST (Representational State Transfer ) – передача состояния представления.

API можно разделить по типу сервиса, у которого они есть: приложения, вебсайты и операционные системы. Например, у большей части операционных систем (Unix, Windows, MacOS, и т. д.) есть API, благодаря которому возможно программирование сервисов для этих систем.

Также API можно подразделять по типу доступа:

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

Как на архаичном рынке факторинга перевести все сделки в онлайн? Опыт «Сбербанк Факторинга»

Для большинства людей факторинг – услуга непонятная. По факту — это финансирование поставок компаний, работающих с отсрочкой платежа.

Предположим, вы небольшой производитель круп. Вы отгрузили товар в торговую сеть, но деньги получите в среднем через 60 дней после отгрузки. Многим компаниям ждать столько не под силу: ту же зарплату сотрудникам нужно платить уже сейчас. Одно из решений — факторинг. После заключения договора факторинга вы можете получить финансирование любой поставки. Достаточно после отгрузки товара отправить фактору подтверждающие документы (счета-фактуры, накладные, акты). Фактор верифицирует поставку у вашего покупателя и перечисляет вам деньги за товар, за вычетом собственной комиссии.

Разница между авторизацией через приложение и через сервисный аккаунт

Основными отличиями между авторизацией через приложение и через серверный аккаунт являются:

1. При авторизации через сервисный аккаунт не требуется подтверждать доступ к данным через браузер.
2. Сервисный аккаунт имеет доступ только к тем Google таблицам к которым вы сами ему предоставили доступ на почту. При авторизации через приложение вы подтверждаете доступ ко всей доступной вашему Google аккаунту информации.

По этим двум причинам наиболее предпочтительным способом автризации является авторизация через сервисный аккаунт

Но важно понимать, что если кто-то посторонний получит доступ к JSON файлу с ключём от сервисного аккаунта, он автоматически завладеет всеми правами и доступами которые вы предоставили этому сервисному аккаунту

Основные функции пакета googlesheets4

Все функции пакета разделены на 3 группы, каждая группа функций имеет свой префикс, который говорит об области действия этой функции:

• — объединяет функции реализующие операции над книгой GoogleSheets
• — операции над рабочими листами
• — операции над отдельными диапазонами ячеек
• — операции над отдельными ячейками

Давайте рассмотрим основные функции пакета googlesheets4.

• — Авторизация;
• — Создаёт новую Google Таблицу;
• — Открывает Google Таблицу в браузере;
• — Инициализирует подключение к Google Таблице, в качестве единственного аргумента принимает URL или ключ нужной Google Таблицы;
• — Считывает данные из указанного листа Google Таблицы;
• — Записывает данные в Google Таблицу, при необходимости создаёт новый лист. Если вы пытаетесь записать данные на существующий лист то все данные будут перезаписаны;
• — Дописывает данные на уже существующий лист;
• — Создаёт новые листы в существующей Google Таблице;
• — Удаляет существующие листы из Google Таблицы;
• — Выводит вектор содержащий имена листов Google Таблицы.

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

Открытые API — мода или необходимость?

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

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

Российское государство и его финансовый сектор уже осознали необходимость открытого банкинга. Предоставление банковских API внешним организациям признано ключевым элементом, необходимым для эффективной интеграции систем участников финансового рынка, инициативы выпуска открытых API поддерживают Центробанк, портал Банки.ру, Московская биржа, «Национальный клиринговый центр» и «Национальный расчетный депозитарий». Отдельные банки уже сформулировали свою стратегию открытого банкинга, определились с моделью дальнейших действий, официально анонсировали доступ к своим системам и сервисам через открытые API и приступили к соответствующим работам.

Список API на webMethods API portal

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

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

Кроме того, открытые API представляют своим партнерам такие разработчики программного обеспечения, как «Яндекс». Почта России тоже предлагает интеграцию с внешними приложениями через API, что позволяет встроить сервисы Почты России в сторонние сайты, приложения, системы учета и документооборота — например, добавлять на сайты функции отслеживания отправлений.

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

Но управление открытыми API никому не дано свыше. Оно невозможно без соответствующего технологического стека.

API – отдельная часть ПО

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

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

Если же мыслить глобально, то любую часть ПО, которую можно отделить от окружения, имеет смысл рассматривать как API. Также API может быть частью другого API. Например, если в ПО добавить стороннюю библиотеку, то она станет API, ведь получит интерфейс для работы с остальным кодом программы.

Более того: отдельный объект в коде тоже может иметь API. Так, в объектно-ориентированном программировании используют классы – они отражают типы объектов: классом может быть человек, геометрическая фигура и т.п. У каждого такого класса может быть свой API – набор методов и свойств, с помощью которых конкретные объекты этого класса (например, Иван Петров для класса «человек», круг или квадрат для класса «геометрическая фигура) взаимодействуют с другими объектами программы.

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

API операционных систем. Проблемы, связанные с многообразием API

Практически все операционные системы (Unix, Windows, MacOS, и т. д.) имеют API, с помощью которого программисты могут создавать приложения для этой операционной системы.
Главный API операционных систем — это множество системных вызовов.

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

С другой стороны, отличия в API различных операционных систем существенно затрудняют перенос приложений между платформами. Существуют различные методы обхода этой сложности — написание «промежуточных» API (API графических интерфейсов Qt, Gtk, и т. п.), написание библиотек, которые отображают системные вызовы одной ОС в системные вызовы другой ОС (такие среды исполнения, как Wine, cygwin, и т. п.), введение стандартов кодирования в языках программирования (например, стандартная библиотека [[Си языка C), написания интерпретируемых языков, реализуемых на разных платформах (sh, perl, php, tcl, Java, и т. д.)

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

Например: для того, чтобы увидеть в браузере строчку «Hello, world!» достаточно лишь создать HTML-документ с минимальным заголовком, и простейшим телом, содержащим данную строку. Что произойдёт, когда браузер откроет этот документ? Программа-браузер передаст имя файла (или уже открытый дескриптор файла) библиотеке, обрабатывающей HTML-документы, та, в свою очередь, при помощи API операционной системы прочитает этот файл, и разберётся в его устройстве, повызывает через API библиотеки стандартных графических примитивов операции типа «очистить окошко», «написать выбранным шрифтом Hello, world!», при этих операциях библиотека графических примитивов обратится к библиотеке оконного интерфейса с соответствующими запросами, уже эта библиотека обратится к API операционной системы с запросами вида «а положи-ка мне в буфер видеокарты вот это».

При этом практически на каждом из уровней реально существует несколько возможных альтернативных API. Например: мы могли бы писать исходный документ не на HTML, а на LaTeX, для отображения могли бы использовать любой браузер. Различные браузеры, вообще говоря, используют различные HTML-библиотеки, и, кроме того, всё это может быть (вообще говоря) собрано с использованием различных библиотек примитивов и на различных операционных системах.

Основными сложностями существующих многоуровневых систем API, таким образом, являются:

• Сложность портирования программного кода с одной системы API на другую (например, при смене ОС);
• Потеря функциональности при переходе с более низкого уровня на более высокий. Грубо говоря, каждый «слой» API создаётся для облегчения выполнения некоторого стандартного набора операций. Но при этом реально затрудняется, либо становится принципиально невозможным выполнение некоторых других операций, которые предоставляет более низкий уровень API.

Аналогия функциональности API

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

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

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

Так же организатору следует позаботиться о том, чтобы нанятые бригады не мешали друг другу. А еще луче помогали или совместно использовали один ресурс (автокран, готовый цементный раствор). Пожалуй, со стройкой достаточно.

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

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

Что входит в API и как он работает?

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

Элементами такого программного интерфейса, являются:

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

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

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

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

Каким образом все это происходит и как программные компоненты определяют к кому можно обратиться и что для этого нужно? Исполняющие функциональные модули имеют информацию о сигнатуре и семантике.

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

Возвращаюсь к нашему строительному примеру можно провести аналогию. Сигнатура это визитка (например, бригада выполняет укладку кафеля). А семантика – это бланк оформления заявки (От вас требуется указать точное место, площадь поверхности, предоставить плитку. Мы ее качественно клеим за N-сот рублей). Я думаю в общих чертах понятно, что такое api? Теперь поговорим о том, где применяется.

Как бороться с велосипедными сараями?

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

Делать так, как хотите. «Я художник, я так вижу!» — никакого bikeshed эффекта, делается все, что нужно, но на выходе появляются очень странные вещи. Это часто встречается во фрилансе

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

Спросить себя важно ли это? Если нет, можно просто не обсуждать, но это вопрос личного сознания.

Использовать объективные критерии. Про этот пункт я как раз буду говорить в докладе

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

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

Примеры API

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

• Обмен информацией о рейсах между авиакомпаниями и туристическими сайтами
• Использование Google Maps в приложении для совместных поездок (райдшеринга)
• Создание виртуальных собеседников в службе обмена сообщениями
• Встраивание видеоклипов с YouTube на веб-странице
• Автоматизация рабочих процессов в программных инструментах для B2B-сектора

Поиск, сбор и обмен данными

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

В качестве других примеров использования API для обмена информацией в режиме реального времени можно назвать издание The New York Times, позволяющее анализировать свою базу данных, в которой хранятся тысячи статей, и сервис Spotify, который позволяет искать музыку различных стилей и направлений. Даже у агентства НАСА есть открытые API, открывающие доступ всем желающим к спутниковыми изображениями и информации о созвездиях.

Избавление от лишней работы

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

Например, API-интерфейс YouTube позволяет встраивать видеопроигрыватели на сайт, формировать отчеты и получать доступ к полезным ресурсам.  

Укрепление новаторства и сотрудничества

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

Swagger в RBK.money — про наши внешние API

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

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

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

Так вот, о чем я сегодня. В этом посте я расскажу, почему мы в RBK.money используем Swagger, как он помогает нам в работе и какие у него есть косяки.

Что такое REST API

Из песочницы

Если говорить отдаленно, то REST API нужен для создания сайта. Но ведь для этого много чего нужно (скажете Вы) — в какой же части REST API?

Frontend и Backend

Начнем по порядку. Что такое frontend и backend? У сайта есть две стороны: лицевая и внутренняя соответственно. Первая обычно отвечает за визуальное расположение объектов на странице (где какие картинки, где какой текст и где какие кнопочки). Вторая отвечает за “действия”. Обычно это нажатия на те самые кнопочки или на другие “штуки” на сайте. Например, Вы заходите на страницу вашей любимой социальной сети и для начала Вам нужно войти в аккаунт. С лицевой стороны (frontend) Вы вводите логин и пароль и нажимаете кнопку “Войти”. В это время запрос отправляется в базу данных для проверки наличия такого пользователя, и в случае успеха, Вы попадаете в социальную сеть под своим аккаунтом, а в противном случае, Вы увидите сообщение об ошибке. В данном случае, за отправку запроса в базу данных по сути и отвечает backend сторона. Обычно ее разделяют на три подчасти:

1. Web API для приема запросов
2. Бизнес-логика для обработки запросов
3. Взаимодействие с базой данных

В этой статье мы поговорим в основном про API или Application Programming Interface и немного про бизнес-логику. Но для начала создадим сервер.

Удаляем статью

частая ошибка — пустой body

MIME-типы

• По умолчанию это text/plain — просто текст.
• Если ничего не указано, то браузер, скорее всего, будет иметь в виду application/octet-stream — просто поток бит.

• application/pdf;
• image/png;
• application/json;
• application/xml;
• application/vnd.ms-excel.

Коды ответов

тошибки 200 ОК

• 201 Created — успешный код. Статья создана, в ответ надо вернуть созданную статью.
• 202 Accepted означает, что запрос был принят, но его результат будет позже. Это долгоиграющие операции. На Accepted можно не возвращать никакого body. То есть если вы Content-Type в ответе не отдаете, то и body тоже может не быть. Или Content-Type text/plane — все, никаких вопросов. Пустая строка — это валидный text/plane.
• 204 No Content — тело может вообще отсутствовать.
• 403 Forbidden — вам нельзя создавать эту статью.
• 404 Not Found — вы залезли куда-то не туда, нет такого пути, например.
• 409 Conflict — крайний случай, который мало кто использует. Он бывает нужен, если вы на клиенте, а не на бэкенде генерируете id, а в это время кто-то уже успел создать эту статью. Конфликт — это правильный ответ в таком случае.

Создание сущности

• 422 Unprocessable Entity — необрабатываемая сущность. Вроде бы все здорово — семантика, есть код;
• 403 Forbidden;
• 500 Internal Server Error.

Лучшие практики

Отдельные схемы для создания и изменения

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

В автоматической tinyspec используются постфиксы и . Схемы могут быть определены следующим образом:

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

Семантика в названиях схем

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

Постфиксы можно варьировать и комбинировать. Главное, чтобы их название отражало суть и упрощало знакомство с документацией.

Разделение эндпоинтов по типу клиента

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

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

Пишем telegram бота на языке R (часть 2): Добавляем боту поддержку команд и фильтры сообщений

Tutorial

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

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

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

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