--
These days it seems to be fashionable to create REST APIs for things. But does your site really need a REST API? Here are some reasons not to create a REST API for your system.
1. It already has an API
Your system already has an API. And it is called HTTP. Most sites are a collection of HTML and a well-defined protocols on how to interact with it. For example, you can think of HTML as your json in a REST API, the URLs as your GET actions, your next, prev navigation links, and your forms as your POST actions.
Want to provide a developer with a list of products on your site? Let them scrape your products.html page, which has nicely defined pagination elements called Next Page and Previous Page! Want to accept a search query? A POST request with application/x-www-form-urlencoded data via a form will do!
You may say, “But Andriy! Surely this is so crude! My REST API is so much more developer friendly.” To which I say…
2. It Will Break
Your API will break. It will break when you least expect it. It will break when people most need it.
I use the terms API and REST API interchangeably here.
You see, your website essentially gets unit tested every second of every day. It gets load tested. It gets crash tested. This is because lots of people visit your site. They don’t visit your API.
How often does your API get exercised? If we assume that for every 1,000 people who visit your site, you get 1 developer who “visits” your API, you will find out about errors in your API thousand times less often!
3. It Will Change
Ha! But surely, my HTML will change, you say. Who is this guy? “Andriy, you’re a dummy! You see, every time a developer writes code to scrape my HTML page and I change the look of my site, it will break all existing clients!”
To which I say:
1. Yes. But your API will change too.
2. Your HTML will not change more often than your API will.
Which version is the Twitter API at now? If it took Twitter, a company dedicated to providing APIs, that long to come up with a relatively good solution, how long will it take you?
A curious thing. The concept of an API version does not work. I’m sure you googled “Best practices for API versioning”. To this day there is no consensus because no such consensus can exist. A system is defined by its behavior. Change its behavior and you change the system. It’s like saying that my vehicle is “car version 1” but when I redesign it to be an airplane it becomes “car version 2.”
Clients are always faced with changing APIs. Say a business has to integrate with around 12 different APIs, and each API changes about once a year, the client will have to rewrite their integration code every month!
Now, regarding HTML. When was the last time you changed your site’s HTML? In fact, how many times did you change it in total? The truth of the matter is that the site’s HTML changes rapidly during its development, but after that it stays the same. An occasional redesign might occur every few years! In my books, this is an A-OK timeline.
4. It Will Be Slow
Your API will be slow. I don’t care how smart you are, no matter how much time you spend on your REST API, it will not be faster than a system of internet servers, routers, proxies, caches, operating systems and browsers all designed to maximize the speed of HTTP traffic.
HTTP protocol has in place multiple optimizations to help save on bandwidth and roundtrips, like ETags, Cache-Control, max-age etc. When you write your own REST API you are ignoring years of internet research!
5. It Will Be Hard To Parse
I am sure many of you parsed JSON documents. “Parsing JSON documents is a breeze,” you say. Ok, let’s imagine we have this:
{
"glossary": {
"title": "example glossary",
"GlossDiv": {
"title": "S",
"GlossList": {
"GlossEntry": {
"ID": "SGML",
"SortAs": "SGML",
"GlossTerm": "Standard Generalized Markup Language",
"Acronym": "SGML",
"Abbrev": "ISO 8879:1986",
"GlossDef": {
"para": "A meta-markup language, used to create markup languages such as DocBook.",
"GlossSeeAlso": ["GML", "XML"]
},
"GlossSee": "markup"
}
}
}
}
}Now, give me the value of the para key from the above. Let’s examine a similar structure, but in html (or xml in this case):
<glossary><title>example glossary</title>
<GlossDiv><title>S</title>
<GlossList>
<GlossEntry ID="SGML" SortAs="SGML">
<GlossTerm>Standard Generalized Markup Language</GlossTerm>
<Acronym>SGML</Acronym>
<Abbrev>ISO 8879:1986</Abbrev>
<GlossDef>
<para>A meta-markup language, used to create markup
languages such as DocBook.</para>
<GlossSeeAlso OtherTerm="GML">
<GlossSeeAlso OtherTerm="XML">
</GlossDef>
<GlossSee OtherTerm="markup">
</GlossEntry>
</GlossList>
</GlossDiv>
</glossary>To get the value of the para element we can use a simple selector like this in jQuery: $('para').text(). There is a large, rich collection of standardized selectors that all parsers must follow. If these are not powerful enough, you can resort to xpath.
We often don’t realize how amazing the HTML parsers are today. They let you query for any component out of a DOM tree using very advanced query language. Any element you wish is at your fingertips, no matter how deeply it is buried in the document. Do you want to get some page’s menu? Ok, write a selector like .nav-home>a. Do you want to get the title of an article? Then .post-header>.post-title will get you there.
As long as the page does not change the immediate structure of the elements your selectors are using, they will keep working. Any surrounding structure can vary without affecting your queries.
Can you change anything in your JSON document without the parser going completely bonkers?
6: It Will Not Make You Money
In most cases, providing a REST API will not result in any return on investment of time and effort. So why do it?
“But Andriy! I want to be RESTfull. If I am RESTfull, my service will integrate with other big services and I will make money!”
First of all, the modern HTTP is RESTful. So enough of that buzzword.
Next, when you reach the point in time when you can actually charge money for your service, then, and only then, can you start thinking about designing any sort of an API. Before that point, you are designing an API with no client in mind. Why the heck would you do that?
Conclusion
While some of the points made in this article may have been too extreme (e.g. some sites really do need an API), it is worth seriously considering any decision to implement an API for your system. Does it really need to be there? If you design your system following the common web-standards and protocols, your system will be very easily accessible by other services already.
There is little reason to have one version of the system serve the majority of users, while another serve a few developers. This, lesser tested, system will often contain many problems and present frustrations to your clients. In fact, you may find developers ignoring your REST API completely and doing the good old fashioned HTML-scraping instead.
Happy system building!
