Remember, APIs are an abstraction

Have you ever noticed how the best APIs on the market seem to provide a simple elegant and clean interface to the data? Developers and API designers take note - this does not happen by accident.

This simple design principle was something that I didn't really pay much attention to when i was first building out our API, however I've become much more aware of it recently, and it is now almost impossible to change;

APIs are an abstraction of the data; not the representation of it

The easiest approach to developing an API is to simply take either the Database representation of a resource (e.g. the row), or it's associated application file (e.g. Java class) and run some sort of JSON converter over it.

This will give you a lovely output in JSON of the data. Expose this via a URL and job done, you've got an API.. right? …Wrong.

This pattern has two very large flaws;

1. Exposure of unnecessary fields
2. Tightly coupling your API to your Back End

Exposure of Unnecessary Fields

By simply exposing your internal resource representation as an API, you are potentially asking the API user fields they both don't need, and don't care about.

Take the following example, suppose this is a row in a database table:

id	name	email	billingreference
12345	Johnny Smith	johnny.smith@myapi.com	c_28f898joc90

Now this seems like a completely appropriate database table, so let's expose this as an API:

GET http://myapi.com/customers/12345
Accept: application/json
{
   "id" : "12345",
   "name" : "Johnny Smith",
   "email" : "johnny.smith@myapi.com",
   "billingreference" : "c_28f898joc90"
}

Looks good. Easy to consume, and matches the database perfectly. The only issue now is that you've exposed your billingreference data likely used for an internal system via your publicly accessible API.

This means that the user now has to inspect and make note of this data, (which they shouldn't really be seeing in the first place) and worse they potentially may store it 'just incase' they may need it in the future.

The second issue with this approach is that you've also tightly coupled your representation in the Database with your API representation.

Tightly Coupled API with your Back End

Tightly coupling is a major flaw in API development, and I have seen it happen numerous times.  By tightly coupling this information, you remove the ability to change your Back End system without having to also change your API.

APIs should be completely abstracted from the back end system, allowing users to consume the representation that you want them to receive, while being completely independent from where the data is stored.

If one day you wanted to remove the billingreference column above, and put it in another table, you now have to modify your API to continue providing this field, or version the API to deprecate it.

If it was never provided in the first place, you've saved yourself a rather large headache.

Provide only the fields that are useful, and nothing else

When designing your API resources, make sure you follow this mantra.  It will ensure that you have simple, clean and useful API representations that your users will love, and it will allow your developers to change their back end systems independent of the API representation.

This method also allows you to use tools like apiary.io and apiblueprint to design your API well before any actual coding begins, which is a major plus when trying to understand what your users actually want.

Originally posted on jordwalsh.com on 28 March 2015.