[FEATURE REQUEST] Normalize topics using URL format

fmvilas commented 5 years ago

Is your feature request related to a problem? Please describe.

Different brokers have different topic separators. AQMP uses dots, MQTT uses slashes, and Kafka doesn't have separators. Since we support topic parameters, we have to standardize what's the character that separates topic chunks. Also, things are confusing when you have to concat baseTopic and a topic. So far, we've been using a dot, but it makes it harder to parse topics. By having topics as URL paths, we make it easier for tooling to parse them, and could even get rid of the events section of the spec, because it will be the same as putting the operations under the /. It will also align things with OpenAPI paths.

Can't it be tackled using specification extensions?

No.

Describe the solution you'd like

At a glance, the solution would look like the following document:

topics:
  /user/updated:
    ...
  user/updated: # Different from the one above (notice the absence of slash in the beginning of the topic)
    ...  
  user/{id}/updated: # Example with a topic parameter
    ...

New topic format would comply with URI templates RFC 6570.

It's now the duty of a specific protocol mapping to define how this URL translates to the underlying protocol's topic naming convention.

Protocol mapping examples (please take them as just examples):

AMQP

user/updated ➡️ user.updated /user/updated ➡️ .user.updated user/{id}/updated ➡️ user.*.updated /user/{id}/updated ➡️ .user.*.updated

Not sure a topic starting with a period is possible in AMQP. In any case, that's AMQP protocol mapping duty to define it.

Kafka

user/updated ➡️ user/updated /user/updated ➡️ /user/updated user/{id}/updated ➡️ (not supported) /user/{id}/updated ➡️ (not supported)

Describe alternatives you've considered

I've considered concatenating baseTopic and topics without any separator in the middle. I also considered making the separator configurable.

fmvilas commented 5 years ago

Updated issue description:

At a glance, the solution would look like the following document:

topics:
  /user/updated:
    ...
  user/updated: # Different from the one above (notice the absence of slash in the beginning of the topic)
    ...  
  user/{id}/updated: # Example with a topic parameter
    ...

New topic format would comply with URI templates RFC 6570.

It's now the duty of a specific protocol mapping to define how this URL translates to the underlying protocol's topic naming convention.

Protocol mapping examples (please take them as just examples):

AMQP

user/updated ➡️ user.updated /user/updated ➡️ .user.updated user/{id}/updated ➡️ user.*.updated /user/{id}/updated ➡️ .user.*.updated

Not sure a topic starting with a period is possible in AMQP. In any case, that's AMQP protocol mapping duty to define it.

Kafka

user/updated ➡️ user/updated /user/updated ➡️ /user/updated user/{id}/updated ➡️ (not supported) /user/{id}/updated ➡️ (not supported)

fmvilas commented 5 years ago

Starting work.

asyncapi-bot commented 3 years ago

:tada: This issue has been resolved in version 1.0.0 :tada:

The release is available on GitHub release

Your semantic-release bot :package::rocket:

asyncapi / spec