I've seen a lot of APIs on ReadMe.io, and one thing I've noticed is that many APIs tend to be built as though replicating the main site is the only usecase. Before launching an API, you should come up with 5-10 compelling usecases that someone couldn't use your website for.
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.
> "Before launching an API, you should come up with 5-10 compelling usecases that someone couldn't use your website for."
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.
Sure, this counts as a compelling usecase. Maybe your API just lets users list Items chronologically since that makes sense for your site, but someone else wants to get Items by location.
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).
> Before launching an API, you should come up with 5-10 compelling usecases that someone couldn't use your website for.
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.
The vain of my existence. APIs are about data structures, relationships and metadata. Give me these things without requiring me to go through your GUI to figure out what goes where. And yes, do come up with use cases for the API. Try and see it from the point of view of someone who does not know the implementation details. It's a very simple concept that for some reason gets lost.
"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."
Yes, pretty much HAL. I've never seen an API use this in the real world. I integrate with a lot of non-startup APIs and they can barely respond with proper JSON.
I agree that you want to do some thinking before launching an external API. A nice intermediate low risk step would be to launch the API internally and see how useful it is for folks in the organization. I did that a few years ago and it turned out to be very useful.
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.
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.