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

  • Augmented Reality is for Seeing Better

    A product designer friend recently asked me, "What is the fundamental capability that augmented reality provides?"

    The fundamental capability that current eye glasses provide is to see better. They help near sighted people see far away things. They help older eyes see things that are ...

  • Neighborhood XR

    Scenario: What is this bug?

    Stephen sits at the bus stop and sees a little bug with too many legs. He wonders what it is, so he pulls out his handset and browses over to the Tree of Life site, then clicks on the link ...

  • 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 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 and skinny townie kid, a ...

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