Perks and Pitfalls of Self-describing APIs

Self describing APIs are a general method for describing or modeling of information that is implemented in applications and services.  Popular ones such as OData and Resource Description Framework (RDF)  use a variety of syntax notations and data serialization formats.  As platforms bring data-oriented web APIs online, each platform is responsible for the design of their web API. They are confronted by the same kinds of questions, and each team answers these in their own particular way.

How do you expose the data, the relationships between the entities inside the data and what should the querying look like?  Unfortunately, there are as many conflicting answers to these questions as there are RESTful web APIs.

Self describing APIs create standards that help solve this problem and we’ve created the best one yet.  Our solution provides the following benefits:

  • A Simple and Uniform way of sharing data at the protocol level.

  • We Enable broad integration across products and breaks data silos.

  • All you need is Http stack to integrate with our data structure

Many people are shying away from Self describing APIs for reasons like the following:

  • They have already started on their software stack with its own API before anyone knew about Self describing APIs, so it was too late.

  • Self describing APIs support completely arbitrary queries of any type (it's basically raw-SQL-in-another-form), which they don’t want  to allow on our production database. Send three or four monster bad queries through, and you could bring a production websites to their knees, interrupting service for everyone. That's why this arbitrary query stuff has ‘to be done in the cloud against the data dumps.’

  • I don't believe a one size fits all, generic API, specificity  is actually a good strategy for a site of our size”. There's a reason people build custom software to better solve specific problems, rather than building everything on Sharepoint or Drupal or WordPress or whatever.

We can help mitigate these concerns.  The Self Describing API we are building can fit on top of any setup with relative ease. Our query engine is resistant to overload. You don’t have to sacrifice targeted and nimble development for the power of standards.

We have a simple, uniform way of sharing data at the protocol level in a way that truly enables the lowest possible bar of entry, is key to enable broad integration across products and break data silos that form around applications.