Андрей Чебукин "Построение успешных API"

Построение успешных APIАндрей ЧебукинThe Secret Circle SolutionsКА ШАГ

Построение успешных API

Андрей ЧебукинThe Secret Circle Solutions / КА ШАГ

Андрей Чебукин•Student Partner•MCSD: Windows 8 C#•Преподаватель: КА ШАГ•Соучредитель: The Secret Circle Solutions•Интересы: F#, functional programming, ALM, Azure

О чём•Что такое API•Какие API успешны в использовании•Как сделать успешные в использовании API

Как расшифровывается API?•Application•Programming•Interface

•интерфейс программирования приложений•интерфейс прикладного программирования

Что такое API•Структуры/типы данных•Операции•Сценарии использования

Какие API успешные?1.Лёгкие в употреблении (TTFSC, TTFHW)2.Понятно как нужно, нельзя как не нужно3.Ничего не ломается при обновлении4.Getting started,

Multi-language code samples, SDKs

https://www.slideshare.net/biztalk360/everybody-loves-swagger

Как узнать API?•Исходники•Метаданные•Документация•IDL

https://www.slideshare.net/whitlockjc/building-apis-with-nodejs-and-swagger

Документи-рование APIhttps://github.com/nazar-pc/opir.org/wiki

Interface Description LanguageInterface Definition Language •OMG (Object Management Group, CORBA)•Microsoft Interface Definition Language•WADL (Web Application Description Language)•WSDL (Web Services Description Language)•RSDL (RESTful Service Description Language)•Swagger•Protocol Buffers•Apache Thrift

Open APISwagger

Swagger это…ТехнологияСпецификация для•Описания•Документирования

REST API

МетодологияНабор средств для•Создания•Употребления•ВизуализацииREST API

https://www.slideshare.net/VictorTrakhtenberg/swagger2

Спецификация Swagger•JSON, чтобы определять метаданные•JSON, чтобы определять структуру API•JSON схема•Машиночитаемая•Независимая от языка программирования

Редакторы•Swagger Editor•editor.swagger.io

•Editor + swagger.js•apistudio.io

•Restlet studio (cross-format editor)• studio.restlet.com

https://www.slideshare.net/biztalk360/everybody-loves-swagger

DEMOSwagger Editor

Подходы к разработкеSpecification first1.Реализую API2.Вставляю

пояснения на месте

Implementation first1.Пишу JSON

спецификацию2.Генерирую

заглушки API3.Реализую APIs4.Публикую

Swashbuckle•Swagger на ASP.NET

Библиотека авто-генерации swagger.json•Использует ApiExplorer•Автогенерация•Точки расширения

•Легко найти спецификацию•Ничего не добавляет в реализацию

SwashbukleASP.NET Core.NETFramework 4.5.1 / .NETStandard 1.6• Swashbuckle.AspNetCore 1.0.0-rc3• Swashbuckle.AspNetCore.Swagger• Swashbuckle.AspNetCore.SwaggerGen• Swashbuckle.AspNetCore.SwaggerUI

ASP.NET Classic.NETFramework 4.5.1 • Swashbuckle 6.0.0-beta902• Swashbuckle.Swagger• Swashbuckle.SwaggerGen• Swashbuckle.SwaggerUi

200 по умолчанию

Явные ответы

XML комменты -> дока

Ещё•Версии спецификации•Фильтры•Определения способов авторизации•UI для просмотра и тестирования•C возможностью изменения и брендинга•С поддержкой сценариев OAuth 2

DEMOSwashbuckle

Успешные API1.Лёгкие в употреблении (TTFSC, TTFHW)2.Понятно как нужно, нельзя как не нужно3.Ничего не ломается при обновлении4.Getting started, Multi language code

samples, SDKs

https://www.slideshare.net/biztalk360/everybody-loves-swagger

Ломающие изменения•Удаление или переименование API или параметров API•Изменения в поведении для существующего API•Изменения в кодах ошибки и контрактах отказа•Что-либо, что нарушило бы Принцип наименьшего удивления

ASP.NET Rounting•Template•Attribute

Template

Attribute

А если нужно что-то изменить?Верс

ионирова

ние

!

Способы версионирования•По параметру строки запроса•По заголовку•По сегменту URL пути

ASP.NET Versioning•https://github.com/Microsoft/aspnet-api-versioning

Способы версионирования в ASP.NET API Versioning•По параметру строки запроса api-version=1.0•По заголовку•api-version или x-ms-version•Accept (media type) application/json;q=0.2;v=1.0

•По параметру строки запроса или заголовку•По сегменту URL пути

Request URL Matched Controller

/api/helloworld?api-version=1.0 HelloWorldController

/api/helloworld?api-version=2.0 HelloWorld2Controller

Request URL Matched Controller Matched Action/api/v1/helloworld HelloWorldController Get/api/v2/helloworld HelloWorld2Controller Get/api/v3/helloworld HelloWorld2Controller GetV3

Независимость от версии

DEMOASP.NET API Versioning

Как подружить Swashbuckle и ASP.NET API Versioning?•IOperationFilter•IDocumentFilter

Удалить version параметр

Проставить version в пути

Включить в док по версии

DEMOSwagger + ASP.NET API Versioning

Успешные API1.Лёгкие в употреблении (TTFSC, TTFHW)2.Понятно как нужно, нельзя как не нужно3.Ничего не ломается при обновлении4.Getting started, Multi language code

samples, SDKs

https://www.slideshare.net/biztalk360/everybody-loves-swagger

Что прикольного было в WSDL?

Swagger + ASP.NET API Versioning = Успешные API1.Лёгкие в употреблении2.Понятные3.Не ломаются

при обновлении4.Multi-language

generated code

Спасибо за внимание

Клацніть піктограму, щоб додати зображення

GitHubgithub.com/xperiandri/Socialfb.com/xperiandrivk.com/xperiandritwitter.com/xperiandriYouTubeyoutube.com/user/andriicsharp

Спасибо за внимание

fb.com/xperiandritwitter.com/xperiandri

vk.com/xperiandrixperiandri@live.ru