<commit_before><!doctype html>
<html lang="en">

	<head>
		<meta charset="utf-8">

		<title>Documenting REST APIs</title>

		<meta name="author" content="<NAME>">

		<meta name="apple-mobile-web-app-capable" content="yes" />
		<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />

		<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, minimal-ui">

		<link rel="stylesheet" href="css/reveal.css">
		<link rel="stylesheet" href="css/theme/black.css" id="theme">

		<!-- Code syntax highlighting -->
		<link rel="stylesheet" href="lib/css/zenburn.css">

		<style type="text/css">
		.epred {
			color:#ed3d3e;
		}
		.epgreen {
			color:#38af5c;
		}
		.epyellow {
			color:#ffe000;
		}
		.reveal h2, .reveal h3 {
			text-transform: none;
		}
		.reveal a {
			color:#8dcffc;
		}
		</style>

		<!-- FontAwesome -->
		<link rel="stylesheet" href="lib/css/font-awesome/css/font-awesome.min.css">

		<!-- Printing and PDF exports -->
		<script>
			var link = document.createElement( 'link' );
			link.rel = 'stylesheet';
			link.type = 'text/css';
			link.href = window.location.search.match( /print-pdf/gi ) ? 'css/print/pdf.css' : 'css/print/paper.css';
			document.getElementsByTagName( 'head' )[0].appendChild( link );
		</script>

		<!--[if lt IE 9]>
		<script src="lib/js/html5shiv.js"></script>
		<![endif]-->
	</head>

	<body>
		  <div class="fork-repo" style="display: none"><a href="https://github.com/epages-de/rnd-microservices-handson" style="z-index:1; position: absolute; top: 0; right: 0%; border: 0px;"><img src="img/fork-me-on-github.png" style="border:0px;" alt="Fork me on GitHub"/></a></div>

		<div class="reveal">

			<!-- Any section element inside of this container is displayed as a slide -->
			<div class="slides">

				<section>
					<h2>Documented and Tested Microservices For Fun And Profit</h2>
					<p><img data-src="img/epages-devs-logo.png" style="border:none; box-shadow:none; background:none; width:150px;" />
					<p><i class="fa fa-street-view epred"></i> <NAME>, ePages GmbH</p>
					<p align="right"><small><q class="quote">WTF is a "REST endpoint"? <br/> - <NAME></q></small></p>
					<aside class="notes">
						<ul>
						    <li>Über mich: Langjähriger Softwareentwickler bei ePages.</li>
						    <li>Fangen wir mit einem einen kleinen Werbeblock an. Was macht ePages?
						    100.000 Shops, Hostingprovider und Telekommunikations. 
						    Kooperieren mit über 60 Technologiepartnern
						    Standorte in Hamburg, Jena, Barcelona, London, New York
						    Übrigens: wir suchen noch Softwareentwickler für unseren Standort HH
					     </li>
						</ul>
					</aside>
				</section>


				<section>
					<h2>Documenting REST APIs</h2>
					<img data-src="img/rest-documentation-and-data.jpg" style="border:none; "/>
					<p><small><a href="http://apihandyman.io/the-data-the-hypermedia-and-the-documentation/">apihandyman.io</a></small></p>
					<aside class="notes">
						<ul>
							<li>Thema, das unter uns Entwicklern eher unbeliebt ist - Dokumentation.</li>
							<li>Zwei Teilbereiche: Menschenlesbare Dokumentation (Handbücher, User Guide...), 
							Maschinenlesbare Dokumentation (IDL)</li>
							<li>Drei Ziele: vollständig, fehlerfrei, aktuell</li>
							<li>Lüsungen im Java-Kontext.</li>
						</ul>
					</aside>
				</section>

				<section>
					<h2>How RESTful are you?</h2>
					<img data-src="img/maturity-overview.png" style="border:none; box-shadow: 10px 10px 5px #282828;"/>
					
					<aside class="notes">
						<ul>
							<li>Richardson Maturity Model</li>
							<li>Level 2: Auf die Idee mit einem GET den Suchindex löschen zu lassen kommt heutzutage nur noch Apache Solr.</li>
							<li>Je nach Kategorisierung der eigenen API ist eine andere Art der Dokumentation nötig.</li>
							<li><NAME>: "The Glory of REST" / Level 3 /  Heiligenschein (ernst gemeint?)</li>
							<li>Auch Level 0-2 APIs haben ihre Daseinsberechtigung, sie sind nur nicht ganz "im Sinne des Erfinders"</li>
						</ul>
					</aside>
				</section>


				<section>
					<h2>How RESTful do you<br/>want to be?</h2>
					<aside class="notes">
						<ul>
							<li>Die Frage sollte daher eher lauten - wo im RMM möchtest du dich platzieren? </li>
						</ul>
					</aside>
				</section>


				<section>
					<h2>Interface Description Languages</h2>
					<ul style="list-style-type: none; ">
						<li class="fragment" style="display: inline;"><a href="http://www.w3.org/TR/wsdl">WSDL</a> (2001)</li>
						<li class="fragment" style="display: inline;"><span class="epred">|</span> <a href="http://www.w3.org/Submission/wadl/">WADL</a> (2009)</li>
						<li class="fragment" style="display: inline;"><span class="epgreen">|</span> <a hreF="http://swagger.io/">Swagger</a> (2009)</li>
						<li class="fragment" style="display: inline;"><span class="epred">|</span> <a href="http://restdesc.org/">RESTdesc</a> (2010)</li>
						<li class="fragment" style="display: inline;"><span class="epgreen">|</span> <a href="http://www.mashery.com/">I/O Docs</a> (2011)</li>
						<li class="fragment" style="display: inline;"><span class="epred">|</span> <a href="http://tools.ietf.org/html/draft-nottingham-json-home-03">JSON Home</a> (2012)</li>
						<li class="fragment" style="display: inline;"><span class="epgreen">|</span> <a href="https://raml.org/">RAML</a> (2013)</li>
						<li class="fragment" style="display: inline;"><span class="epred">|</span> <a href="https://apiblueprint.org/">API Blueprint</a> (2013)</li>
						<li class="fragment" style="display: inline;"><span class="epgreen">|</span> <a href="http://json-schema.org/latest/json-schema-hypermedia.html">JSON Hyper-Schema</a> (2013)</li>
						<li class="fragment" style="display: inline;"><span class="epred">|</span> <a href="http://www.markus-lanthaler.com/hydra/spec/latest/core/">Hydra</a> (2014, draft)</li>
						<li class="fragment" style="display: inline;"><span class="epgreen">|</span> <a href="http://alps.io">ALPS</a> (2014, draft)</li>
						<li class="fragment" style="display: inline;"><span class="epred">|</span> <a href="https://rawgit.com/uber-hypermedia/specification/master/uber-hypermedia.html">UBER</a> (2015, draft)</li>
						<li class="fragment" style="display: inline;"><span class="epgreen">|</span> <a href="https://github.com/mikestowe/CPHL">CPHL</a> (2015, brain-storming)</li>
						<li class="fragment" style="display: inline;">..</li>
					</ul>
					<aside class="notes">
						<ul>
							<li>WSDL 1.1 als Referenz, 2000 Roy Fieldings Dissertation "Design of Network-based Software Architectures"</li>
							<li>Swagger ist von den genannten tools sicherlich das populärste - eines der Key features ist die Interaktive Konsole</li>
							<li>Wir verwenden für einen Teil der API Dokumentation RAML, eine auf YAML basierende Spezifikationssprache.</li>
							<li>Nachteile von swagger: zu URI-zentriert, keine Unterstützung von Querschnitts-Aspekten (Auth, Errors), "undichte" Abstraktion - zieht ggf. fehlerhafte Rückschlüsse 
							, groß, schwemmt den Code mit eigenen Annotations auf.</li>
							<li>
						</ul>
					</aside>
				</section>


				<section data-transition="none">
					<h2>Media Types</h2>
					<ul>
						<li class="fragment" style="display: inline;">Plain-old XML</li>
						<li class="fragment" style="display: inline;"><span class="epred">|</span> Proprietary JSON</li>
						<li class="fragment" style="display: inline;"> </li>
						<li class="fragment" style="display: inline;"><span class="epgreen">|</span> <a href="http://stateless.co/hal_specification.html">HAL</a> (2011)</li>
						<li class="fragment" style="display: inline;"><span class="epred">|</span> <a href="http://json-ld.org/">JSON-LD</a> (2011)</li>
						<li class="fragment" style="display: inline;"><span class="epgreen">|</span> <a hreF="http://amundsen.com/media-types/collection/">Collection+JSON</a> (2011)</li>
						<li class="fragment" style="display: inline;"><span class="epred">|</span> <a href="http://www.markus-lanthaler.com/hydra/spec/latest/core/">Hydra</a> (2014)</li>
						<li class="fragment" style="display: inline;"><span class="epgreen">|</span> <a href="https://github.com/JornWildt/Mason">Mason</a> (2014, draft)</li>
						<li class="fragment" style="display: inline;"><span class="epred">|</span> <a href="https://github.com/kevinswiber/siren">SIREN</a> (2015, draft)</li>
						<li class="fragment" style="display: inline;">..</li>
					</ul>
					<aside class="notes">
						<ul>
							<li>HAL: IETF Draft, Mike Kelly, http://tools.ietf.org/html/draft-kelly-json-hal </li>
							<li>JSON-LD: W3C Recommendation, M. Lanthaler, http://www.w3.org/TR/json-ld/</li>
							<li>Hydra: Baut auf LSON-LD auf. W3C Unofficial draft M. Lanthaler, http://www.markus-lanthaler.com/hydra/spec/latest/core/ </li>
							<li>Collection+JSON (vgl. mit Atom Feed) <NAME>, http://amundsen.com/media-types/collection/format/</li>
							<li>Mason: <NAME> (vgl. mit Siren, Hydra)</li>
						</ul>
					</aside>
				</section>

				<section data-transition="none">
					<h2>HAL</h2>
					
					<pre><code data-trim>
{
  "_links": {
    "self": {
      "href": "http://otrosien:8081/pizzas"
    }
  },<commit_msg>added JSON API<commit_after><!doctype html>
<html lang="en">

	<head>
		<meta charset="utf-8">

		<title>Documenting REST APIs</title>

		<meta name="author" content="<NAME>">

		<meta name="apple-mobile-web-app-capable" content="yes" />
		<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent" />

		<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, minimal-ui">

		<link rel="stylesheet" href="css/reveal.css">
		<link rel="stylesheet" href="css/theme/black.css" id="theme">

		<!-- Code syntax highlighting -->
		<link rel="stylesheet" href="lib/css/zenburn.css">

		<style type="text/css">
		.epred {
			color:#ed3d3e;
		}
		.epgreen {
			color:#38af5c;
		}
		.epyellow {
			color:#ffe000;
		}
		.reveal h2, .reveal h3 {
			text-transform: none;
		}
		.reveal a {
			color:#8dcffc;
		}
		</style>

		<!-- FontAwesome -->
		<link rel="stylesheet" href="lib/css/font-awesome/css/font-awesome.min.css">

		<!-- Printing and PDF exports -->
		<script>
			var link = document.createElement( 'link' );
			link.rel = 'stylesheet';
			link.type = 'text/css';
			link.href = window.location.search.match( /print-pdf/gi ) ? 'css/print/pdf.css' : 'css/print/paper.css';
			document.getElementsByTagName( 'head' )[0].appendChild( link );
		</script>

		<!--[if lt IE 9]>
		<script src="lib/js/html5shiv.js"></script>
		<![endif]-->
	</head>

	<body>
		  <div class="fork-repo" style="display: none"><a href="https://github.com/epages-de/rnd-microservices-handson" style="z-index:1; position: absolute; top: 0; right: 0%; border: 0px;"><img src="img/fork-me-on-github.png" style="border:0px;" alt="Fork me on GitHub"/></a></div>

		<div class="reveal">

			<!-- Any section element inside of this container is displayed as a slide -->
			<div class="slides">

				<section>
					<h2>Documented and Tested Microservices For Fun And Profit</h2>
					<p><img data-src="img/epages-devs-logo.png" style="border:none; box-shadow:none; background:none; width:150px;" />
					<p><i class="fa fa-street-view epred"></i> <NAME>, ePages GmbH</p>
					<p align="right"><small><q class="quote">WTF is a "REST endpoint"? <br/> - Roy Fielding</q></small></p>
					<aside class="notes">
						<ul>
						    <li>Über mich: Langjähriger Softwareentwickler bei ePages.</li>
						    <li>Fangen wir mit einem einen kleinen Werbeblock an. Was macht ePages?
						    100.000 Shops, Hostingprovider und Telekommunikations. 
						    Kooperieren mit über 60 Technologiepartnern
						    Standorte in Hamburg, Jena, Barcelona, London, New York
						    Übrigens: wir suchen noch Softwareentwickler für unseren Standort HH
					     </li>
						</ul>
					</aside>
				</section>


				<section>
					<h2>Documenting REST APIs</h2>
					<img data-src="img/rest-documentation-and-data.jpg" style="border:none; "/>
					<p><small><a href="http://apihandyman.io/the-data-the-hypermedia-and-the-documentation/">apihandyman.io</a></small></p>
					<aside class="notes">
						<ul>
							<li>Thema, das unter uns Entwicklern eher unbeliebt ist - Dokumentation.</li>
							<li>Zwei Teilbereiche: Menschenlesbare Dokumentation (Handbücher, User Guide...), 
							Maschinenlesbare Dokumentation (IDL)</li>
							<li>Drei Ziele: vollständig, fehlerfrei, aktuell</li>
							<li>Lüsungen im Java-Kontext.</li>
						</ul>
					</aside>
				</section>

				<section>
					<h2>How RESTful are you?</h2>
					<img data-src="img/maturity-overview.png" style="border:none; box-shadow: 10px 10px 5px #282828;"/>
					
					<aside class="notes">
						<ul>
							<li>Richardson Maturity Model</li>
							<li>Level 2: Auf die Idee mit einem GET den Suchindex löschen zu lassen kommt heutzutage nur noch Apache Solr.</li>
							<li>Je nach Kategorisierung der eigenen API ist eine andere Art der Dokumentation nötig.</li>
							<li><NAME>: "The Glory of REST" / Level 3 /  Heiligenschein (ernst gemeint?)</li>
							<li>Auch Level 0-2 APIs haben ihre Daseinsberechtigung, sie sind nur nicht ganz "im Sinne des Erfinders"</li>
						</ul>
					</aside>
				</section>


				<section>
					<h2>How RESTful do you<br/>want to be?</h2>
					<aside class="notes">
						<ul>
							<li>Die Frage sollte daher eher lauten - wo im RMM möchtest du dich platzieren? </li>
						</ul>
					</aside>
				</section>


				<section>
					<h2>Interface Description Languages</h2>
					<ul style="list-style-type: none; ">
						<li class="fragment" style="display: inline;"><a href="http://www.w3.org/TR/wsdl">WSDL</a> (2001)</li>
						<li class="fragment" style="display: inline;"><span class="epred">|</span> <a href="http://www.w3.org/Submission/wadl/">WADL</a> (2009)</li>
						<li class="fragment" style="display: inline;"><span class="epgreen">|</span> <a hreF="http://swagger.io/">Swagger</a> (2009)</li>
						<li class="fragment" style="display: inline;"><span class="epred">|</span> <a href="http://restdesc.org/">RESTdesc</a> (2010)</li>
						<li class="fragment" style="display: inline;"><span class="epgreen">|</span> <a href="http://www.mashery.com/">I/O Docs</a> (2011)</li>
						<li class="fragment" style="display: inline;"><span class="epred">|</span> <a href="http://tools.ietf.org/html/draft-nottingham-json-home-03">JSON Home</a> (2012)</li>
						<li class="fragment" style="display: inline;"><span class="epgreen">|</span> <a href="https://raml.org/">RAML</a> (2013)</li>
						<li class="fragment" style="display: inline;"><span class="epred">|</span> <a href="https://apiblueprint.org/">API Blueprint</a> (2013)</li>
						<li class="fragment" style="display: inline;"><span class="epgreen">|</span> <a href="http://json-schema.org/latest/json-schema-hypermedia.html">JSON Hyper-Schema</a> (2013)</li>
						<li class="fragment" style="display: inline;"><span class="epred">|</span> <a href="http://www.markus-lanthaler.com/hydra/spec/latest/core/">Hydra</a> (2014, draft)</li>
						<li class="fragment" style="display: inline;"><span class="epgreen">|</span> <a href="http://alps.io">ALPS</a> (2014, draft)</li>
						<li class="fragment" style="display: inline;"><span class="epred">|</span> <a href="https://rawgit.com/uber-hypermedia/specification/master/uber-hypermedia.html">UBER</a> (2015, draft)</li>
						<li class="fragment" style="display: inline;"><span class="epgreen">|</span> <a href="https://github.com/mikestowe/CPHL">CPHL</a> (2015, brain-storming)</li>
						<li class="fragment" style="display: inline;">..</li>
					</ul>
					<aside class="notes">
						<ul>
							<li>WSDL 1.1 als Referenz, 2000 Roy Fieldings Dissertation "Design of Network-based Software Architectures"</li>
							<li>Swagger ist von den genannten tools sicherlich das populärste - eines der Key features ist die Interaktive Konsole</li>
							<li>Wir verwenden für einen Teil der API Dokumentation RAML, eine auf YAML basierende Spezifikationssprache.</li>
							<li>Nachteile von swagger: zu URI-zentriert, keine Unterstützung von Querschnitts-Aspekten (Auth, Errors), "undichte" Abstraktion - zieht ggf. fehlerhafte Rückschlüsse 
							, groß, schwemmt den Code mit eigenen Annotations auf.</li>
							<li>
						</ul>
					</aside>
				</section>


				<section data-transition="none">
					<h2>Media Types</h2>
					<ul>
						<li class="fragment" style="display: inline;">Plain-old XML</li>
						<li class="fragment" style="display: inline;"><span class="epred">|</span> Proprietary JSON</li>
						<li class="fragment" style="display: inline;"> </li>
						<li class="fragment" style="display: inline;"><span class="epgreen">|</span> <a href="http://stateless.co/hal_specification.html">HAL</a> (2011)</li>
						<li class="fragment" style="display: inline;"><span class="epred">|</span> <a href="http://json-ld.org/">JSON-LD</a> (2011)</li>
						<li class="fragment" style="display: inline;"><span class="epgreen">|</span> <a hreF="http://amundsen.com/media-types/collection/">Collection+JSON</a> (2011)</li>
						<li class="fragment" style="display: inline;"><span class="epred">|</span> <a href="http://jsonapi.org/">JSON API</a> (2013)</li>
						<li class="fragment" style="display: inline;"><span class="epgreen">|</span> <a href="http://www.markus-lanthaler.com/hydra/spec/latest/core/">Hydra</a> (2014)</li>
						<li class="fragment" style="display: inline;"><span class="epred">|</span> <a href="https://github.com/JornWildt/Mason">Mason</a> (2014, draft)</li>
						<li class="fragment" style="display: inline;"><span class="epgreen">|</span> <a href="https://github.com/kevinswiber/siren">SIREN</a> (2015, draft)</li>
						<li class="fragment" style="display: inline;">..</li>
					</ul>
					<aside class="notes">
						<ul>
							<li>HAL: IETF Draft, Mike Kelly, http://tools.ietf.org/html/draft-kelly-json-hal </li>
							<li>JSON-LD: W3C Recommendation, M. Lanthaler, http://www.w3.org/TR/json-ld/</li>
							<li>Hydra: Baut auf LSON-LD auf. W3C Unofficial draft M. Lanthaler, http://www.markus-lanthaler.com/hydra/spec/latest/core/ </li>
							<li>Collection+JSON (vgl. mit Atom Feed) Mike Amunndsen, http://amundsen.com/media-types/collection/format/</li>
							<li>Mason: <NAME> (vgl. mit Siren, Hydra)</li>
						</ul>
					</aside>
				</section>

				<section data-transition="none">
					<h2>HAL</h2>
					
					<pre><code data-trim>
{
  "_links": {
    "self": {
      "href": "http://otrosien:8081/pizzas"
    }
  },
{'fraction_non_alphanumeric': 0.19241685856584373, 'fraction_numerical': 0.017029936271622127, 'mean_word_length': 3.6234216390195595, 'pattern_counts': {'":': 6, '<': 581, '<?xml version=': 0, '>': 581, 'https://': 14, 'lorem ipsum': 0, 'www.': 14, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1584451', 'n_tokens_mistral': 8126, 'n_tokens_neox': 6540, 'n_words': 1389}