Personal API Experience

Personal API Experience

Daily musings

Sharing my day to day lessons, ideas and contemplations of architecting, developing and maintaining services (API) in the global marketplace we call the internet.

DDD – what isle is your attribute in?

APIPosted by Craig Hughes Wed, January 09, 2019 18:41:59

During a Domain Driven Design (DDD) workshop this week, one of my colleagues very cleverly used grocery store aisles as an analogy to explain why attributes should be grouped into entities. He explained that grocery stores group logical produce together to make it easier for customers to find what they are looking for. Thereby suggesting that grouping attributes together in entities would help API consumers find relevant data. I really liked this analogy since it highlights some of the challenges of Domain Driven Design.

Have a look next time you go to your local grocery store. The teas, coffees and other hot drinks will be in one aisle. Condiments may be in another, so too will dry goods. Each isle can be seen as a group of items that logically go together. But, and there is always the exception, there are some items that don’t clearly fit into one category; like sugar for example. Should sugar be with the hot drinks, the dry goods or the baking goods? The stores around me can’t seem to agree, but at least they’ve each made a decision and mostly keep to it. As regular shoppers, we begin to know where to find our favorite items and understand the store's layout.

DDD can be a very time-consuming and on-going exercise. Not everyone is going to agree with the models you define, but you can’t go on ad infinitum. Eventually, at some point, you have to make a decision. That decision will be based on the best available knowledge your team has at that point in time. Yes, it may not be 100% right, but it is a decision none-the-less.

Many of these decisions will be around which entities attributes logically belong to. Once all the decisions have been made, you are going to publish your model as an API. Consumers may initially be confused by the placement of one or more attributes and will either accept or challenge them.

Being challenged on a model is not a big deal. The beauty of APIs is that they can be versioned. This allows us a little flexibility in making a decision on our models. A change to the model (that breaks the current contract of your API) can be published as a new API version. That’s not to say we are free to change the model whenever the whim takes us, but, we don’t have to wait for the absolutely perfect model before releasing our APIs. We can start with a minimum viable product (MVP) and evolve it as our knowledge and experience in the domain grows.

The alternative is, of course, to not model your domain at all, and simply publish an API with a long list of root attributes. Imagine trying to shop in a store that randomly puts stuff on shelves without any thought…

Photo by from Pexels

  • Comments(0)

Fill in only if you are not real

The following XHTML tags are allowed: <b>, <br/>, <em>, <i>, <strong>, <u>. CSS styles and Javascript are not permitted.