Date post: | 05-Apr-2017 |
Category: |
Technology |
Upload: | fwdays |
View: | 96 times |
Download: | 6 times |
Построение успешных 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