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

  • Wider Web War Room

    I was listening to a business plan for a wider web social space and it occurred to me that I'd heard a lot of these ideas before. Actually, I'd had a lot of these ideas.

    I went digging through my archives and I ...

  • Naming the Wider Web

    I will admit it, I like naming things.

    Projects, ideas, and pets; I love looking into their essential nature and pulling out a word or phrase that becomes their verbal and written flagship. I love it when other people engage in word-play with me until ...

  • Designing the Wider Web

    In the olden times, I made static web pages. They sat quietly on tubular displays that squatted like toads on the desk of every office worker. Early humans grunted at these pages with mice and keyboards. That was it.

    To write the simplest of web ...

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