I remember first hearing about RESTful API design at a Gartner Application Architecture, Design & Integration Summit back in 2008. I recall thinking how practical the idea was, leveraging GET, POST, PUT, PATCH, and DELETE to communicate with an API server.

It wasn’t until a couple years later that I started seeing RESTful APIs at client engagements. All of them seemed to follow the standard RESTful API design, making it easy to build client applications against the back-end API services built upon REST.

Well…all except for one.

A Different Design
As part of an application conversion project, I was told that there was very little work to do on the API side of the solution. My focus was to replace a legacy client framework with something more responsive.

When I started looking at the legacy code, I noticed that one single endpoint continued to be utilized over and over again. Basically, there was a single REST end-point, which was configured as a POST and required the client to provide a query that will be accepted by the end-point, executed and then returned with a standardized, but very generic response.

Here is an example:
var data = {
entityName:’CustomerVO’,
orderByAscending:’name’,
where: [
[‘dateDeleted:date’, ‘is’, null]
]
});
$http.post(‘//api.myapp.com’, data);

In the simple example above, the API is being asked to locate CustomerVO objects, which do not have a value for the dateDeleted attribute. The results would be ordered by the name attribute in ascending order.

The response would then be structured as follows:
{
“data”: [{
“id”: 1001001,
“entityType”: “CustomerVO”,
“dateDeleted”: null,
“name”: “ABC Company”
}, {
“id”: 5003003,
“entityType”: “CustomerVO”,
“dateDeleted”: null,
“name”: “Beta Company”
}, {
“id”: 3002002,
“entityType”: “CustomerVO”,
“dateDeleted”: null,
“name”: “Zeta Company”
}]
}

Only three records were located, and they were sorted by the name field.

This approach reminded me of a Seinfeld episode where (Cosmo) Kramer’s telephone started ringing as a result of Moviefone customers seeking show times in their area. Evidently, the number of Moviefone was very close to Kramer’s telephone number. So, instead of letting people down, he attempted to ask the caller to use their touchtone phone to type in the first three characters of the movie they wish to see. Unable to translate the touch-tone sounds into a title via a couple of guesses, Kramer finally announced in a robotic voice, “why don’t you just tell me the movie you selected?”

You can watch the clip here.

To me, instead of having a standardized manner to obtain a list of items for a given resource, the RESTful API is acting like Kramer almost to say, “why don’t you just tell me what data you want me to return.”

Brilliance or Insanity?
What I never really found out is if this design was brilliant or a less than ideal approach to meet the needs of the customer’s API.

On one hand, it was kind of neat to be able to place the control in the hands of client – empowering them to obtain whatever data was required. With this open access to the back-end data store, client-side developers do not have to wait for the back-end developer to release new end-points which provide access to the much-needed data.

However, the other hand is heavily weighted down with challenges with this approach.

For starters, there seem to be some significant security vulnerabilities with the approach – especially in cases where sensitive data could be exposed. A good rule of thumb is to not expect the client to maintain the same security levels – even if the client is internally facing. After all, some simple analysis of the network connections in order to determine the parameters of the POST request being used. From there, common tooling (such as Postman), could help the curious customer gain access to additional data.

With everything flowing through a single end-point, the potential for scalability issues also exists. As the POST-based requests for data increase in size, the response time is likely to also increase – yielding performance concerns. Compounding the issue would be the increases associated with additional clients of either the same application or a related application – leveraging the wide-open contract-free API.

Finally, nature of the response differing based upon the request seems like it would be a concern. Along the same lines, the support team may find it difficult – if not impossible – to make changes to the API without breaking every client utilizing the service. Of course, a new version of the API could be released, but at that point maybe it would make sense to convert to a more traditional RESTful API.

Conclusion
When I first encountered this API, the design caught my attention. In my mind, I wondered if this was a similar scenario to when everyone believed the earth was flat. That, all along, we the RESTful API developers were using an approach that was mythical, at best.
After giving this idea some additional thought, I believe that the challenges I noted (I am sure there are others) far outweigh the way-cool benefits of being able to “just tell the API what data you want it to return.” Still, this article gave me the opportunity to link back to a comical segment of one of my favorite situation comedies back in the 1990s.

Have a really great day!