DESCRIBE YOUR DATA

What data consumer may get and what the data means. This is the semantic definition of your application domain.

DESCRIBE WHAT CONSUMER CAN DO WITH THE DATA

What actions your data may afford including any description of action attributes.

IN A WAY BOTH HUMANS AND MACHINES CAN READ

Humans are bad at reading schemas. So are machines at reading a plain text. You want every person and every machine to understand.

Tao of Good API Design

Focus on what matters.

Data is your API. Understanding data and what consumers can do with it is the key to a successful API design, implementation and use.

Yet, over and over we see API documentation focused on technical details. We hear confused stakeholders, missed expectations, and frustrated developers. We rely on untested code, hard-coded understanding that can't be evolved and input that wasn't validated.

All of this can be fixed by focusing on what matters the most—data and affordances.

The first step is to get everyone on the same page about what data is in the system and what they mean. No understanding of data is complete without the description of its affordances. Understanding what consumer can do with data is equally as important as understanding the meaning of data.

Finally, to get much-needed interoperability and automation, both the description of data and its affordances should be readable to machines.(why?)

Questions? Let's talk!

Get in touch