Dogfooding your REST APIs
New technology in web development mostly follows a three fold pattern:
- Developers like, marketing and sales ignore
- Marketing likes, developers start dismissing
- Everyone forgets about it and it's just "always been there"
After that cycle, there will be something else going through it. You may remember things such as web fonts, responsive design and Node.js that have undergone this treatment. Ok, maybe Node.js is still at 2.5, because some insist on doing everything with it because it was sold as Node.
On REST APIs and CMSes
In the layman's content management space REST APIs are now on top of the hyperbole, with tools such as Drupal 8 and WordPress. There are countless reviews, articles and videos on how a REST API will unlock a WCMS as universal operating systems of the internet or something. Web developers to control my fridge, let alone my locks? The same guys and companies whose process is to fix things only after they're broken. Hmm...
The above discussions leads to having a full REST API. But as Michael S. Mikowski describes in his article RESTful APIs, the big lie, nobody even knows what a REST API is because it is not defined:
Ever notice how nobody calls their API "RESTpure"? Instead they call it "RESTful" or "RESTish". That's because nobody can agree on what all the methods, payloads, and response codes really mean.
There are certain principles behind REST that are agreed upon and should differentiate "a kludge script that returns some JSON" and a RESTful API. You can still have a perfectly valid API that adheres to the principles, but is limited in functionality.
A RESTful API can be worse than the kludge it replaces
Limited in functionality means that only a tiny subset of the application's functionalities can be done through it. In some cases exposing only limited functionality via a public API is fine, but with content management systems (CMS) REST APIs are mostly used to create glorified AJAX RSS readers with React or Angular instead of XML and vanilla JavaScript. The same shit sugarcoated.
Couple the REST principles leading to a swath of individual small HTTP requests and your RESTful API performs worse than the 2008 AJAX application it replaces. Not using customized aggregated data can lead to a worse user experience. Luckily HTTP/2 can leviate this by pushing all the requests to one, in fact you can start serving PHP REST APIs with HTTP/2 today. Atomic data versus larger aggregates remain a fifty-sixty situation.
Use your API, or it's illusion
For me a Content Management System must use it's own REST API extensively for it to be credible. In the software field this is called eating your own dogfood, or dogfooding. This means that the software you create is software you run, you are the developer and you are the user. You can talk the talk, but can you walk the walk?
This is why I expect any API that I consume to be used in the product extensively. It needs to be a first class citizen for me to build upon it. A social media application I build on your framework must be able to remove users from day one and the CMS content type editing tool must not litter my database with fragments of data when I remove a content type using the REST API.
Serve me a bowl of your finest dog food, not an À la carte side dish.