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.