What is a not well-defined interface?

Question

I keep reading about "well defined interfaces", as here, here or here, specially when talking about microservices.

What's an example of the opposite, an interface that is not well-defined?

Answer 1

Any interface definition that isn't specific enough to determine whether a client or service implementation conforms to it is not well-defined. Some examples:

• unspecified character encoding (one side using utf-8 while the other uses iso8859-1)
• unspecified number representation (decimal point versus comma)
• implicit sequencing requirements (need to call createFooList before you can call addFoo)
• incomplete specification of limits, constraints, semantic rules etc.

In general, if developers argue about the correct usage or implementation of an interface it's a good indicator that the interface is ill-defined (or that the developers didn't understand it, which also happens.)

Just being awkward or difficult to use doesn't make an interface ill-defined, though.