Recently, I was asked to take a side project I was working on based on an idea my boss had thrown out about gamification of work perks/promotions. I spent time (my freetime) and wrote up a backend with a RESTful API. I then wrote a simple JS library that wrapped the requests to make it easier to consume. Around this point, the team was included on the repo to start building out a frontend. When no one stepped up to take the lead, I went ahead and wrote up a framework to ease developing UIs inside of a basic, unified, look. There were form handling functions, major systems to dictate overarching interactions, and a unified style attached to DOM builders. I then wrote up a few sections that showed basic usage of this library (so people could copy from it and build from there), around this point, we were given half a day of work time to get started. Nothing got committed for the week after that. Today I called a meeting to see where everyone else was (hint: nowhere). I am dumbfounded…
The hardest part I am grasping is that their biggest gripe is not understanding what the backend code does, as in the underlying data structures and infrastructure. When consuming an API (such as GitHub’s) you are not required or expected to know how they store data. You don’t need to know the underlying system that ties into git to make commits or read the commit logs. You just need to know how to consume the API. With the growth (read: explosion) of APIs, being able to quickly begin using APIs has to be a critical skillset of a developer. If I want to begin using Twitter’s API (if they still let me), I should be able to read how the API calls work or the basic usage of a wrapping library and be consuming it soon after. Expecting for a Twitter engineer to sit down and explain how everything in their codebase works is absurd. Today’s industry is all about integrating with other services, and this is done via their API. There is little diversity in these APIs, as they are all designed against one of a few vague standards.
Being able to consume an API is very simple. If there is a specific thing you want
to use it for, you figure out how to get that and what is required to make that
request. If you are developing a general user of the API, you see what you can get
from it and build up from there. If you are given a library, you see what is
required to get moving (usually some auth or setup), connect via your favorite REPL,
and begin digging through what you get back. In this project, the person dealing
with creating/viewing skills just needs to read how to get skills
(lib.skills.get()) then figure out how to display them. To display an individual
skill, you just call the same with the basic skill document or it’s ‘url’ value.
To create a skill, pass in an object to (surprise!: lib.skill.create()). When
consuming an API, you are a slave to it. It is designed to be a public view of an
opaque system. As a developer, I don’t want to or need to know about what
is happening inside that giant white block of bits that I am asking for stuff from.
I am only required to know I am asking for things the right way and telling it to
store things properly (and if not, it will tell me!).
So please, as another developer, become comfortable in consuming an API. Don’t be afraid of just trusting the system it exposes (you really don’t have much other choice beyond writing your own). It is designed to be used and to use an existing system rather than writing your own. And most importantly, it is designed to be quick to begin using it.