APIs

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.