4 ms·

The Open API Initiative

80 points by xrorre 11y ago

Oras 11y ago
In this page: https://github.com/OAI/OpenAPI-Specification/tree/OpenAPI.next 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.
- porpoisemonkey 11y ago
  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/versions/2.0.md https://github.com/OAI/OpenAPI-Specification/blob/master/ver...
sharemywin 11y ago
Is there a directory of apis that conform to the spec?
- bbrennan 11y ago
  Yes! Over 200 specs are provided for free by APIs.guru: https://github.com/apis-guru/api-models https://github.com/apis-guru/api-models
- deleted 11y ago
  [deleted]
gtirloni 11y ago
How's this related to WSDL?
palakchokshi 11y ago
Next 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.
- doublerebel 11y ago
  Auto-generated client side consumers for APIs already exist, and are quite useful: https://apimatic.io 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.
- sinzone 11y ago
  Already happening. Tools (like https://gelato.io https://gelato.io) provide auto-generated docs, live test-console, code snippets and SDKs from your Swagger file. It comes with a free plan for OSS projects.
- Mikhail_Edoshin 11y ago
  I'm not sure about WSDL, the only thing I understand about it is that it was originally viewed as a simplified version of CORBA for Web :) But did XML Schema actually had that cycle of incompatible extensions you describe? I agree it's a bit heavyweight, but otherwise its concept is pretty clear and solid. To me HTML and CSS look more like vendor extension soup you describe. That said, there certainly will be extensions, because REST as it is is not sufficient for many scenarios. Take WebDAV, for instance: it has locks, batch updates, queries, standard support for sync, etc. REST has nothing of this sort. Have you ever tried to sync a large dataset against a typical REST API? It's very painful. While REST is simple, this simplicity mostly comes from being very basic. And WSDL and XML Schema are complex not because their authors are stupid (addition: or because there was some political wars), but because the subject itself is complex.
whatnotests 11y ago
What 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.
- porpoisemonkey 11y ago
  There does appear to be an examples section in the project repository https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v2.0 https://github.com/OAI/OpenAPI-Specification/tree/master/exa...
  - palakchokshi 11y ago
    I believe he meant a way to put examples in the spec itself. I believe they have a client SDK that will consume the API spec and allow you to make requests and see responses.
    - porpoisemonkey 11y ago
      Ah I see. The OpenAPI specification for the interface description language and the auto-generation tools are actually two separate entities so I'm not sure it would make sense that they put examples for a specific auto-generation tool in the official OpenAPI repository. It seems like the best supported tool for generating client and server stubs is Swagger Codegen. Version 2.1.2 seems to support the OpenAPI 2.0 draft spec. http://swagger.io/swagger-codegen/ http://swagger.io/swagger-codegen/ http://swagger.io/getting-started/ http://swagger.io/getting-started/
  - whatnotests 11y ago
    Yes, I mean documentation in general. It's fine to just show a long list of method signatures and class hierarchies, but a working code sample is the picture that's worth a thousand words.
yeukhon 11y ago
The 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.
- palakchokshi 11y ago
  What you are looking for is the semantic web or an accessible web. There are standards to create an accessible website but few developers do it unless their market has a significant number of visually impaired people. This is further complicated by Single Page Applications and/or web apps. If there was a browser extension or something that made every website accessible that would be an awesome extension.
JimDabell 11y ago
Does anybody have any recommendations for a Swagger-style documentation toolchain for REST APIs? I mean actual REST, not this weird anti-REST where you predefine fixed URI structures up front. REST APIs are based around media types, not URI structures. Unfortunately, tools like Swagger are based around URI structures, which shouldn't be in REST API documentation at all. It makes trying to find good tooling for REST APIs difficult when people say "just use Swagger" and similar.
malandrew 11y ago
Too little, too late. Thrift, gRPC, YaRPC, etc. are all RPC frameworks with strong typing and binary transports. They are still immature, but as such frameworks mature and support more languages, they will eat the lunch of any project trying to build on REST.

80 points by xrorre 11y ago

Oras 11y ago

In this page: https://github.com/OAI/OpenAPI-Specification/tree/OpenAPI.next 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.

porpoisemonkey 11y ago
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/versions/2.0.md https://github.com/OAI/OpenAPI-Specification/blob/master/ver...

sharemywin 11y ago

Is there a directory of apis that conform to the spec?

bbrennan 11y ago
Yes! Over 200 specs are provided for free by APIs.guru: https://github.com/apis-guru/api-models https://github.com/apis-guru/api-models
deleted 11y ago
[deleted]

gtirloni 11y ago

How's this related to WSDL?

palakchokshi 11y ago

Next 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.

doublerebel 11y ago
Auto-generated client side consumers for APIs already exist, and are quite useful: https://apimatic.io 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.
sinzone 11y ago
Already happening. Tools (like https://gelato.io https://gelato.io) provide auto-generated docs, live test-console, code snippets and SDKs from your Swagger file. It comes with a free plan for OSS projects.
Mikhail_Edoshin 11y ago
I'm not sure about WSDL, the only thing I understand about it is that it was originally viewed as a simplified version of CORBA for Web :) But did XML Schema actually had that cycle of incompatible extensions you describe? I agree it's a bit heavyweight, but otherwise its concept is pretty clear and solid. To me HTML and CSS look more like vendor extension soup you describe. That said, there certainly will be extensions, because REST as it is is not sufficient for many scenarios. Take WebDAV, for instance: it has locks, batch updates, queries, standard support for sync, etc. REST has nothing of this sort. Have you ever tried to sync a large dataset against a typical REST API? It's very painful. While REST is simple, this simplicity mostly comes from being very basic. And WSDL and XML Schema are complex not because their authors are stupid (addition: or because there was some political wars), but because the subject itself is complex.

whatnotests 11y ago

What 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.

porpoisemonkey 11y ago
There does appear to be an examples section in the project repository https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v2.0 https://github.com/OAI/OpenAPI-Specification/tree/master/exa...
- palakchokshi 11y ago
  I believe he meant a way to put examples in the spec itself. I believe they have a client SDK that will consume the API spec and allow you to make requests and see responses.
  - porpoisemonkey 11y ago
    Ah I see. The OpenAPI specification for the interface description language and the auto-generation tools are actually two separate entities so I'm not sure it would make sense that they put examples for a specific auto-generation tool in the official OpenAPI repository. It seems like the best supported tool for generating client and server stubs is Swagger Codegen. Version 2.1.2 seems to support the OpenAPI 2.0 draft spec. http://swagger.io/swagger-codegen/ http://swagger.io/swagger-codegen/ http://swagger.io/getting-started/ http://swagger.io/getting-started/
- whatnotests 11y ago
  Yes, I mean documentation in general. It's fine to just show a long list of method signatures and class hierarchies, but a working code sample is the picture that's worth a thousand words.

yeukhon 11y ago

The 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.

palakchokshi 11y ago
What you are looking for is the semantic web or an accessible web. There are standards to create an accessible website but few developers do it unless their market has a significant number of visually impaired people. This is further complicated by Single Page Applications and/or web apps. If there was a browser extension or something that made every website accessible that would be an awesome extension.

JimDabell 11y ago

Does anybody have any recommendations for a Swagger-style documentation toolchain for REST APIs? I mean actual REST, not this weird anti-REST where you predefine fixed URI structures up front. REST APIs are based around media types, not URI structures. Unfortunately, tools like Swagger are based around URI structures, which shouldn't be in REST API documentation at all. It makes trying to find good tooling for REST APIs difficult when people say "just use Swagger" and similar.

malandrew 11y ago

Too little, too late. Thrift, gRPC, YaRPC, etc. are all RPC frameworks with strong typing and binary transports. They are still immature, but as such frameworks mature and support more languages, they will eat the lunch of any project trying to build on REST.