Understanding‎ > ‎


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.