I finally understand why Swarm is not as essential as I thought and can be added later as an addon.
I have also been thinking more about APIs on Ethereum in general, and in the end it comes down to either having a middleware/gateway/proxy or programming language library implementing some standards on both the client and server side. Latter may be preferable because it includes no heavy dependencies (as is the case with Kong (Nginx+Cassandra)), but at some scale, load balancing for virtual services and fragile p2p links would have to be handled anyway.
There are many open questions, for example how authentication (with HTTP Header signatures?) or payments are handled. Restricting payments to a subscription based model brings its own problems, for example users acting as proxies for others. With regards to an offchain SDL, https://openapis.org/ still looks promising, maybe it would make sense to add some custom identity fields and corresponding functionality to the server/client generator.
I haven't created an API on a larger scale before. It all depends on the scale of the deployment, it certainly makes a difference whether a toaster or the entire Facebook API is behind it.
Thanks for your answer on ethereumprogramming :) Do you know of anyone else working on generalized API micropayments? Another subarea to investigate would be search. With service descriptor files, the API could include (externally signed/certified or selfmade) tags, but finding a service would still require iterating over the entire list. This might be an appropriate place to go meta and let the Google of tomorrow offer a service for search ;)
I should look for datastructures that make finding ranges of values, signifying prices, positions etc. easier.
I just completed the first iteration of my API payment prototype in Python. I had to create web3.py first. This is sufficient on the server side: https://raw.githubusercontent.com/void4/paymentchannel/master/example.png
The hug framework with the new extensions takes care of everything (documentation generation, signature validation and persistent storage). It also returns the 402 status code if no header was included, together with the payment path (e.g. pay://0xaccount/value).