API, Design, Technology

Blank Slate: Building API’s for public consumption

So, next week I’m heading off to a new company.  A true startup, no existing product to speak of.  Blank Slate…

We will be building a SaaS based product.  The way people interact is entirely API driven.

We know we want a developer friendly experience.

  • Documentation needs to be solid and reliable.
  • Going from documentation to trying out our API’s should take minutes, not hours or days.
  • We want to keep breaking changes to a minimum.
  • All of our API’s should be consistent so there isn’t difficulty using multiple API’s, and learning a new one should leverage past experience
  • Performance should be high.
  • Clients (in many languages) should be easily supported.

Which brings me to this question “What type of API’s do we focus on?”, and do we focus on one, or multiple?

  1. GraphQL
  2. OData
  3. json:api
  4. custom ‘restful
  5. custom ‘rest-ish’

I’m currently leaning towards GraphQL, as it helps address versioning, functional documentation, and client generation.

There are obvious pros and cons to each.

I’m looking at the following options, and want to know if anyone else has opinions, thoughts or comments.

So to you, the reader:  What would you want to see? What would you suggest if you were starting out this journey with us?

Reddit thread(s):



Hopefully, as I go though this startup journey, I’ll be able to add more to this blog, maybe it can be a guide for others.