With the explosion of the API economy, there has been a push to create a set of standards that will help define the capabilities of an API, as well as what information should be returned from a specific call.  Most APIs simply implement a REST or SOAP architecture and a developer has to read through the documentation in order to understand all the calls that must be made in order to complete his/her project.   The advantage of using a set of standards is you can shortcut this process.  If a developer understands OData or RDF specifications, they can implement their project much more quickly.   I am going to talk about some of the specifications that are out there and what some of their capabilities are.

OData is a specification published by Microsoft.  It uses query parameters such as $metadata, $select and $expand.  These query parameters are one of the most powerful aspects of OData implementation. They allow you to increase or decrease the amount of information given in a single call which makes parsing the result data much easier.

$metadata will return the full structure of the data available as well as data types and relationship.  This allows you to add context to the returned information and also lets you branch calls based upon the returned relationships.

$select allows you to specify the information you actually want from a request.  This allows you to make your calls lighter since you can return a subset of the object instead of the whole thing.  This is especially useful for mobile applications where data caps can be a factor.

$expand allows you to retrieve the full relational object around a query.  This is especially useful for getting information around parent – child relationships or object permissions.

Resource Description Framework or RDF is a specification published by the W3C. It is built around the concept of the Entity-Attribute-Value model. For example to describe the phrase “The fox is the color red” You have an entity of a fox with an attribute color with the value red.  The main difference between RDF and OData is that an RDF document can be linked to other RDF documents that are hosted on other APIs and the entity attributes are defined in relation to those APIs. This is known as “linked data” and is a major component of the “semantic web,” an evolution of the internet that W3C is championing.

Ultimately, a specification is not required to build an API, but any sort of structured system you implement will make design decisions much easier.  Your developers will understand how to use the API quickly and it will also add a uniformity to all future API development.  This way you won’t end up publishing the Frankenstein’s Monster of APIs.