Essential Types of API Hygiene

"Brush your teeth, twice a day"

"Wash your hands before you eat"

"Shower every morning"

Human hygiene is ritualized from a young age – and for good reason. Hygiene rituals protect communities from plague, and individuals from easily preventable serious issues.

But do you see the trick? These rituals work because they have triggers attached to them.

Before you A, make sure you B. These triggers create habits in people, and turn us into well-oiled machines.

API Hygiene is the (often overlooked) set of practices and policies that you apply to incoming and outgoing data. Just like proper human hygiene protects health and reduces issues, API Hygiene insures that what comes into and goes out of your app keeps your system in running order.

Also, like humans – these rules need to have triggers attached. When an event happens, or an input is received, there are things that we **always**** do. When you skip a trigger, you've broken the ritual – and you can't be confident in the result.

The 3 categories of API Hygiene are:

• Sanitization
• Validation
• Hydration

Sanitize

WHAT IT DOES:

Automatic manipulation of incoming content, that will silently be applied to incoming data.

WHEN TO USE IT:

This step ensures that what was provided in a request, matches the format your data expects. The easiest example to think of here are dates. If you store a dates as "2016-12-25" and the client provides "December 25, 2016" then your *sanitize* step is responsible for sanitizing data. Sanitization can also remove or inoculate extra or malicious characters.

Validate

WHAT IT DOES:

Check for acceptable values, returning an error if the value does not pass the checks.

WHEN TO USE IT:

While sanitization *fixes* data so it becomes usable, validation halts the operation and forces the client to handle the issue. Let's talk about dates again. If you expect a date, but a client provides "Stardate 12:90", then a validation rule rejects the input and presents an error (at least in 2016 it does).

Hydrate

What it does:

Replace a token or machine id with an object (ie. event id of '213' becomes an event object of `{ title: 'Radiohead Concert', 'url':'http://...', venue: '...', 'id': 213 }

When to use it:

Unlike Sanitization and Validation, which operate on *incoming* data, *Hydration* focuses on output. Hydration allows you to control the level of detail in your API response.

Say your service provides a calendar of events. By employing hydration, you can handle a request for a days events with two different levels of detail:

GET /events?date=2016-25-12
{
    "status": "success",
    "date": "2015-25-12",
    "events": [
        {"id" : 213 },
        {"id" : 410 },
        {"id" : 9091 }
  ]
}

Here we have a non-hydrated response that has a small payload and small overhead.

GET /events?date=2016-25-12&fields=title,venue,city 
{
    "status": "success",
  "date": "2015-25-12",
  "events":
        [{
            "id": 213,
            "title": "Radiohead Concert",
            "venue": "BOK Center",
            "city":  "Tulsa, OK"
        },
        { 
        ...
        }]
}

But by accepting the common convention of a fields parameter to determine what fields are being requested, we can provide a much more detailed response – only when requested.

Think of hydration as a way to control the amount of data you share (or in bad cases, leak) with clients until they request it. It handles a common issues with REST APIs where output is either too verbose, or too terse (one new solution proposed to address this is GraphQL).

By defining and keeping up with your API hygiene, you'll keep your data healthy, robust and free from surprises.