docs: add AsyncAPI definition #9
Conversation
| pattern: '^[A-Za-z0-9+/=]*$' | ||
| required: | ||
| - payment | ||
| - stake |
There was a problem hiding this comment.
Shouldn't stake be optional to support enterprise addresses?
There was a problem hiding this comment.
@iccicci stake can be an empty array even if the field is required.
I see no problem making it optional or keeping it mandatory like this.
| $ref: '#/components/schemas/pointPayload' | ||
| required: | ||
| - point | ||
| protocolParameterPayload: |
There was a problem hiding this comment.
One of the goals of this API is for it to be stable over protocol upgrades where transaction contents and protocol params can change.
This current approach establishes a strong contract with the server that's specific to a particular Cardano era. We would either need to create era types or just consider serializing the protocol parameters and pass a blob to the client, similar to how we're not concerned with transaction contents. I'm leaning towards the latter since the former does not address the goals mentioned above.
There was a problem hiding this comment.
I don't have a clear winner here. I am not so sure using a blob makes it more 'stable'.
If we use a blob, the API will remain the same over time. However, declaring the details will maintain the contract created by the API between the client and the server.
If not declared, once a new era arrives, the server and the client will try to implement something not defined in the API specs. They should go and inspect the blockchain implementation and figure out the details.
Taking long-term responsibility for maintaining the client-server contract is a strategic decision.
If it is documented well, using a blob will lower the maintenance costs and keep the development cost the same.
For me, the winner is 'a blob' by a nose.
There was a problem hiding this comment.
Taking inspiration from https://ogmios.dev/api/. I think we should also avoid mentioning Cardano specifically when it's not required and there's also currently no hosted instances.
| url: 'https://www.apache.org/licenses/LICENSE-2.0' | ||
| defaultContentType: application/json | ||
| servers: | ||
| cardano-mainnet: |
There was a problem hiding this comment.
| cardano-mainnet: | |
| 127.0.0.1:{port} |
There was a problem hiding this comment.
Since this is like a name, I changed it to local-server 8dca51e
| cardano-mainnet: | ||
| host: 'localhost:8080' | ||
| protocol: wss | ||
| description: Cardano Mainnet API |
There was a problem hiding this comment.
| description: Cardano Mainnet API | |
| description: Default instance, when running a local server. |
| defaultContentType: application/json | ||
| servers: | ||
| cardano-mainnet: | ||
| host: 'localhost:8080' |
There was a problem hiding this comment.
| host: 'localhost:8080' | |
| host: '127.0.0.1:{port}' |
| description: This environment is for Cardano mainnet production | ||
| - name: 'visibility:public' | ||
| description: This resource is public to all users | ||
| cardano-preprod: |
The AsyncAPI definition file, based on the CIP details.
You can copy and paste the file content into
https://studio.asyncapi.com/for a visual rendering.The definition uses one channel per blockchain, but this can be easily changed, and every blockchain can be combined into one channel.
For WS, one channel is one connection.
To-dos: