Like most web coders of a certain age, I use every new codebase as an opportunity to attempt the One True API System (OTAS) which honors the essence of the web, provides developers with exactly the syntax they need for expressing the representation and logic of resources, and does so in a performant manner.

Here is a short list of the topics I addressed in the last iteration:

  • testing, both functional and load
  • documentation for internal and third party developers
  • example code
  • serialization format and tools
  • list pagination
  • filtering by resource attribute
  • related resource inclusion
  • server side resource definition and its relationship to persistence
  • request authentication: tokens and sessions
  • versioning
  • monitoring
  • rate and bandwidth limiting
  • blacklists for tokens, users, subnets, user agents
  • attack surface: DDoS, brute force attacks, unexpected exposure
  • third party application registration
  • third party access requests and restrictions
  • cross site scripting, benign and malicious
  • schema generation (yes, I'm trying a non-hypertext approach)
  • JS schema parser and backbone generator
  • third party language schema parser and client (e.g. python, java)
  • authentication: login, sessions, access partitions
  • Access-Control-Allow-Origin and Access-Control-Allow-Headers as well as ORIGIN requests
  • unsupported (though not private) API resources

On my plate but as of yet unaddressed:

  • push events (e.g. via websockets)
  • proxy and cache signalling

I've not yet built the OTAS but this last go feels pretty good. One day...