Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

Welcome to Software Development on Codidact!

Will you help us build our independent community of developers helping developers? We're small and trying to grow. We welcome questions about all aspects of software development, from design to code to QA and more. Got questions? Got answers? Got code you'd like someone to review? Please join us.

Post History

66%
+2 −0
Q&A Best practices for business versioning within Web APIs

Context Our team is developing a solution mainly composed of several microservices relying on ASP.NET Core. We have decided that the simplest and most cost-effective solution would be for service...

0 answers  ·  posted 2mo ago by Alexei‭  ·  edited 2mo ago by Alexei‭

#3: Nominated for promotion by user avatar Alexei‭ · 2024-05-03T07:27:25Z (about 1 month ago)
#2: Post edited by user avatar Alexei‭ · 2024-04-22T16:34:47Z (about 2 months ago)
Better title
  • Naming conventions for business versioning within Web APIs
  • Best practices for business versioning within Web APIs
#1: Initial revision by user avatar Alexei‭ · 2024-04-22T16:34:16Z (about 2 months ago)
Naming conventions for business versioning within Web APIs
## Context

Our team is developing a solution mainly composed of several microservices relying on ASP.NET Core.

We have decided that the simplest and most cost-effective solution would be for services to support multiple versions at the same time at pod level (the same application might expose multiple versions at the same time as opposed to running different pods for different versions).

We have also decided to avoid function-level versioning logic (i.e. if statements checking for something related to a specific version), so that it is easy to phase out an older version once no client uses it.

We expect a maximum of three versions at the same time.

While controller-level versioning (API versioning) is covered in numerous articles, I cannot find many details about how to version the underlying services. 

Let's consider a simple example:

- `POST /v1/messages` calls `MessageService` which in turn relies on a validator (`MessageApiModelValidator`) to validate the input
- a `MessageMapper` translates the `MessageApiModel` to `Message` (the EF model) 
- a repository (`MessageRepository`) is called to persist the message

Let's consider a breaking change at the `MessageApiModel` level (e.g. a new mandatory property is added). This means that MessageApiModel, MessageMapper and possibly MessageService will be versioned.

## Option 1 - keep the class names 

We have also aligned to keep the older versions in special folders. The structure would look like this:

```
Messages 
│
├── _versions
├──── v1
├────── Mappers
├──────── MessageMapper.cs
├────── Models
├──────── MessageApiModel.cs
├────── Services
├──────── MessageService.cs
├────── Validators
├──────── MessageApiModelValidator.cs
├── Mappers
├──── MessageMapper.cs
├── Models
├──── MessageApiModel.cs
├── Services
├──── MessageService.cs
├── Validators
├──── MessageApiModelValidator.cs
```

The breaking changes are implemented directly in the "normal" folder structure (outside of the _versions folder) and the older versions include a clone of the existing affected files (only the changes files are cloned).

- the main pro I see is that we keep the class names clean.
- the main con I see is that by having the same class name, one needs to be very careful to reference the correct class. This is especially important due to the auto-import feature of Visual Studio (might pick the wrong version and not realize it).


## Option 2 - apply explicit versioning on class names

In this case the folder structure is almost identical, but all affected class names get the version as a suffix:

```
Messages 
│
├── _versions
├──── v1
├────── Mappers
├──────── MessageMapperV1.cs
├────── Models
├──────── MessageApiModelV1.cs
├────── Services
├──────── MessageServiceV1.cs
├────── Validators
├──────── MessageApiModelValidatorV1.cs
├── Mappers
├──── MessageMapper.cs
├── Models
├──── MessageApiModel.cs
├── Services
├──── MessageService.cs
├── Validators
├──── MessageApiModelValidator.cs
```

The main pro I see is that when working with an instance it is very clear which version is used. Also, there is no need for namespace disambiguation (namespace alias).

The main con I see is that the class names look strange and somewhat redundant (the namespace already includes the version).

Regardless of the option, phasing out a version means removing the folder(s) for that version and fixing a few compilation errors (e.g. service registration).

What are the best practices surrounding business class versioning for breaking changes that affect multiple classes?