You should publicly post these usecases somewhere, too, as a type of "Request for Projects". It gives people ideas... after all, you spend more time thinking about your API than anyone else ever will.
Not necessarily. Sometimes what you want is to combine data from multiple sources in interesting ways. A single API doesn't need to be versatile, it just needs to make useful information available.
Many times, the only way to do what you want with data is to use the API to get everything, then transform it locally. This is obviously really inefficient (and sometimes impossible).
Disagree. The most important thing by far is to have an API at all. Just being able to build your main site but with a different UI (or as a native program) is a more than good enough use case to make it worth publishing an API.
By all means improve the API if you can, but having one at all is the most important thing. And as people start using it they'll naturally map out the use case space and you can see what cases come up - rather than trying to figure out which interfaces people will need up front, it's much more efficient to respond to feature requests as they arise.
"HAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API.
Adopting HAL will make your API explorable, and its documentation easily discoverable from within the API itself. In short, it will make your API easier to work with and therefore more attractive to client developers.
APIs that adopt HAL can be easily served and consumed using open source libraries available for most major programming languages. It's also simple enough that you can just deal with it as you would any other JSON."
Plus it gives you a safe space to learn about the intricacies of running an API before you charge for it.
Also, as a developer if I heard "we are exposing an internal API and charging for it" I'd be confident that the API would be around.
It seems to me that, unless your product is a platform, you probably shouldn't publish a public API until someone requests it as a feature. And you should charge for it, especially if your hosting the API endpoint. Turn it into direct revenue to support the development and maintence of those API features.
Information consumed by eyeballs has different business models. You can paywall or you can have it ad-supported (or both). API clients don't have eyeballs, so ad-supported isn't an option. Microsoft has the Azure Data Marketplace, which is the only monetized API market that I'm aware of. My company provides APIs for cloud ETL that companies pay an annual subscription to use. You could say that Amazon Lambda is a metered API. My own opinion is that there will be lots of different business models. This is just getting started.
This kind of phraseology is a clear sign that someone's programming experience is extremely narrow in scope.
I had to skim like 5 paragraphs to even know wtf the title meant.
- postcode lookups
- sending email
- sending SMS
- multi-hop route planning
- engineer appointment scheduling
Question 1: Is there a de facto API/service description language standard out there?
Optional question 2: Which would be the best choice for a decentralised internet of services?
(Other options include RAML, Blueprint and IO Docs, but Swagger has the momentum)
A good starting point is to generate the SDK online: https://github.com/swagger-api/swagger-codegen#online-genera...
Swagger-Codegen can also generate server stub in SpringMVC, PHP Slim and more.
Disclosure: I'm a top contributor to the project.
WSDL on the other hand seems to be dead and/or unusable. Even one of its creators described it as a "train wreck" :)
Yeah, it's not. It's still what people in big enterprises do, or what people who want to do a quick API use.
If you're a .NET developer it's pretty easy to consume WDSL/SOAP services, so you might be more inclined to just use it when creating your own webservices.
There's of cause also the group that doesn't really know what they're doing, who just slaps a webservice method decorator on whatever internal function they wish to expose. Those are usually the worst APIs.
But yes, WDSL is a train wreck.
Disclosure: I'm a top contributor to swagger-codegen
Personally I use thrift. I think that's the most fit-for-purpose way of doing it. But many people object to any standard that's not purely HTTP-based.