Recommended
More Related Content
What's hot
What's hot (20)
Similar to Open API Specification - SiliconValley Code camp 2017 session @siddiqimuhammad
Similar to Open API Specification - SiliconValley Code camp 2017 session @siddiqimuhammad (20)
Recently uploaded
Recently uploaded (20)
Open API Specification - SiliconValley Code camp 2017 session @siddiqimuhammad
- 2. What are we trying to do today? • API Economy • OpenAPI is the de-facto standard for REST now • Has been there for some time now • Lots of good organizations are behind it • Open API Specification • Eco-System @siddiqimuhammad 2
- 3. @siddiqimuhammad By 2019, more than 30 percent of the 100 largest vendors' new software investments will have shifted from cloud- first to cloud-only. Gartner - Jun’16 The worldwide Internet of Things market is predicted to grow to $1.7 trillion by 2020, marking a compound annual growth rate of 16.9%. IDC Worldwide Internet of Things Forecast, 2015 – 2020. An estimated 25 billion connected “things” will be in use by 2020. – Gartner Newsroom API Economy 3
- 7. Open API Specification @siddiqimuhammad - Contract for REST Service - Defines Interface to REST API - Language agnostic - API Specs / API Docs —-> JSON / YAML format - No guesswork in calling the service - Documenting RESTful APIs - Open sourced - Single source of truth for REST API 7
- 8. History of OpenAPI Specification 2010 2011 2017 Project founded Swagger 1.0 2012 Swagger 1.1 2014 Swagger 1.2 – 2.0 2015 OAI OAS 3.0 @siddiqimuhammad 8
- 10. Community OAI BGB TDC TOB Business Governance Board Technical Design Committee Technical Oversight Board OAS: Organization of American States @siddiqimuhammad 10
- 11. Trends @siddiqimuhammad 2016 Google Group IRC Channel : #swagger Twitter 11
- 12. @siddiqimuhammad Is my API RESTful? Degrees / Levels or RESTful-ness 12
- 13. OpenAPI 3.0 – What changed? @siddiqimuhammad 13
- 14. Basic Layout of the Spec @siddiqimuhammad 14
- 16. Callback • Web hooks • Subscriptions • Content Syndication Response - - - - - - > At a later time (out of band) @siddiqimuhammad 16
- 19. Documentation from Specification @siddiqimuhammad https://github.com/temando/open-api-renderer React Renderer for SpecSwagger UI swagger.io Redoc https://rebilly.github.io/ReDoc 20
- 20. @siddiqimuhammad Documentation from Specification (f.k.a: Swagger.Ed) Postman 21
- 21. Migrating to Open API 3.0 @siddiqimuhammad swagger.io swagger-converter https://github.com/Mermade/swagger2openapi swagger2openapi 22
- 22. Swaggerizing REST APIs @siddiqimuhammad Contract First Code First 23
- 23. @siddiqimuhammad Contract First swagger.io Editor Restlet SwaggerHub apiary 24
- 24. Code First @siddiqimuhammad ASP.Net Web API —- > Swashbuckle scalatra-swagger "com.wordnik" %% "swagger-play2" SpringFox -> Automated JSON API documentation for API's built with Spring swagger-node-express 25
- 25. Validating Swagger Spec @siddiqimuhammad Swagger Validation Badge <img src="http://online.swagger.io/validator?url={URL}"> https://openapi- converter.herokuapp.com/api/v1/badge?url={URL} https://openapi- converter.herokuapp.com/api/v1/validate?url={URL} swagger.io Mermade 26
- 26. Open API & Microsoft @siddiqimuhammad 27
- 27. Open API & Google @siddiqimuhammad 28
- 29. Is there a OpenAPI Spec Hub? @siddiqimuhammad http://theapistack.com/ https://apis.guru/browse-apis/ https://watson-api-explorer.mybluemix.net/ 31
- 30. References • https://www.openapis.org/ • https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?tabs=visual-studio • https://github.com/OAI/ • https://developer.capitalone.com/blog-post/callbacks-in-openapi-specification-30/ • https://martinfowler.com/articles/richardsonMaturityModel.html • https://www.youtube.com/watch?v=4lBMQteMd6Y • https://www.openapis.org/faq/style-guide • https://www.openapis.org/specification/repo @siddiqimuhammad 32
Editor's Notes
- http://petstore.swagger.io/v2/swagger.json https://raw.githubusercontent.com/OAI/OpenAPI-Specification/OpenAPI.next/examples/v3.0/petstore.yaml
- Uber is a platform built on APIs provided by e.g. Google Maps. So these APIs create value chains. It’s just a matter of claiming your share. The API economy is an enabler for turning a business or organization into a platform. Semantic web is only possible with APIs working together to fulfill client’s needs. We live in an API economy, a set of business models and channels based on secure access of functionality and exchange of data.
- Makes consumption of your API easier by providing details about everything need to use your api. (methods, resources, parameters, media types) API adoption is affected by proper documentation This includes both private (in your enterprise) or public APIs. Moved from YAML 1.1 to YAML 1.2.
- In 2015, acquired by SmartBear. March 2014: Swagger 1.2 3.0: Initial draft: 02/2017, rc1: 04/2017, rc2: 06/2017, final-ver: 07/2017
- OAI: Organization that oversees the specification. It’s a collaborative project of Linux foundation. OAS: The specification. BGB: Licensing / Legal / Trademarks Doesn’t have influence on technical direction of the spec. - TDC: Responsible for Technical direction for the spec Manages open source projects like github.com/OAI
- Leonard Richardson HATEOAS: Hypermedia As The Engine Of Application States You let the hypermedia drive the interaction with the RESTful service. Web API is just another type of web application so why should be any different than the other web applications e.g. web sites. For using a website, we don’t need a formal training. We go to the main page, it has hyperlinks… and it goes on…REST APIs should also behave the same way. Martin Fowler calls it, “Steps towards the glory or REST”. url tempting and swagger?
- It is a breaking change. The specification can be defined in JSON or YAML https://github.com/OAI/OpenAPI-Specification/blob/master/README.md
- Changes: Semantic Versioning Github Markup for description to Common Markup. YAML 1.1 to YAML 1.2.
- https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/ https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#mediaTypes
- https://swagger.io/docs/specification/describing-request-body/multipart-requests/
- docker run -p 80:8080 swaggerapi/swagger-ui http://localhost Open API 3.0: https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v3.0/petstore.yaml React renderer uses Mermade for Open API validation.
- chrome-extension://kaggdmjacnelneophkagkdljffninnpd/pages/openapis.html?spec=https://raw.githubusercontent.com/OAI/OpenAPI-Specification/OpenAPI.next/examples/v3.0/petstore.yaml#general chrome-extension://kaggdmjacnelneophkagkdljffninnpd/pages/openapis.html?spec=http://generator.swagger.io/api/swagger.json# Collections are groups of requests that can be run together as a series of requests, against a corresponding environment. Using scripts, you can build integration test suites, pass data between API requests, and build workflows that mirror your actual use case of APIs.
- http://oai.swagger.io/api/convert?url=https://api.apis.guru/v2/specs/amazonaws.com/acm/2015-12-08/swagger.yaml http://oai.swagger.io/api/convert?url=http://petstore.swagger.io/v2/swagger.json https://openapi-converter.herokuapp.com/api/v1/convert?url=http://petstore.swagger.io/v2/swagger.yaml https://openapi-converter.herokuapp.com/api/v1/convert?url=http://petstore.swagger.io/v2/swagger.json Mermade: Swagger 2.0 to Open API 3.0 migration (https://openapi-converter.herokuapp.com) Used in command line Used as API
- Apiary is now acquired by Oracle. Editor: Use StudentAPI and show client and server code generation Restlet: Create Test API with Restlet SwaggerHub: Show export to API Gateway Apiary: DreddAPI Tester: The implementation matches the spec. https://dredd.readthedocs.io/en/latest/hooks/
- Swagger Spec: http://localhost:5000/swagger/v1/swagger.json Swagger UI: http://localhost:5000/swagger/ui/
- MERMADE https://openapi-converter.herokuapp.com/ https://openapi-converter.herokuapp.com/api/v1/validate?url=https://openapi-converter.herokuapp.com/examples/openapi.json https://openapi-converter.herokuapp.com/api/v1/badge?url=https://openapi-converter.herokuapp.com/examples/openapi.json swagger validate https://api.apis.guru/v2/specs/nytimes.com/top_stories/2.0.0/swagger.json
- https://docs.microsoft.com/en-us/search/index?search=openapi+swagger https://docs.microsoft.com/en-us/azure/connectors/connectors-native-http-swagger
- https://cloud.google.com/endpoints/docs/openapi/openapi-overview https://cloud.google.com/apis/docs/overview https://cloud.google.com/endpoints/docs/openapi/openapi-extensions
- Both RAML and API Blueprint have joined the OAI Initiative.
- API Specs can be available by the API providers themselves. Then they have a responsibility to versioning and maintenance of the specs. https://watson-api-explorer.mybluemix.net/ Is there a public space available for API specs as we have package managers including nuget.org or npm / bower? Nothing official yet but APIs.GURU and API Stack are closer.
- https://www.youtube.com/watch?time_continue=576&v=7MS1Z_1c5CU https://www.1src.com/video/t_7YcW25PHnAA