One of the fundamentals of programming is defining interfaces, or contracts between parts of systems. Interfaces create layers of abstraction and allow scaling code beyond the complexity a single person can hold in their head. They appear at the level of function signatures, to dependency signatures, up to service-to-service network calls.
There are almost always grey areas within an individual interface; areas where behavior isn’t explicitly defined. This causes a couple problems. Interpretations of behavior can differ between people or over time, leading to subtle bugs due to drifting behavior in different modules. It also requires overhead and more error handling in each consumer, as you’ll see below.
In a strongly typed language there are some not-immediately-obvious techniques to reduce this ambiguity and create a more intuitive design.
I’ll provide code examples throughout this post, available in several different languages.
The basics: Comments
As the author, the easiest way to avoid ambiguity is through documenting your code.
interface Foo {
type: string; // describes how foo should be represented
}
interface Bar {
discount?: number;
discountApplied?: boolean; // indicates if `discount` is possible, or actually applied, not present if no discount
}
data class Foo(
val type: String // describes how foo should be represented
)
data class Bar(
val discount: String?,
val discountApplied: Boolean? // indicates if `discount` is possible, or actually applied, not present if no discount
)
type Foo struct {
Type string // describes how foo should be represented
}
type Bar struct {
Discount *string
DiscountApplied *bool // indicates if `discount` is possible, or actually applied, not present if no discount
}
components:
schemas:
Foo:
type: object
properties:
type:
type: string
description: describes how foo should be represented
Bar:
type: object
properties:
discount:
type: string
nullable: true
discountApplied:
type: boolean
nullable: true
description: indicates if `discount` is possible, or actually applied, not present if no discount
This helps, but couples you to additional tooling within your editor to expose without reading the source. Comments don’t protect against human issues, such as misinterpretation or plain laziness, and conformance can’t automatically be verified by build tooling.
Taking advantage of typing
Enums
A simple pattern is to use enumeration values. Explicit enumerations can reduce the need for inline error handling and allows for self-documentation through good naming. This sounds simple, but I see people forget about enums often. The key question to ask is:
Do I care about how the consumer uses this value?
If the answer is yes, a string type doesn’t capture the correct nuance.
Before
interface Foo {
type: string;
}
function convertFooTypeToX(x: Foo): string {
switch (x.type) {
case "a":
return "1";
case "b":
return "2";
case "c":
return "3";
default:
throw new Error(`unknown type: ${x.type}`);
}
}
After
enum FooType {
a = "a",
b = "b",
c = "c"
}
interface Foo {
type: FooType;
}
function convertFooTypeToX(x: Foo): string {
switch (x.type) {
case FooType.a:
return "1";
case FooType.b:
return "2";
case FooType.c:
return "3";
// no default is required to satisfy type checking
}
}
Before
data class Foo(
var type: String
)
fun convertFooTypeToX(x: Foo): String = when (x.type) {
"a" -> "1"
"b" -> "2"
"c" -> "3"
else -> throw Exception("unknown type: ${x.type}")
}
After
enum class FooType {
a,
b,
c,
}
data class Foo(
val type: FooType
)
fun convertFooTypeToX(x: Foo): String = when (x.type) {
FooType.a -> "1"
FooType.b -> "2"
FooType.c -> "3"
// no else is required to satisfy type checking
}
Before
type Foo struct {
Type string
}
func ConvertFooTypeToX(x Foo) string {
switch x.Type {
case "a":
return "1"
case "b":
return "2"
case "c":
return "3"
}
panic(fmt.Sprintf("unknown type: %s", x.Type))
}
After
type FooType string
const (
FooTypeA FooType = "a"
FooTypeB = "b"
FooTypeC = "c"
)
type Foo struct {
Type FooType
}
func ConvertFooTypeToX(x Foo) string {
switch x.Type {
case FooTypeA:
return "1"
case FooTypeB:
return "2"
case FooTypeC:
return "3"
}
// unfortunately, without real enums in go, we still need this
panic(fmt.Sprintf("unknown type: %s", x.Type))
}
Before
components:
schemas:
Foo:
schema:
type: string
After
components:
schemas:
Foo:
schema:
type: string
enum: [a, b, c]
String formats
Enums work well, but only work for explicit sets of values—they can’t be applied if I don’t know the full set of values. If I do know, adding anything new breaks backwards compatibility.
To get around this, I can use a type alias to provide more semantic information.
type HtmlType = string;
typealias HtmlType = String
type HtmlType string
components:
schemas:
Foo:
schema:
type: string
format: html
There’s a loophole: The consumer could create their own string and pass it in place of HtmlType. Depending on the serialization library and language, it can be possible to discourage this with custom deserialization of a non-constructable type.
type HtmlType = string & { __t: "html_type" }
function read(response: Response): HtmlType {
return response.body as HtmlType;
}
class HtmlTypeDeserializer extends JsonDeserializer<HtmlType> {
@Override
fun deserialize(JsonParser jp, DeserializationContext ctx) throws IOException, JsonProcessingException {
// read contents of jp...
return HtmlType(content)
}
}
@JsonDeserialize(using = HtmlTypeDeserializer::class)
class HtmlType private constructor(private val content: String)
// no example in this language
# no example in this language
In the real world, it’s risky to migrate to a format from an existing enumeration. There’s often logic in the client that depends on knowledge of a specific value, and all that logic needs to be transformed into an api driven model. It’s tempting to keep it in the client, but that makes removal of the value not-backwards compatible and undocumented.
Nested nullables
A common pattern I see when designing api responses is to use a flat structure like the following.
interface Workout {
swim_id: string | null;
swim_miles: number | null;
swim_time: Time | null;
bike_id: string | null;
bike_miles: number | null;
bike_time: Time | null;
run_id: string | null;
run_miles: number | null;
run_time: Time | null;
}
import kotlin.time.Duration;
data class Workout(
var swim_id: String?,
var swim_miles: String?,
var swim_time: Duration?,
var bike_id: String?,
var bike_miles: Double?,
var bike_time: Duration?,
var run_id: String?,
var run_miles: Double?,
var run_time: Duration?
)
type Workout struct {
SwimID *string
SwimMiles *float64
SwimTime *time.Duration
BikeID *string
BikeMiles *float64
BikeTime *time.Duration
RunID *string
RunMiles *float64
RunTime *time.Duration
}
components:
schemas:
Workout:
type: object
properties:
swim_id:
type: string
nullable: true
swim_miles:
type: number
nullable: true
swim_time:
type: number
nullable: true
bike_id:
type: string
nullable: true
bike_miles:
type: number
nullable: true
bike_time:
type: number
nullable: true
run_id:
type: string
nullable: true
run_miles:
type: number
nullable: true
run_time:
type: number
nullable: true
This leads to open questions: What happens a mix of id, miles, and time is present? Should I always expect miles to be present if id is present? How does time relate to miles?
By breaking up the flat structure these can be answered.
Here, it’s clear that an id is always paired with miles and time, and each type of activity might be missing:
interface Segment {
id: string;
miles: number;
time: Time;
}
interface Workout {
swim: Segment | null;
bike: Segment | null;
run: Segment | null;
}
import kotlin.time.Duration;
data class Segment(
val id: String,
val miles: Double,
val time: Duration
)
data class Workout(
var swim: Segment?,
var bike: Segment?,
var run: Segment?
)
type Segment struct {
ID string
Miles float64
Time time.Duration
}
type Workout struct {
Swim *Segment
Bike *Segment
Run *Segment
}
components:
schemas:
Segment:
type: object
properties:
id:
type: string
miles:
type: number
time:
type: number
Workout:
type: object
properties:
swim:
$ref: "#/components/schemas/Segment"
nullable: true
bike:
$ref: "#/components/schemas/Segment"
nullable: true
run:
$ref: "#/components/schemas/Segment"
nullable: true
With this alternate structure, I can see that the other fields might be missing:
interface Segment {
id: string;
miles: number | null;
time: Time | null;
}
interface Workout {
swim: Segment | null;
bike: Segment | null;
run: Segment | null;
}
import kotlin.time.Duration;
data class Segment(
val id: String,
val miles: Double?,
val time: Duration?
)
data class Workout(
var swim: Segment?,
var bike: Segment?,
var run: Segment?
)
type Segment struct {
ID string
Miles *float64
Time *time.Duration
}
type Workout struct {
Swim *Segment
Bike *Segment
Run *Segment
}
components:
schemas:
Segment:
type: object
properties:
id:
type: string
miles:
type: number
nullable: true
time:
type: number
nullable: true
Workout:
type: object
properties:
swim:
$ref: "#/components/schemas/Segment"
nullable: true
bike:
$ref: "#/components/schemas/Segment"
nullable: true
run:
$ref: "#/components/schemas/Segment"
nullable: true
And here, I understand that the statistics might be missing, but are tied together:
interface Segment {
id: string;
stats: {
miles: number;
time: Time;
} | null;
}
interface Workout {
swim: Segment | null;
bike: Segment | null;
run: Segment | null;
}
import kotlin.time.Duration;
data class Stats(
val miles: Double,
val time: Duration
)
data class Segment(
val id: String,
val stats: Stats?
)
data class Workout(
var swim: Segment?,
var bike: Segment?,
var run: Segment?
)
type Stats struct {
Miles float64
Time time.Duration
}
type Segment struct {
ID string
Stats *Stats
}
type Workout struct {
Swim *Segment
Bike *Segment
Run *Segment
}
components:
schemas:
Stats:
type: object
properties:
miles:
type: number
time:
type: number
Segment:
type: object
properties:
id:
type: string
stats:
$ref: "#/components/schemas/Stats"
nullable: true
Workout:
type: object
properties:
swim:
$ref: "#/components/schemas/Segment"
nullable: true
bike:
$ref: "#/components/schemas/Segment"
nullable: true
run:
$ref: "#/components/schemas/Segment"
nullable: true
This avoids type asserations and null pointer errors: workout.swim_id!: workout.swim_id!!: panic: runtime error: invalid memory address or nil pointer dereference.
Type unions
Another type structure that can reduce ambiguity is a union type. Union types allow representing “exclusive or” in the interface and avoid locking in an inheritance structure. Kotlin’s sealed classes are a good way to implement these. This is a first class feature in Typescript.
For example, say I want to represent a figure on my site.
interface Figure {
source: string;
attr: string;
height?: number;
width?: number;
}
data class Figure(
val source: String,
val attr: String,
val height: Int?,
val width: Int?
)
type Figure struct {
Source string
Attr string
Height *int
Width *int
}
components:
schemas:
Figure:
type: object
properties:
source:
type: string
attr:
type: string
height:
type: number
nullable: true
width:
type: number
nullable: true
This works, but allows for accidentally distorting the image by specifying a height and width that doesn’t match the aspect ratio. A type union can prevent this.
type Size = {} | { height: number } | { width: number };
interface UnsizedFigure {
source: string;
attr: string;
}
type Figure = UnsizedFigure & Size;
sealed class Figure(
open val source: String,
open val attr: String
)
class UnsizedFigure(
override val source: String,
override val attr: String
): Figure(source, attr)
class HeightSizedFigure(
override val source: String,
override val attr: String,
val height: Int
): Figure(source, attr)
class WidthSizedFigure(
override val source: String,
override val attr: String,
val width: Int
): Figure(source, attr)
type UnsizedFigure struct {
Source string
Attr string
}
type HeightSizedFigure struct {
UnsizedFigure
Height int
}
type WidthSizedFigure struct {
UnsizedFigure
Width int
}
type Figure interface{}
components:
schemas:
UnsizedFigure:
type: object
properties:
source:
type: string
attr:
type: string
Size:
oneOf:
- type: object
properties:
height:
type: number
- type: object
properties:
width:
type: number
SizedFigure:
allOf:
- $ref: "#/components/schemas/UnsizedFigure"
- $ref: "#/components/schemas/Size"
Figure:
oneOf:
- $ref: "#/components/schemas/UnsizedFigure"
- $ref: "#/components/schemas/SizedFigure"
Type unions force explicit checking of which type is used. They’re possible in many languages, but not all.
function isHeightSized(x: Size): x is { height: number } {
return (x as { height?: number }).height != null;
}
function isWidthSized(x: Size): x is { width: number } {
return (x as { width?: number }).width != null;
}
fun eval(figure: Figure): Int = when (figure) {
is UnsizedFigure -> 0
is HeightSizedFigure -> 1
is WidthSizedFigure -> 2
}
func eval(figure Figure) int {
switch t := figure.(type) {
case UnsizedFigure:
return 0
case HeightSizedFigure:
return 1
case WidthSizedFigure:
return 2
default:
panic(fmt.Sprintf("Unknown type: %v", t))
}
}
# See other languages for reference implementations.
In the real world
These techniques can give great build-time safety when applied within a single codebase, but it’s harder to apply that safety across different codebases (e.g. calling an api, or using a typescript dependency in a javascript codebase). Responsibility for conforming to the contract has been absolved from the consumer and has been shifted explicitly to the producer. Since there’s less incentive for explicit protection through validation in client code, errors caused by backwards incompatibility are harder to track down. Documenting changes through the use of techniques like semver make this easy to avoid.
Introducing into an existing system
In a well-established environment it’s sometimes not possible to apply these patterns in the producer; especially when dealing with legacy systems or other teams. In these cases these patterns can be introduced in the middle of the stack, either within a fronting service or a module within the consuming client. This gives an explicit place to add validation and audit that the contract is being followed.
To summarize: Introducing more complexity into your interface; be it a function call, library, or api; makes it harder for consumers to make the wrong assumptions without asking them to think about logic outside of their business domain.