asyncapi / asyncapi/spec

[spec] AsyncAPI 3.0: Should `OperationObject` be related with a combination of `ChannelObject` & `ServersObject`(s)?

Open
#1,165 6 comments 0 reactions 0 assignees View on GitHub
❔ Question stale
Dominant language
JavaScript
Stars
5.3k
Forks
382
Avg merge
7m
Merged PRs (30d)
4

Description

Hi Team,

I have a question on the Spec. I see that the channels have a relation to the server using the `servers` attribute in the [ChannelObject](https://www.asyncapi.com/docs/reference/specification/v3.0.0#channelObject). This is straightforward and makes sense.

I was wondering whether it also makes sense to have an operations related to servers as well (probably something similar to how channels are related in the ChannelObject as mentioned above). Below is the scenario based on which this question comes to my mind.

## Scenario

I have a kafka based scenario which i need to represent/design using the asyncAPI spec. The `servers` are known based on the available environments (e.g. `dev`, `sit`, `uat`, `prod`). The `channels` are also identified to be available (lets say) on all `servers`. All straightforward as per the spec documentation til now.

> i.e. if we assume the example to be for a single channel
>
> **servers**: `dev`, `sit`, `uat`, `prod`
> **channels**: `example.topic`

Assume I have a client who is onboarding to the channel, but as the clients need to phase out in an orderly and phased manner, clients are available in the `dev` -> `sit` -> `uat` -> `prod`, in that order based on controlled release. In such cases, shouldn't the asyncAPI provide mechanism to design `operations` to also represent on which `channel` & `server` **combination** it is available at any given point in time?

> i.e. if we assume the example to be for a single operation
>
> **servers**: `dev`, `sit`, `uat`, `prod`
> **channels**: `example.topic`
> **operations**: `readExampleTopic` (where `operations..channel`:

## Effects

The scenario above would in general make the asyncAPI contract, invalid/inconsistent for the developer experience, as the contract would represent that a given operation is available on the channel on **ALL** servers, whereas it might just be available on (lets say for example) `dev` & `sit` at a given moment.

Contributor guide

Open the contributing guide

Research direction

Start by reading the AsyncAPI 3.0 ChannelObject and OperationObject sections referenced in the issue, then compare how each currently relates to servers. Review the six comments for a decision; done means the specification clearly settles whether channel-and-server combinations can scope operations and documents the resulting behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
kafka
Domain
api
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
28/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.