Reusable components: design or extract?

Are you always DRY or perhaps you follow the Rule of Three?

I’m currently working at a software company that has two business models, one is the familiar contracted services dev shop, the other is publishing a public set of API’s to accelerate application development.

We always try and look for opportunities to extract a reusable component out of project work, and include it in the API product.  However there are times we also are asked to design an API first, add it to the API product, then incorporate it into a running project.

Designing API’s for public use is difficult, designing an API for public use without pulling for an existing implementation, example or proof of concept is even harder.  

It has been my personal experience that I often need to refine an idea a few times before I feel its ready for public release.  To me, trying to build an abstraction over a concept in the form of an API, requires a level of knowledge and thus becomes an effort to generalize, versus lack of knowledge and an effort of mostly speculation.  I try to avoid premature generalization

When building an API, I generally prefer the extraction of proven functionality from a previous effort/project.  In the past this also was my preferred way of identifying code to pull into private library.  Over the years I’ve become more comfortable with the idea that I’ll make it easier to pull things apart but not worry all the time about creating more and more abstractions in my code.  

However, I do think we need to be careful and see if the “rule of three” can apply as we develop code.  If I find myself writing the same code or copy/paste-ing the same code I’ll extract it to a common method or API implementation right then.

What about you? 

When do you prefer to create an abstraction?
Comment on Reddit 

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.