posts/well_designed_code_is_easy_to_delete

[Lewiscowles1986]

I mostly wanted to avoid utterances app, and see if this appears on the blog. But also, nice article.

What are some things you think can help with ensuring code can be deleted, replaced outside of OpenAPI?

I Really like queueing technologies for this, because I can leave publishing as-is, and setup new consumers without loss of data. That can be as simple as any queue service buffering between services, or with persistent / durable queues such as EventStore or Kinesis with DataStreams, you can move a read head for a consumer, and add a new consumer at the very first message / event.

https://blacksheepcode.com/posts/well_designed_code_is_easy_to_delete

[dwjohnston]

I mostly wanted to avoid utterances app, and see if this appears on the blog. But also, nice article.

So you manually created an issue with this title? Is not showing up so far.

What are some things you think can help with ensuring code can be deleted, replaced outside of OpenAPI?

Well, the gyst is that for any clear interface, whether that's a REST API, or it could be a package, or a module, or a class, the old implementation can be nuked wholesale, and replaced.

But, this assumes that you can write perfect interfaces first time.

There's a problem when you try to change the interfaces, and this is a good topic for another blog post, there's an insidious dynamic that causes the undesirable interfaces to live on long after the reason for them existing has gone away.

For example, say you had an interface for an auth service like:

GET /auth 

{
    // There's some legacy reason this was necessary at the time it was designed
    someUglyThing: string; 
}

And this auth service had five (or 500) different consumers now to coming to rely on this ugly interface.

Now we want to move on from this interface.

The problem is, we have five (or 500) consumers expecting the old ugly interface.

Now we could do a 'we'll deprecate it, run the new version and the old version simultaneously, and after a year when turn the old version off', but there's two effects here:

1. 'Running the two versions simultaneously' - could lead to the old interface seeping into your new design. For example, maybe you end up adding 'someUglyThing' to a database table in your new implementation, just as a temporary measure to support the old implementation, but something comes to rely on it... and now even though you've turned off the old implementation, that old field is still hanging around.
2. Probably what's going to happen is that some or many of the consumers will end up creating a wrapper to convert the new interface back to the old one. And then be continuing to pass that old interface downstream anyway.

But I guess that's point - when you were doing this work to change an interface, both the designers of the new service, and its consumers should be thinking 'how do we make this adapter easy to delete?'.

[Lewiscowles1986]

I think the reason it is not showing up is a missing tag. There is another issue without the label and that is also not showing up

[Lewiscowles1986]

In terms of the interface migration pattern; I too like stable systems; where we dont needlessly break consumers regularly. How regular is classified as regularly; I'd be willing to hear arguments for.

While I'm sure there are hard and fast rules for this sort of thing. I think expanding the API perimeter, and monitoring would be two no-regrets activities to allow keeping the old (for now); whilst also providing the new take on how something should be designed. I'd then consider most of the challenge to be how to communicate that; for which the easy option might be to stop communicating the old endpoint, or to mark as deprecated.