Automated commit at 2023-10-12 19:15:30 UTC by middleman-deploy 2.0.0…

…-alpha
apiaryio · Oct 12, 2023 · d0b5fb0 · d0b5fb0
commit d0b5fb0
Show file tree

Hide file tree

Showing 52 changed files with 17,786 additions and 0 deletions.
diff --git a/CNAME b/CNAME
@@ -0,0 +1 @@
+apiblueprint.org
diff --git a/developers.html b/developers.html
diff --git a/documentation/advanced-tutorial.html b/documentation/advanced-tutorial.html
@@ -0,0 +1,282 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+
+    <title>API Blueprint Advanced Tutorial | API Blueprint</title>
+
+    <link href="/images/favicon-10b3ff24.png" rel="icon" type="image/png" />
+    <link href="//netdna.bootstrapcdn.com/font-awesome/4.5.0/css/font-awesome.min.css" rel="stylesheet" /><link href="//netdna.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css" rel="stylesheet" /><link href="/stylesheets/all.css" rel="stylesheet" /><link href="/stylesheets/highlight.css" rel="stylesheet" />
+    <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,300' rel='stylesheet' type='text/css'>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/zepto/1.1.6/zepto.min.js"></script>
+    <script src="/javascripts/all.js"></script>
+  </head>
+
+  <body class="documentation documentation_advanced-tutorial">
+    <header>
+      <div class="container">
+        <div class="pull-right">
+          <a href="https://twitter.com/apiblueprint" class="twitter-follow-button" data-show-count="false">Follow @apiblueprint</a> <script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src=p+'://platform.twitter.com/widgets.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'twitter-wjs');</script>
+          <iframe src="https://ghbtns.com/github-btn.html?user=apiaryio&repo=api-blueprint&type=star&count=true" frameborder="0" scrolling="0" width="105px" height="20px"></iframe>
+        </div>
+
+        <hr />
+
+        <div class="navbar-header">
+          <a href="/" class="navbar-brand">API Blueprint</a>
+
+          <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar">
+              <span class="sr-only">Toggle navigation</span>
+              <span class="icon-bar"></span>
+              <span class="icon-bar"></span>
+              <span class="icon-bar"></span>
+          </button>
+        </div>
+
+        <nav class="collapse navbar-collapse bs-navbar-collapse" role="navigation" id="navbar">
+          <ul class="nav navbar-nav navbar-right">
+            <li><a class="documentation" href="/documentation/">Docs</a></li>
+            <li><a class="tools" href="/tools.html">Tools</a></li>
+            <li><a class="developers" href="/developers.html">Developers</a></li>
+            <li><a class="support" href="/support.html">Support</a></li>
+          </ul>
+        </nav>
+      </div>
+    </header>
+
+    <div class="container page-content">
+      <div class="row content">
+        <div id="sidebar" class="col-md-3" role="complementary">
+            <ul class="nav">
+                  <li>
+                  <a href="/documentation/tutorial.html">Tutorial</a></li>
+                  <li class="active">
+                  <a href="/documentation/advanced-tutorial.html">Advanced Tutorial</a></li>
+                  <li>
+                  <a href="/documentation/specification.html">Specification</a></li>
+                  <li>
+                  <a href="/documentation/glossary.html">Glossary of Terms</a></li>
+                  <li>
+                  <a href="/documentation/mson/cheatsheet.html">MSON Cheatsheet</a></li>
+                  <li>
+                  <a href="/documentation/mson/tutorial.html">MSON</a></li>
+                  <li>
+                  <a href="/documentation/mson/specification.html">MSON Specification</a></li>
+                  <li>
+                  <a href="/documentation/examples/">Examples</a></li>
+            </ul>
+        </div>
+        <div class="col-md-9 text" role="main">
+            <h2>API Blueprint Advanced Tutorial</h2>
+            <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
+<html><body>
+<p>Welcome to the advanced API Blueprint tutorial! This tutorial will take you
+through advanced topics like JSON Schema, request and response attributes, data
+structures and relation types.</p>
+
+<p>This tutorial assumes that you have read the <a href="https://github.com/apiaryio/api-blueprint/blob/master/Tutorial.md">API Blueprint Tutorial</a>.</p>
+
+<h2 id="json-schema">JSON Schema</h2>
+
+<p>Action request and response bodies can have associated schemas that describe
+the allowed structure of the body content. JSON bodies are typically described
+with <a href="http://json-schema.org/">JSON Schema</a>. Given a simple JSON response body
+we can describe the structure of the response with JSON Schema in a <code>+ Schema</code>
+section.</p>
+
+<p>The schema can describe the type of each member, which members are required,
+default values, and support a number of other advanced features. Below is an
+example, taken from the 
+<a href="https://raw.github.com/apiaryio/api-blueprint/master/examples/Polls%20API.md">Polls API</a>
+blueprint:</p>
+<div class="highlight"><pre class="highlight apiblueprint"><code><span class="p">###</span><span class="gh"> Create a New Question </span><span class="s">[POST]</span>
+You may create your own question using this action. It takes a JSON object
+containing a question and a collection of answers in the form of choices.
+<span class="p">
++</span> Request (application/json)<span class="sb">
+
+    + Body
+
+            {
+              "question": "Favourite language?"
+              "choices": [
+                "Swift",
+                "Objective-C"
+              ]
+            }
+
+    + Schema
+
+            {
+              "$schema": "http://json-schema.org/draft-04/schema#",
+              "type": "object",
+              "properties": {
+                "question": {
+                  "type": "string"
+                },
+                "choices": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "minItems": 2
+                }
+              }
+            }
+</span></code></pre></div>
+<h2 id="attributes">Attributes</h2>
+
+<p>Another way of describing examples and the structure of your request and
+response content is by using <a href="https://github.com/apiaryio/mson#readme">MSON</a>.
+MSON, like API Blueprint, allows you to use human-readable plain text to
+describe things rather than formats designed for computer parsing like JSON or
+YAML. Where API Blueprint allows you to describe your API, MSON allows you to
+describe data structures.</p>
+
+<p>MSON can be added to resources, actions, and individual requests or responses
+via an <code>+ Attributes</code> section.</p>
+
+<p>Creating a new question in the polls API can be modeled using MSON:</p>
+<div class="highlight"><pre class="highlight apiblueprint"><code><span class="p">###</span><span class="gh"> Create a New Question </span><span class="s">[POST]</span>
+You may create your own question using this action. It takes a JSON object
+containing a question and a collection of answers in the form of choices.
+<span class="p">
++</span> Request (application/json)<span class="sb">
+
+    + Attributes
+
+        + question: Favourite Language? (required)
+        + choices: Swift, `Objective-C` (array, required)
+
+</span></code></pre></div>
+<p>When the above blueprint is parsed it will have a JSON body and JSON Schema
+example generated for it from the MSON attributes. Note, however, that the
+generated JSON Schema may differ from a hand-written one. In this example, the
+<code>minItems</code> will not be set. If you have such constraints you can override the
+generated schema by providing your own, in which case only the JSON body will
+be generated.</p>
+
+<h2 id="data-structures">Data Structures</h2>
+
+<p>Once you start using MSON, you may find yourself wanting to reuse certain
+commonly used or nested data structure components. This is possible with the
+<code>## Data Structures</code> section. Attributes sections can then reference the data
+structures defined in the Data Structures or other resource sections by name.</p>
+
+<p>For example, using the polls API question collection resource, we can split out
+the <code>Question</code> and <code>Choice</code> objects:</p>
+<div class="highlight"><pre class="highlight apiblueprint"><code><span class="p">###</span><span class="gh"> List All Questions </span><span class="s">[GET]</span>
+<span class="p">+ </span><span class="k">Response</span><span class="m"> 200</span><span class="s"> (application/json)</span><span class="sb">
+
+    + Attributes (array[Question])
+
+</span><span class="gu">## Data Structures</span>
+
+<span class="gu">### Question</span>
+<span class="p">+</span> question: Favourite programming language? (required)
+<span class="p">+</span> published_at: <span class="nv">`2014-11-11T08:40</span><span class="p">:</span><span class="s">51.620Z` (required)</span>
+<span class="p">+</span> url: /questions/1 (required)
+<span class="p">+</span> choices (array[Choice], required)
+
+<span class="gu">### Choice</span>
+<span class="p">+</span> choice: Javascript (required)
+<span class="p">+</span> url: /questions/1/choices/1 (required)
+<span class="p">+</span> votes: 2048 (number, required)
+
+</code></pre></div>
+<h2 id="relation-types">Relation Types</h2>
+
+<p>Actions in a blueprint can define a semantic domain-specific meaning by
+defining a relation type using a <code>+ Relation</code> section. This means that an
+action can have a specific meaning regardless of its URI or name, and allows
+clients to be built based on the domain of the API rather than specific URIs.</p>
+
+<p>For example, in the polls API:</p>
+<div class="highlight"><pre class="highlight apiblueprint"><code><span class="p">##</span><span class="gh"> Question </span><span class="s">[/question/{id}]</span>
+<span class="p">###</span><span class="gh"> View a Question Detail </span><span class="s">[GET]</span>
+<span class="p">+</span><span class="k"> Relation:</span><span class="s"> self</span>
+
+<span class="p">###</span><span class="gh"> Delete a Question </span><span class="s">[DELETE]</span>
+<span class="p">+</span><span class="k"> Relation:</span><span class="s"> delete</span>
+
+<span class="p">##</span><span class="gh"> Questions Collection </span><span class="s">[/questions]</span>
+<span class="p">###</span><span class="gh"> List All Questions </span><span class="s">[GET]</span>
+<span class="p">+</span><span class="k"> Relation:</span><span class="s"> self</span>
+</code></pre></div>
+<p>A server or client implementation can now use this information to handle the
+specific API resource and action URIs. Please see the 
+<a href="https://tools.ietf.org/html/rfc5988">Web Linking RFC 5988</a> and the 
+<a href="http://www.iana.org/assignments/link-relations/link-relations.xhtml">IANA Link Relation Types</a> for
+more information.</p>
+
+<h2 id="conclusion">Conclusion</h2>
+
+<p>This tutorial has covered some advanced API Blueprint topics.
+For more in-depth information and other advanced topics,
+please see the <a href="https://github.com/apiaryio/api-blueprint/blob/master/API%20Blueprint%20Specification.md">API Blueprint Specification</a>.</p>
+</body></html>
+
+        </div>
+      </div>
+    </div>
+
+    <footer>
+      <div class="container">
+        <div>
+          <ul class="social">
+              <li>
+                <a href="https://stackoverflow.com/questions/tagged/apiblueprint?sort=frequent&pageSize=15">
+                  <img src="/images/stackoverflow-994229fe.svg" />
+                  <span class="relation">FAQ</span>
+                  <span class="service">Stack Overflow</span>
+                </a>
+              </li>
+              <li>
+                <a href="https://github.com/apiaryio/api-blueprint/issues">
+                  <img src="/images/github-893a5b9a.svg" />
+                  <span class="relation">Issues</span>
+                  <span class="service">GitHub</span>
+                </a>
+              </li>
+              <li>
+                <a href="https://twitter.com/apiblueprint">
+                  <img src="/images/twitter-2ade0f64.svg" />
+                  <span class="relation">Twitter</span>
+                  <span class="service">@apiblueprint</span>
+                </a>
+              </li>
+          </ul>
+        </div>
+
+        <hr />
+
+        <div class="info row">
+          <div class="brand-block col-md-6">
+              <img src="/images/apiblueprint-footer-81a6c64c.svg" alt="API Blueprint Logo" width=38 height=36 />
+              <div class="brand-info">
+                <span class="brand">API Blueprint</span>
+                <span>&copy; 2013—2023</span>
+              </div>
+            </ul>
+          </div>
+          <ul class="nav nav-pills col-md-6 text-md-right">
+            <li><a class="documentation" href="/documentation/">Docs</a></li>
+            <li><a class="tools" href="/tools.html">Tools</a></li>
+            <li><a class="developers" href="/developers.html">Developers</a></li>
+            <li><a class="support" href="/support.html">Support</a></li>
+          </ul>
+        </div>
+        <div class="license">API Blueprint is released under <a href="https://github.com/apiaryio/api-blueprint/blob/master/LICENSE">MIT License</a></div>
+      </div>
+    </footer>
+
+    <div class="rocket"></div>
+    <div class="moon"></div>
+
+    <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>
+    <script src="//netdna.bootstrapcdn.com/bootstrap/3.3.6/js/bootstrap.min.js"></script>
+
+  </body>
+</html>