How to build APIs with the right abstraction: SOAP, REST, ODATA

Leaky abstractions can be bad, especially in the context of APIs we expose to the world. Here are some thoughts on how to be less leaky and achieve more self-service with the APIs you build

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

Leave a Comment

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

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

Facebook photo

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

Connecting to %s