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

  • PotassiumES Devlog #3

    Using Three.js to build a reusable border geometry for spatial UIs!

  • PotassiumES Devlog #2

    🌸 Updated potassium style system (KSS), now with margins!
    🌸 The path to the vNext
    🌸 A couple of new spatial controls

  • PotassiumES Devlog #1

    🌸 A brief intro to the existing samples
    🌸 Building UI components that work in flat, portal, and immersive display modes

  • What is PotassiumES?

    Update: This is still a handy reference but you might be interested in the new PotassiumES site.


    This is a post about PotassiumES, an ECMAScript library that enables browser-side development for the wider web. If you're not sure about the wider web, click that ...

  • Wider Web Lingo

    Update: This is still a handy reference but you might be interested in the new wider web section of the PotassiumES site.


    People sling around a lot of lingo when talking about the wider web, and even the term "wider web" is lingo!

  • Wider Web Lingo: Voice

    There's a lot of lingo around the wider web so this is one of a series of short definition posts.

    Voice: Phrases or other vocal noises that can be recognized and used as input

    Computers are getting pretty good at understanding ...

  • Wider Web Lingo: Gesture

    There's a lot of lingo around the wider web so this is one of a series of short definition posts.

    Gesture: A body motion that can be recognized and used as input

    Computers are getting better at watching how we position ...

  • Wider Web Lingo: More Hugs, Fewer Thugs

    There's a lot of lingo around the wider web so this is one of a series of short definition posts.

    More hugs, fewer thugs

    The wider web is inherently more intimate than the flat web that you hold in your hand ...

  • Wider Web Lingo: Spatial Controls

    There's a lot of lingo around the wider web so this is one of a series of short definition posts.

    Spatial controls: Interactive visual elements that are placed in the real or virtual environment

    Unlike page controls or overlay controls (the ...

  • Wider Web Lingo: Overlay Controls

    There's a lot of lingo around the wider web so this is one of a series of short definition posts.

    Overlay controls: Visual elements that seem to sit on top of a portal display

    Overlay controls on the wider web float ...