Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
221 lines (178 sloc) 14.8 KB
---
---
<!DOCTYPE html>
<html lang="en">
<head>
<title>Introduction — AsyncAPI</title>
<meta charset="utf-8">
<meta name="description" content="Define your Message-Driven APIs">
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
<link rel="alternate" hreflang="x-default" href="https://asyncapi.org/v1/guide/index.html">
<meta property="og:type" content="article">
<meta property="og:title" content="Introduction — AsyncAPI">
<meta property="og:description" content="Define your Message-Driven APIs">
<meta property="og:image" content="https://www.asyncapi.com//images/twitter-card-image.png">
<meta name="twitter:card" content="summary">
<meta name="twitter:title" content="Introduction — AsyncAPI">
<meta name="twitter:description" content="Define your Message-Driven APIs">
<meta name="twitter:image" content="https://www.asyncapi.com/images/twitter-card-image.png">
<link rel="icon" href="/images/favicon.png" type="image/png">
<link href='//fonts.googleapis.com/css?family=Source+Sans+Pro:300,400,600|Roboto Mono' rel='stylesheet' type='text/css'>
<link href='//fonts.googleapis.com/css?family=Dosis:500' rel='stylesheet' type='text/css'>
<link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" rel="stylesheet" type="text/css">
<!-- main page styles -->
<link rel="stylesheet" href="/css/page.css">
<!-- this needs to be loaded before guide's inline scripts -->
<script>window.PAGE_TYPE = "guide"</script>
<!-- ga -->
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-109278936-1', 'www.asyncapi.com');
ga('send', 'pageview');
</script>
</head>
<body class="docs"> <div id="mobile-bar" >
<a class="menu-button"></a>
<a class="logo" href="/"></a>
</div>
<div id="header">
<a id="logo" href="/">
<img src="/images/logo.png">
<span>AsyncAPI</span>
</a>
<ul id="nav">
<li class="nav-dropdown-container learn">
<a class="nav-link current">
Learn
<span class="arrow"></span>
</a>
<ul class="nav-dropdown">
<li><ul>
<li><a href="/v1/guide/" class="nav-link current">Guide</a></li>
<li><a href="/v1/tutorial/" class="nav-link">Tutorial</a></li>
<li><a href="/v1/spec.html" class="nav-link">The specification</a></li>
</ul></li>
</ul>
</li>
<li class="nav-dropdown-container ecosystem">
<a class="nav-link">Ecosystem</a><span class="arrow"></span>
<ul class="nav-dropdown">
<li><h4>Help</h4></li>
<li><ul>
<li><a href="https://github.com/asyncapi/asyncapi " class="nav-link" target="_blank">Github repo</a></li>
<li><a href="https://async-apis-slack.herokuapp.com/ " class="nav-link" target="_blank">Slack channel</a></li>
</ul></li>
<li><h4>Tooling</h4></li>
<li>
<ul>
<li><a href="http://editor.asyncapi.org" class="nav-link" target="_blank">Online editor</a></li>
<li><a href="/v1/tooling/docgens.html" class="nav-link ">Documentation generators</a></li>
<li><a href="/v1/tooling/codegens.html" class="nav-link ">Code generators</a></li>
</ul>
</li>
<li><h4>News</h4></li>
<li><ul>
<li><a href="https://twitter.com/search?q=asyncapi" class="nav-link" target="_blank">Twitter</a></li>
<li><a href="https://medium.com/asyncapi" class="nav-link" target="_blank">Blog</a></li>
</ul></li>
<li><h4>Spread the word</h4></li>
<li><ul>
<li><a href="https://twitter.com/intent/tweet?url=https%3A%2F%2Fwww.asyncapi.org&via=fmvilas&text=Check%20out%20%23AsyncAPI.%20Worth%20having%20a%20look%21&hashtags=api%2Cmicroservices%2Ctech%2Ccode" class="nav-link" target="_blank">Tweet about it</a></li>
</ul></li>
</ul>
</li>
<li>
<a href="/about.html" class="nav-link about">About</a>
</li>
</ul>
</div>
<div id="main" class="fix-sidebar">
<div class="sidebar">
<div class="sidebar-inner">
<ul class="main-menu">
<li class="nav-dropdown-container learn">
<a class="nav-link current">
Learn
<span class="arrow"></span>
</a>
<ul class="nav-dropdown">
<li><ul>
<li><a href="/v1/guide/" class="nav-link current">Guide</a></li>
<li><a href="/v1/tutorial/" class="nav-link">Tutorial</a></li>
<li><a href="/v1/spec.html" class="nav-link">The specification</a></li>
</ul></li>
</ul>
</li>
<li class="nav-dropdown-container ecosystem">
<a class="nav-link">Ecosystem</a><span class="arrow"></span>
<ul class="nav-dropdown">
<li><h4>Help</h4></li>
<li><ul>
<li><a href="https://github.com/asyncapi/asyncapi " class="nav-link" target="_blank">Github repo</a></li>
<li><a href="https://async-apis-slack.herokuapp.com/ " class="nav-link" target="_blank">Slack channel</a></li>
</ul></li>
<li><h4>Tooling</h4></li>
<li>
<ul>
<li><a href="http://editor.asyncapi.org" class="nav-link" target="_blank">Online editor</a></li>
<li><a href="/v1/tooling/docgens.html" class="nav-link ">Documentation generators</a></li>
<li><a href="/v1/tooling/codegens.html" class="nav-link ">Code generators</a></li>
</ul>
</li>
<li><h4>News</h4></li>
<li><ul>
<li><a href="https://twitter.com/search?q=asyncapi" class="nav-link" target="_blank">Twitter</a></li>
<li><a href="https://medium.com/asyncapi" class="nav-link" target="_blank">Blog</a></li>
</ul></li>
<li><h4>Spread the word</h4></li>
<li><ul>
<li><a href="https://twitter.com/intent/tweet?url=https%3A%2F%2Fwww.asyncapi.org&via=fmvilas&text=Check%20out%20%23AsyncAPI.%20Worth%20having%20a%20look%21&hashtags=api%2Cmicroservices%2Ctech%2Ccode" class="nav-link" target="_blank">Tweet about it</a></li>
</ul></li>
</ul>
</li>
<li>
<a href="/about.html" class="nav-link about">About</a>
</li>
</ul>
<div class="list">
<ul class="menu-root">
<li>
<a href="/v1/guide/index.html" class="sidebar-link current">Introduction</a>
</li>
</ul>
</div>
</div>
</div>
<div class="content guide with-sidebar index-guide">
<h1>Introduction</h1>
<p>AsyncAPI provides a specification that allows you to define Message-Driven APIs in a machine-readable format. It’s protocol-agnostic, so you can use it for APIs that work over MQTT, AMQP, WebSockets, STOMP, etc. The spec is very similar to <a href="https://github.com/OAI/OpenAPI-Specification" target="_blank" rel="external">OpenAPI/Swagger</a> so, if you’re familiar with them, AsyncAPI should be easy for you.</p>
<h2 id="A-basic-example"><a href="#A-basic-example" class="headerlink" title="A basic example"></a>A basic example</h2><p>The following example describes a very simple streetlights service. It describes a service you can connect at <code>api.streetlights.smartylighting.com</code> (port 1883 or 8883) and allows you to publish information about environmental lighting conditions.</p>
<figure class="highlight yaml"><table><tr><td class="code"><pre><div class="line"><span class="attr">asyncapi:</span> <span class="string">'1.0.0'</span></div><div class="line"><span class="attr">info:</span></div><div class="line"><span class="attr"> title:</span> <span class="string">Streetlights</span> <span class="string">API</span></div><div class="line"><span class="attr"> version:</span> <span class="string">'1.0'</span></div><div class="line"><span class="attr"> description:</span> <span class="string">|</span></div><div class="line"><span class="string"> The Smartylighting Streetlights API allows you</span></div><div class="line"><span class="string"> to remotely manage the city lights.</span></div><div class="line"><span class="string"></span><span class="attr"> license:</span></div><div class="line"><span class="attr"> name:</span> <span class="string">Apache</span> <span class="number">2.0</span></div><div class="line"><span class="attr"> url:</span> <span class="string">'https://www.apache.org/licenses/LICENSE-2.0'</span></div><div class="line"><span class="attr">baseTopic:</span> <span class="string">smartylighting.streetlights.1.0</span></div><div class="line"></div><div class="line"><span class="attr">servers:</span></div><div class="line"><span class="attr"> - url:</span> <span class="string">api.streetlights.smartylighting.com:&#123;port&#125;</span></div><div class="line"><span class="attr"> scheme:</span> <span class="string">mqtt</span></div><div class="line"><span class="attr"> description:</span> <span class="string">Test</span> <span class="string">broker</span></div><div class="line"><span class="attr"> variables:</span></div><div class="line"><span class="attr"> port:</span></div><div class="line"><span class="attr"> description:</span> <span class="string">Secure</span> <span class="string">connection</span> <span class="string">(TLS)</span> <span class="string">is</span> <span class="string">available</span> <span class="string">through</span> <span class="string">port</span> <span class="number">8883.</span></div><div class="line"><span class="attr"> default:</span> <span class="string">'1883'</span></div><div class="line"><span class="attr"> enum:</span></div><div class="line"><span class="bullet"> -</span> <span class="string">'1883'</span></div><div class="line"><span class="bullet"> -</span> <span class="string">'8883'</span></div><div class="line"></div><div class="line"><span class="attr">topics:</span></div><div class="line"> <span class="string">event.&#123;streetlightId&#125;.lighting.measured:</span></div><div class="line"><span class="attr"> publish:</span></div><div class="line"> <span class="string">$ref:</span> <span class="string">'#/components/messages/lightMeasured'</span></div><div class="line"></div><div class="line"><span class="attr">components:</span></div><div class="line"><span class="attr"> messages:</span></div><div class="line"><span class="attr"> lightMeasured:</span></div><div class="line"><span class="attr"> summary:</span> <span class="string">Inform</span> <span class="string">about</span> <span class="string">environmental</span> <span class="string">lighting</span> <span class="string">conditions</span> <span class="string">for</span> <span class="string">a</span> <span class="string">particular</span> <span class="string">streetlight.</span></div><div class="line"><span class="attr"> payload:</span></div><div class="line"><span class="attr"> type:</span> <span class="string">object</span></div><div class="line"><span class="attr"> properties:</span></div><div class="line"><span class="attr"> lumens:</span></div><div class="line"><span class="attr"> type:</span> <span class="string">integer</span></div><div class="line"><span class="attr"> minimum:</span> <span class="number">0</span></div><div class="line"><span class="attr"> description:</span> <span class="string">Light</span> <span class="string">intensity</span> <span class="string">measured</span> <span class="string">in</span> <span class="string">lumens.</span></div><div class="line"><span class="attr"> sentAt:</span></div><div class="line"> <span class="string">$ref:</span> <span class="string">"#/components/schemas/sentAt"</span></div><div class="line"></div><div class="line"><span class="attr"> schemas:</span></div><div class="line"><span class="attr"> sentAt:</span></div><div class="line"><span class="attr"> type:</span> <span class="string">string</span></div><div class="line"><span class="attr"> format:</span> <span class="string">date-time</span></div><div class="line"><span class="attr"> description:</span> <span class="string">Date</span> <span class="string">and</span> <span class="string">time</span> <span class="string">when</span> <span class="string">the</span> <span class="string">message</span> <span class="string">was</span> <span class="string">sent.</span></div></pre></td></tr></table></figure>
<p>If you are familiar with the OpenAPI specification, I’m sure you already found lots of similarities. But, what’s this <code>topics</code> section in the file? And what’s this <code>event.{streetlightId}.lighting.measured</code>? Let’s dive into it!</p>
<h2 id="Core-concepts"><a href="#Core-concepts" class="headerlink" title="Core concepts"></a>Core concepts</h2><p>The AsyncAPI specification assumes two core concepts:</p>
<h3 id="1-Messages"><a href="#1-Messages" class="headerlink" title="1. Messages"></a>1. Messages</h3><p>Consumer(s) communicate with your API via messages. A message is a piece of information two or more programs exchange. Most of the times to notify the other end(s) that, either an event has occurred or you want to trigger a command.</p>
<p>Technically speaking the events and actions will always be sent in the same way. These are just messages, and their content can be anything. So when we talk about the difference between events and actions, this is only a semantic differentiation of message’s content. We do not enforce you to make any difference between them, although we encourage you to do it.</p>
<p>A message can contain headers and a payload. However, both are optional. The specification allows you to define any header, to remain as much protocol-agnostic as possible.</p>
<h3 id="2-Topics"><a href="#2-Topics" class="headerlink" title="2. Topics"></a>2. Topics</h3><p>Message-driven protocols usually contain something called topic (<a href="http://www.hivemq.com/blog/mqtt-essentials-part-5-mqtt-topics-best-practices" target="_blank" rel="external">MQTT</a>), routing key (AMQP), destination (STOMP), etc. To some extent, they can compare to URLs in HTTP APIs. So, when you send a message to your API, it will be routed depending on the topic you published on. This feature allows you to create APIs that subscribe to specific topics and publish to other ones.</p>
<p>There’s no standard way of naming topics, so we recommend you to <strong><a href="https://github.com/asyncapi/topic-definition" target="_blank" rel="external">have a look at our proposal here</a></strong>.</p>
<div class="guide-links">
</div>
{% include footer.html %}
</div>
</div>
<script src="/js/smooth-scroll.min.js"></script>
<!-- main custom script for sidebars, version selects etc. -->
<script src="/js/css.escape.js"></script>
<script src="/js/common.js"></script>
<!-- fastclick -->
<script src="//cdnjs.cloudflare.com/ajax/libs/fastclick/1.0.6/fastclick.min.js"></script>
<script>
document.addEventListener('DOMContentLoaded', function() {
FastClick.attach(document.body)
}, false)
</script>
</body>
</html>