APIS — A Deeper Look Into The Developer Mindset
This post was originally published on the SYNQ blog.
In my last article, I talked about the key advantages APIs based companies have, but it might still be a little fuzzy on what exactly makes the model better. I believe there are two key concepts that differentiate the APIs of today vs the past. It lies in the seemingly paradoxical features of simplicity and flexibility . The reason for this is actually related to the developers seemingly contradictory behavior of “I am lazy” and “I can write everything myself”.
Extremely Easy to Start
- Easy signup process
- Free Trial or Low per usage or tiered pricing
- Plenty of documentation, specifically getting started guides, tutorials, SDKs and API specification
I want to highlight, that the phenomena of “easy to use documentation” is a key part of this. Look at all the ways you can interact with the APIs, you can read the tutorial, which is usually laid out well, and beautifully designed. The fact that there are multiple companies that make docs easier should tell you something (Read the Docs, ReadMe.io, Swagger, Gelato, etc.). But then there’s almighty GitHub, which makes both hosting of code, and the documentation of it very easy. So, if you’re a “read the docs” kind of person, you have a bunch of things to go through. If you’re a “let me see the API specs” person, that’s also easy. And then others who like to “interact with code” (like me), can jump right into GitHub and start looking at how the code is designed. Let’s take a quick look at Twilio’s doc to show you what I mean
Here you can see Twilio’s Python SDK on GitHub, and the description includes a reference to their documentation
Below is the link referenced in the GitHub repo’s description, with general information, as well as additional links back to GitHub and to other SDKs, Quickstart, Guides, Tutorials etc.
In the main section of the twilio-python repo, you can see install instructions and reference to the API documentation.
Finally, here is the “Read the Docs” page referenced by the above link, which takes the open source RST files located here and makes it easy to read and search
As you can see, everything is re-enforced, where you can jump back and forth between different docs, or you can just look at the GitHub README.md, which essentially describes many of the parts of what you see in official docs. So right here you see a format that was created to make it easy for docs to live with code (which is something many developers believe in), but also that there’s so many ways to interact with a service today. On top of this, many languages have their “documentation” generator which can look at comments in the code and generate API specs. Look at our Elixir-SDK reference we get for “free” by just putting in the right syntax in the language.
This all relates to the developer’s “laziness”. I want to just find a service that does something, and it just “works”. So, if I can pluck a plugin from pip, npm, rubygems or hex.pm and just “get the functionality”, I am going do it. If I go to Intercom, and look at the piece of JS embed code to drop in chat functionality, I am going do it. This is, I am really busy, and I don’t have to time to sift through a bunch of crap, so let me just get the SDK. But, don’t hide everything, as I am also curious so I want to look at your API specs and your open source code in GitHub, so I can also explore if I really wanted to.
The “ease of use” for this is just so starkly different from the old days of convoluted documentation, that it’s quite impressive.
Elegantly Powerful
- Deeper customization through configuration or code
- Enhanced functionality with integrations to other services
- Scale and grow with your business
Here’s where the services are separated, the truly great services make it very easy to start, but they make their “bones” by being extremely useful and powerful. This is to directly counter the standard developer’s mentality of “I can write this better myself”. As coders, we tend to believe we can build whatever, and really we probably can, but it comes down to the effort required for us to do it. Do we really want to spend hours and hours researching, then building a prototype, and then testing and eventually maintaining a piece of code if a service can just “solve my problems”? Of course not, but the moment an API becomes stringent or lacking of function, that little “devil” on your shoulder starts whispering “you can do this better”. The irony of this is, with today’s tooling, it is easier to launch your own applications. To build and run and test and host a service that I wrote, is 100x easier than it was 10 years ago. So, a truly great API service has to counter the developers inclination to “write it myself”. Many companies were born with this concept of “I can do it better”. So APIs are really in an arms race to prove that, we know what we’re doing, and you really don’t want to do it yourself. Below you can see how Twilio does it
Twilio has its own markup language for highly customized text and voice workflows
Here’s a quick glance at all the “verbs” or actions you can accomplish and stitch together
Here’s a look at the attributes of the <Dial> verb
Finally, here’s an example of their “Queue” feature with code reference right next to it
Conclusion
The best APIs usually are labeled with “it just works”. But what makes it work? It’s not just the reliability (which is a key feature), but it’s the ease of use, and the ability for the product to solve a problem for the developer. We are both lazy and DIYers all at the same time, so any service that can hit that sweet spot of making it very easy for me, but then lets me do stuff I want to do will have a place in any developers heart.
