Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: re-add Servers tutorial and change code snippet #2275

Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 56 additions & 0 deletions pages/docs/tutorials/getting-started/servers.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
---
title: "Servers"
date: 2019-04-03T10:56:52+01:00
menu:
docs:
parent: 'getting-started'
weight: 110
---

In the previous lesson, you learned how to create the definition of a simple [Hello World application](/docs/getting-started/hello-world). Let's take it from there.

In this tutorial, you'll learn how to add `servers` to your AsyncAPI document. Adding and defining servers is useful because it specifies where and how to connect. The connection facilitates where to send and receive messages.

<CodeBlock highlightedLines={[6,7,8,9,10]}>
{`asyncapi: 3.0.0
info:
title: Hello world application
version: '0.1.0'
servers:
production:
host: broker.mycompany.com
protocol: amqp
description: This is "My Company" broker.
channels:
hello:
address: 'hello'
messages:
sayHelloMessage:
payload:
type: string
pattern: '^hello .+$'
operations:
receiveHello:
action: 'receive'
channel:
$ref: '#/channels/hello'`}
</CodeBlock>

You've now added a new section called `servers` in your AsyncAPI document.

You might have noticed that our example mentions `amqp`, a very common protocol that was popularized by RabbitMQ (among others). While our example uses `amqp`, you can use any protocol. The most common protocols used are `mqtt` (widely adopted by the Internet of Things and mobile apps), `kafka` (popular for its streaming solution), `ws` (WebSockets are frequently used in browsers), and `http` (used in HTTP streaming APIs).

<Remember>

The `servers` section defines where your application should connect to start sending and receiving messages.

1. If you are using a broker-centric architecture such as Kafka or RabbitMQ, specify the broker URL.
2. If you have the classic client-server model such as for REST APIs, then your `server` should be the URL of the server.

</Remember>

## Conclusion

Now you know where the `Hello world application` connects to, and you can start receiving `hello {name}` messages.

In the next section, you'll learn how to add security requirements to your server.