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

  • What is PotassiumES? An In-flight Infodump

    Hi, there!

    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 link because otherwise the rest of this post won't make a lick of sense ...

  • Wider Web Lingo

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

    So, I wrote a series of short posts defining words and phrases ...

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

  • Wider Web Lingo: Page Controls

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

    Page controls: Visual elements that you're used to on the web like buttons, images, text fields, and blocks of text ...

  • Wider Web Lingo: Wand

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

    Wand: A handheld device with tracked orientation and position, often with touchpads, thumbsticks, buttons, or other controls ...

  • Wider Web Lingo: Immersive Display

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

    Immersive display: A display into a real or virtual environment that covers most of your field of ...