При создании интерактивного мобильного или веб-приложений нужна серверная часть, которую будет использовать приложение и разработчик этого приложения. Он должен знать маршруты, по которым можно найти методы, их описание, входные параметры и варианты ответов. В идеале хочется, чтобы из API можно было мгновенно сгенерировать клиентский код. А ещё реализация метода всегда может измениться, и нужно предусмотреть версионность, чтобы старые клиенты могли продолжать работать без ошибок. Можно подумать, что реализация этого может занять месяцы, но я покажу, как реализовать это на ASP.NET Core за 20 минут.

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

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

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

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

5. Как расшифровывается
API?
•Application
•Programming
•Interface
•интерфейс
программирования
приложений
•интерфейс
прикладного
программирования

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

7. Какие API успешные?
1.Лёгкие в употреблении (TTFSC, TTFHW)
2.Понятно как нужно, нельзя как не нужно
3.Ничего не ломается при обновлении
4.Getting started,
Multi-language code samples,
SDKs
https://www.slideshare.net/biztalk360/everybody-loves-swagger

8. Как узнать API?
•Исходники
•Метаданные
•Документация
•IDL
https://www.slideshare.net/whitlockjc/building-apis-
with-nodejs-and-swagger

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

10. Interface Description Language
Interface 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

11. Open API
Swagger

12. Swagger это…
Технология
Спецификация для
•Описания
•Документирования
REST API
Методология
Набор средств для
•Создания
•Употребления
•Визуализации
REST API
https://www.slideshare.net/VictorTrakhtenberg/swagger2

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

14. Редакторы
•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

15. DEMO
Swagger Editor

16. Подходы к разработке
Specification first
1.Реализую API
2.Вставляю
пояснения на месте
Implementation first
1.Пишу JSON
спецификацию
2.Генерирую
заглушки API
3.Реализую APIs
4.Публикую

17. Swashbuckle
Swagger на ASP.NET

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

19. Swashbukle
ASP.NET Core
.NETFramework4.5.1/.NETStandard1.6
• Swashbuckle.AspNetCore1.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

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

21. Явные ответы

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

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

24. DEMO
Swashbuckle

25. Успешные API
1.Лёгкие в употреблении (TTFSC, TTFHW)
2.Понятно как нужно, нельзя как не нужно
3.Ничего не ломается при обновлении
4.Getting started, Multi language code
samples, SDKs
https://www.slideshare.net/biztalk360/everybody-loves-swagger

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

27. ASP.NET Rounting
•Template
•Attribute

28. Template

29. Attribute

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

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

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

33. Способы версионирования
в 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 пути

34. Request URL Matched Controller
/api/helloworld?api-version=1.0 HelloWorldController
/api/helloworld?api-version=2.0 HelloWorld2Controller

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

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

37. DEMO
ASP.NET API Versioning

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

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

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

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

43. DEMO
Swagger + ASP.NET API Versioning

44. Успешные API
1.Лёгкие в употреблении (TTFSC, TTFHW)
2.Понятно как нужно, нельзя как не нужно
3.Ничего не ломается при обновлении
4.Getting started, Multi language code
samples, SDKs
https://www.slideshare.net/biztalk360/everybody-loves-swagger

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

49. Swagger + ASP.NET API
Versioning = Успешные API
1.Лёгкие в употреблении
2.Понятные
3.Не ломаются
при обновлении
4.Multi-language
generated code

50. Спасибо за
внимание
GitHub
github.com/xperiandri/
Social
fb.com/xperiandri
vk.com/xperiandri
twitter.com/xperiandri
YouTube
youtube.com/user/
andriicsharp

51. Спасибо за внимание
fb.com/xperiandri
twitter.com/xperiandri
vk.com/xperiandri
xperiandri@live.ru