The Open API Initiative
openapis.org
The Open API Initiative
1–10 of 23 posts
Re: The Open API Initiative
#2In this page: https://github.com/OAI/OpenAPI-Specification/tree/OpenAPI.ne...
The link to current specification is broken
Review the [current specification]. The human-readable markdown file is the source of truth for the specification.
Re: The Open API Initiative
#3Is there a directory of apis that conform to the spec?
Re: The Open API Initiative
#4How's this related to WSDL?
Re: The Open API Initiative
#5Next will come the API spec parsers to automate client code generation. Those will break on the first vendor specific extension. Vendors will put in extensions for security, pre and post request action guidance, etc. This will cause vendor specific client code generators to be created. The specification will take a long time to get updated as each vendor will want their extensions in the core specification. As a result even more extensions will be created.
We have seen this cycle before with WSDL and XML Schema, etc. I hope we have learned from our mistakes and don't go down the same path to have history repeat itself.
Personally I like the idea of an API Specification but the practical use has been a let down so far.
Re: The Open API Initiative
#6What most API documentation lacks is one thing.
Examples.
Real, working, copy-n-paste examples.
While I prefer the swagger format, we use Blueprint at work because it's trivial to include an actual example request or response as part of the documentation.
Sure, schema helps, but having a spot to just lay out an example request or response is really important.
Another thing: often, one must perform prerequisite steps before making a call to a given API method. Eg - you must have booked a flight before checking in. The context surrounding how an API fits into its use-cases is as important as the API itself.
Re: The Open API Initiative
#7Next will come the API spec parsers to automate client code generation. Those will break on the first vendor specific extension. Vendors will put in extensions for security, pre and post request action guidance, etc. This will cause vendor specific client code generators to be created. The specification will take a long time to get updated as each vendor will want their extensions in the core specification. As a resu…
Auto-generated client side consumers for APIs already exist, and are quite useful: https://apimatic.io .
If we can get producers to standardize all or part of their API, then we gain the ability to switch easily between providers and force them to compete on service instead of proprietary lock-in.
Ideally.
Re: The Open API Initiative
#8What most API documentation lacks is one thing. Examples. Real, working, copy-n-paste examples. While I prefer the swagger format, we use Blueprint at work because it's trivial to include an actual example request or response as part of the documentation. Sure, schema helps, but having a spot to just lay out an example request or response is really important. Another thing: often, one must perform prerequisite steps…
There does appear to be an examples section in the project repository
https://github.com/OAI/OpenAPI-Specification/tree/master/exa...
Re: The Open API Initiative
#9In this page: https://github.com/OAI/OpenAPI-Specification/tree/OpenAPI.ne... The link to current specification is broken Review the [current specification]. The human-readable markdown file is the source of truth for the specification.
Noticed the same thing. After some digging I found what appears to be the latest draft spec here: https://github.com/OAI/OpenAPI-Specification/blob/master/ver...
Re: The Open API Initiative
#10The real major Open API I always think is required is an Open API allow me to interact with any part of a website so people can finally build assistive technology based on API rather than parsing some website's DOM that you will likely never be able to parse out correctly from version to version. If the website exposes a "REST" specification how to interact with the pages, then we can really build a website visual impaired can finally used. Just my rant after trying to build one and realized how crazy it was to learn to work with DOM.