Leak Less of your Enterprise in your API: Interface Design Tips


Modern software is built over the network with systems hooked-up either privately within the internal enterprise eco-system or with a trusted partner or via a public channel

Traditional system integration (ESB) engineers working within project directives would have delivered interfaces for system to system or partner to system integration while working closely with the consuming teams

This would have created, despite our best effort, very “leaky abstraction” of the provider system’s service implementation in the form of internal ids, system namespaces, validation logic etc in our API to the consumer

Impact of a leaky abstraction

APIs are a means to decouple the implementation by providing a good abstraction (we can never have a perfect abstraction) and our past experience with system integration has show that thinking only in a single context (EAI) in a project sense leads to a leaky abstraction (and tight coupling agnostic of technology used). Thus not reasoning for all contexts early on and thinking of your APIs as Products for Digital, B2B etc can lead to an improper abstraction

Impact of a leaky abstraction are

– Tighter coupling between service provider and consumer:

– Security: Attacker can guess internal implementation and launch a data hack by manipulating requests which would look valid to the server

Where should we focus?

– Service naming: API URI leaks something about the system serving it and not about the domain product, its business context and resource

– Resource Identifier: Does your Create Object return an internal database row ID?

– Date Time: Internal server datetime representation vs a standard causing usual datetime issues and logic to be implemented by consumers to handle your server issues

– Language implementation details in data: Ever see a java.util.List come back in a payload?

– Server headers: HTTP response headers from internal server often do not get the full treatment. We either skip them or block them all. When sending back backend server headers, try to reason why it is necessary or obsfucate (hash) so that someone cannot guess a sequence etc

Published by

techiecook

I apply my degree in computing with my experience in building networked software to create products that people will love. More about me here https://techiecook.com/about/

Leave a Comment

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s