The considerable aspects of API design

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...

More posts

Recent posts

  • Link (Story 4 of 4)

    Hitchcock was awake. Starlight filtered through the forest canopy and dappled the walls of the cabin he shared with Lester. A trio of Clytemnestra’s beetle bots was resting in Lester's sleep-crumpled dreads, occasionally flicking their wings in response to dreams. Sometimes he forgot ...

  • Sphere (Story 3 of 4)

    Clytemnestra was in fragments. Her programs were spread across her stolen space ship, the station she just stole it from, and the small bots that she used to steal it. As each program relayed its experiences to the other, an avalanche of memory effects like ...

  • Ship (Story 2 of 4)

    Lester was obsessed. It had been a year since the massive beam of light printed the white sphere that invited humanity to a distant star, and he still spent most of his time inspecting the sensor logs in his office. Pictures of the beam and ...

  • Beam (Story 1 of 4)

    Elizabeth Stinton was frustrated. Her simulations for turbulence in her theoretical air sinter were a mess and if she didn't have something to show at the next board meeting she was pretty certain that they'd sell her startup for parts.

    Standing up from ...

  • One Hour Fiction: The Panelist

    The pounding in my head is in sync with the ticking of the escalator steps as they rise from the netherworld of the convention center's floor. I pull a smile from memory and ignore the sweat in my eyebrows. So many happy attendees, clipping ...

  • Agreements: Fuel for the Engine of Business

    Note: This is an old post. I am now a CTO and no longer offer this service.

    The first person I watched run a company was Bly, the owner of a computer sales and service shop in Athens, Georgia. She gave me, a painfully young ...

  • What I hope Amazon is doing in secret

    Last weekend I had coffee at the wonderful Uptown Espresso with a friend from a nearby Amazon office. I write "a" nearby office because he's working on a multi-year project so secret that he can't even tell people which building he's in ...

  • Top 5 opportunities for growth in software

    I am a software engineering newbie. I thought that I knew a lot about it after I coded my first BASIC program on a TRS-100 way back in the before time, but now I see that the creation of software is a vast landscape of ...

  • It's safer in earthquakes, too

    "Trying to be happy by accumulating possessions is like trying to satisfy hunger by taping sandwiches all over your body." - George Carlin

    Happy Discardia, everybody! The weeks around the solstices are when we discardians let go of whatever is not adding value to our lives ...

  • Don't touch that dial

    I grew up in the future. My childhood room was next to an attic filled with science fiction so as soon as I could read I buried my nose in the universes of the great pulp era authors. I love it in that future because ...