Why isn't your API specification public?

I think realityking nailed it in terms of the API community needing to define compelling use cases. The catch 22 here is that it is hard for people to innovate around API specifications when they are so hard to get! Per the SDKs ... what if there was a NPM.org or rubygems equivalent of high quality SDKs that get automatically generated whenever I push a new API specification? That seems like it could be cool.

And your example of automated composition is fantastic! Curious if you are able to share how much work it is for you to get access to the specifications in order to make this possible? If we invented a common practice to publish something like api.company.com/spec.yaml could you have spent a lot more time on making cool integrations vs mining specs?

The only costs that would occur would be transaction fees for changing state in the Ethereum network (which is only required once for registering the service and at the order of half a cent at the current scalability level) and a similar amount for opening and closing the payment channels. I'm currently implementing a prototype extending http://hug.rest. If executed correctly, the following three lines of Python:

@hug.get("/pay_world", requires=pay("$0.001")) def pay_world(): return "You paid for this"

would result in the framework generating the OpenAPI spec amended with the payment metadata in the background and making it available under the service root. A middleware layer would check every ingoing request for payment signatures, closing the payment channel if necessary. Interesting things would become possible, although it is not clear if it all will succeed. Many different kinds of payment mechanisms would be conceivable, from pay-per-call to subscription based. Hypothetically, you could even pay APIs with gold backed cryptocurrency or tokens you issued yourself.

See here for a similar project and reasoning: https://github.com/etherapis/etherapis

If you've a Swagger/OpenAPI spec, you can use Swagger Codegen (https://github.com/swagger-api/swagger-codegen), a free and open-source project, to generate API clients (SDKs) in C#, Ruby, PHP, Java, ObjC, etc.

Here is an example: https://github.com/wing328/petstore-php

You can also use Swagger Codegen to generate server stub in SpringMVC, PHP Slim and more.

Disclosure: I'm a top contributor to Swagger Codegen.

(To convert RAML, API blueprint, WSDL, etc to Swagger/OpenAPI spec 2.0, please try https://github.com/lucybot/api-spec-converter - an open-source converter written in NodeJS)

And I disagree that formal specifications are intimidating. A formal specification is just code, so if you have trouble understanding something, you can enlist the computer's help. On the other hand, if an informal specification isn't clear to you, you are more or less screwed.

Yes, this is exactly the problem which I try to solve with my collection.

> Per the SDKs ... what if there was a NPM.org or rubygems equivalent of high quality SDKs that get automatically generated whenever I push a new API specification?

You can run the same tool on API owner side you don't need to publish your spec for that. I did a couple of interviews with API owner and they fear to loose control over SDKs, Docs, etc.

> Curious if you are able to share how much work it is for you to get access to the specifications in order to make this possible?

No, it's public info since my entire work is open-sourced under MIT license. I try to make process automatic as much as possible, so it starts from scraping. For example, I scrape Github for Swagger specs: https://morph.io/IvanGoncharov/API_specifications When I need to filter test, example, etc. APIs and find specs for real-life APIs. But get spec source is just first step, I need to fix errors in it(~80% have them), get additional info(logo, link to API key registration, etc.). But most time consuming is update them every day. My update/convert/validation scripts not ideal so I need to manually inspect all changes.

> ould you have spent a lot more time on making cool integrations vs mining specs?

Actually not I learn a lot from it, for example, you can fix all mistakes in API owner specs. Instead, you should give them a tool which will automatically inspect API spec and output errors/warnings/recommendations/hints. Together with my friend we working on OpenAPI/Swagger linter.

If you want to discuss more here is my Skype(ivangon4arov) and Hangouts(ivan.goncharov.ua@gmail.com) or APIs.guru public chat https://gitter.im/APIs-guru/api-models