I have a firm understanding of how APIs work, why they're valuable (to developers inside and outside a the service's operating organization). Here are some notes on the questions I have about them sometimes.
getting started is tedious. Maybe we can develop a standard around documenting REST APIs
then have a machine-readable export, and quickly build the skeleton for a library in any language based on that export of the document?
the skeleton would have:
all functions created with parameters (required ones listed first)
each paramater has an expected type and responses
maybe the machine-readable document could even specify the boundaries for valid parameters (for say if the parameter is an integer between 1 and 6)
possible problems: languages define data types differently, as would programmers in their libraries
Doxygen-style code documentation with a description of the function matching the endpoint, with all parameters and returns documented
API cloner: backend tools to take a specification and match functions up with data/views/actions. Sort of like how WordPress and Identi.ca cloned the Twitter API for their applications. The cloner would take the above machine-readable document to get the application developer started
APIs have versions and probably therefore need changelogs within major versions and between them.