- The document discusses OpenAPI, the de facto standard for documenting REST APIs. It outlines the history and evolution of OpenAPI, how to define REST API specifications using the OpenAPI format, and tools for generating documentation and validating specifications. Key topics covered include OpenAPI 3.0 updates, migrating Swagger specs to OpenAPI, and best practices for documenting REST APIs using OpenAPI specifications.
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
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
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.
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/
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.