├── .gitmodules ├── .nojekyll ├── README.md ├── bin └── fix ├── css ├── custom.css ├── reveal-base.css ├── reveal-theme.css └── reveal.css ├── fonts └── lato │ ├── LatoLatin-Bold.eot │ ├── LatoLatin-Bold.ttf │ ├── LatoLatin-Bold.woff │ ├── LatoLatin-BoldItalic.eot │ ├── LatoLatin-BoldItalic.ttf │ ├── LatoLatin-BoldItalic.woff │ ├── LatoLatin-Italic.eot │ ├── LatoLatin-Italic.ttf │ ├── LatoLatin-Italic.woff │ ├── LatoLatin-Regular.eot │ ├── LatoLatin-Regular.ttf │ ├── LatoLatin-Regular.woff │ ├── LatoLatinLight-Italic.eot │ ├── LatoLatinLight-Italic.ttf │ ├── LatoLatinLight-Italic.woff │ ├── LatoLatinLight-Regular.eot │ ├── LatoLatinLight-Regular.ttf │ └── LatoLatinLight-Regular.woff ├── images ├── aglio-example.png ├── aglio.png ├── apiary-1.png ├── apiary-2.png ├── apiblueprint.png ├── apiplatform.png ├── application-state.svg ├── drakov.gif ├── dredd.png ├── graphql.png ├── hurlit.png ├── jsonapi.png ├── mmmh.png ├── nope.gif ├── oai.png ├── postman.png ├── resource-state.svg ├── rmm.png ├── trump.png └── twitter-example.png ├── index.html ├── monod.md └── slides.md /.gitmodules: -------------------------------------------------------------------------------- 1 | [submodule "reveal.js"] 2 | path = reveal.js 3 | url = https://github.com/hakimel/reveal.js.git 4 | [submodule "font-awesome"] 5 | path = font-awesome 6 | url = https://github.com/FortAwesome/Font-Awesome.git 7 | -------------------------------------------------------------------------------- /.nojekyll: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/.nojekyll -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Pragmatic APIs 101 2 | 3 | ## Abstract 4 | 5 | Over the last five years, I have studied REST and HTTP APIs a lot. Nowadays, 6 | everyone claims to have a REST API, yet the REST architecture is complex and not 7 | really practicable in real life. In this talk, we will see that it does not 8 | matter to be 100% REST-compliant, and above all, how to build an API in a 9 | pragmatic manner. 10 | 11 | ## About the slides 12 | 13 | This slide deck has been written with 14 | [Monod](https://github.com/tailordev/monod), then exported as a Markdown file 15 | (`monod.md`) using Cmd + S. I created a Reveal.js template 16 | made of HTML and CSS (using the same CSS as in Monod), and a tool to fix a few 17 | things in the markdown exported by Monod (`bin/fix` script). The idea of this 18 | slide deck is to have a backup, in case the Internet goes wrong, my laptop 19 | burns, or any other disaster. 20 | 21 | Here is my workflow: 22 | 23 | 1. I write slides in Monod 24 | 2. I export the Markdown into this repository 25 | 3. I run `bin/fix monod.md` 26 | 4. I commit both `monod.md` and `slides.md` (generated by `bin/fix`) 27 | 5. I profit! 28 | -------------------------------------------------------------------------------- /bin/fix: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env php 2 | \n\\1\n", $content); 6 | $content = preg_replace('#{no-border}#', '', $content); 7 | $content = preg_replace('#{no-bullet}#', '', $content); 8 | $content = preg_replace('#:fa-([a-z-]+):#', '', $content); 9 | $content = preg_replace('#:heart:#', '', $content); 10 | $content = preg_replace('#:ua:#', 'UA', $content); 11 | $content = preg_replace('#http://localhost:8000/#', '', $content); 12 | 13 | file_put_contents("slides.md", $content); 14 | -------------------------------------------------------------------------------- /css/custom.css: -------------------------------------------------------------------------------- 1 | img { 2 | border: 0 !important; 3 | box-shadow: none !important; 4 | background: none !important; 5 | } 6 | 7 | .no-bullet li { 8 | list-style-type: none; 9 | } 10 | -------------------------------------------------------------------------------- /css/reveal-base.css: -------------------------------------------------------------------------------- 1 | /* Webfont: LatoLatinLight-Regular */@font-face { 2 | font-family: 'LatoLatinLight'; 3 | src: url('../fonts/lato/LatoLatinLight-Regular.eot'); /* IE9 Compat Modes */ 4 | src: url('../fonts/lato/LatoLatinLight-Regular.eot?#iefix') format('embedded-opentype'), /* IE6-IE8 */ 5 | url('../fonts/lato/LatoLatinLight-Regular.woff') format('woff'), /* Modern Browsers */ 6 | url('../fonts/lato/LatoLatinLight-Regular.ttf') format('truetype'); 7 | font-style: normal; 8 | font-weight: normal; 9 | text-rendering: optimizeLegibility; 10 | } 11 | /* Webfont: LatoLatinLight-BoldItalic */@font-face { 12 | font-family: 'LatoLatinLight'; 13 | src: url('../fonts/lato/LatoLatin-Italic.eot'); /* IE9 Compat Modes */ 14 | src: url('../fonts/lato/LatoLatin-Italic.eot?#iefix') format('embedded-opentype'), /* IE6-IE8 */ 15 | url('../fonts/lato/LatoLatin-Italic.woff') format('woff'), /* Modern Browsers */ 16 | url('../fonts/lato/LatoLatin-Italic.ttf') format('truetype'); 17 | font-style: italic; 18 | font-weight: bold; 19 | text-rendering: optimizeLegibility; 20 | } 21 | 22 | /* Webfont: LatoLatinLight-Bold */@font-face { 23 | font-family: 'LatoLatinLight'; 24 | src: url('../fonts/lato/LatoLatin-Regular.eot'); /* IE9 Compat Modes */ 25 | src: url('../fonts/lato/LatoLatin-Regular.eot?#iefix') format('embedded-opentype'), /* IE6-IE8 */ 26 | url('../fonts/lato/LatoLatin-Regular.woff') format('woff'), /* Modern Browsers */ 27 | url('../fonts/lato/LatoLatin-Regular.ttf') format('truetype'); 28 | font-style: normal; 29 | font-weight: bold; 30 | text-rendering: optimizeLegibility; 31 | } 32 | 33 | /*! 34 | * reveal.js 35 | * http://lab.hakim.se/reveal-js 36 | * MIT licensed 37 | * 38 | * Copyright (C) 2016 Hakim El Hattab, http://hakim.se 39 | */ 40 | /********************************************* 41 | * RESET STYLES 42 | *********************************************/ 43 | html, body, .reveal div, .reveal span, .reveal applet, .reveal object, .reveal iframe, 44 | .reveal h1, .reveal h2, .reveal h3, .reveal h4, .reveal h5, .reveal h6, .reveal p, .reveal blockquote, .reveal pre, 45 | .reveal a, .reveal abbr, .reveal acronym, .reveal address, .reveal big, .reveal cite, .reveal code, 46 | .reveal del, .reveal dfn, .reveal em, .reveal img, .reveal ins, .reveal kbd, .reveal q, .reveal s, .reveal samp, 47 | .reveal small, .reveal strike, .reveal strong, .reveal sub, .reveal sup, .reveal tt, .reveal var, 48 | .reveal b, .reveal u, .reveal center, 49 | .reveal dl, .reveal dt, .reveal dd, .reveal ol, .reveal ul, .reveal li, 50 | .reveal fieldset, .reveal form, .reveal label, .reveal legend, 51 | .reveal table, .reveal caption, .reveal tbody, .reveal tfoot, .reveal thead, .reveal tr, .reveal th, .reveal td, 52 | .reveal article, .reveal aside, .reveal canvas, .reveal details, .reveal embed, 53 | .reveal figure, .reveal figcaption, .reveal footer, .reveal header, .reveal hgroup, 54 | .reveal menu, .reveal nav, .reveal output, .reveal ruby, .reveal section, .reveal summary, 55 | .reveal time, .reveal mark, .reveal audio, .reveal video { 56 | margin: 0; 57 | padding: 0; 58 | border: 0; 59 | font-size: 100%; 60 | font: inherit; 61 | vertical-align: baseline; } 62 | 63 | .reveal article, .reveal aside, .reveal details, .reveal figcaption, .reveal figure, 64 | .reveal footer, .reveal header, .reveal hgroup, .reveal menu, .reveal nav, .reveal section { 65 | display: block; } 66 | 67 | /********************************************* 68 | * GLOBAL STYLES 69 | *********************************************/ 70 | html, 71 | body { 72 | width: 100%; 73 | height: 100%; 74 | overflow: hidden; } 75 | 76 | body { 77 | position: relative; 78 | line-height: 1; 79 | background-color: #fff; 80 | font-family: 'LatoLatinLight', 'Helvetica Neue', Helvetica, Roboto, Arial, sans-serif; 81 | color: #000; } 82 | 83 | html:-webkit-full-screen-ancestor { 84 | background-color: inherit; } 85 | 86 | html:-moz-full-screen-ancestor { 87 | background-color: inherit; } 88 | 89 | -------------------------------------------------------------------------------- /css/reveal-theme.css: -------------------------------------------------------------------------------- 1 | /********************************************* 2 | * GLOBAL STYLES 3 | *********************************************/ 4 | .reveal { 5 | font-size: 38px; 6 | font-weight: normal; 7 | color: #222; } 8 | 9 | .reveal .slides > section, 10 | .reveal .slides > section > section { 11 | line-height: 1.3; 12 | font-weight: inherit; } 13 | 14 | /********************************************* 15 | * HEADERS 16 | *********************************************/ 17 | .reveal h1, 18 | .reveal h2, 19 | .reveal h3, 20 | .reveal h4, 21 | .reveal h5, 22 | .reveal h6 { 23 | margin: 0 0 20px 0; 24 | color: #222; 25 | font-weight: 600; 26 | line-height: 1.2; 27 | letter-spacing: normal; 28 | text-transform: uppercase; 29 | text-shadow: none; 30 | word-wrap: break-word; } 31 | 32 | .reveal h1 { 33 | font-size: 2.5em; } 34 | 35 | .reveal h2 { 36 | font-size: 1.6em; } 37 | 38 | .reveal h3 { 39 | font-size: 1.3em; } 40 | 41 | .reveal h4 { 42 | font-size: 1em; } 43 | 44 | .reveal h1 .fa, 45 | .reveal h2 .fa, 46 | .reveal h3 .fa { 47 | color: #1abc9c; 48 | } 49 | 50 | /********************************************* 51 | * OTHER 52 | *********************************************/ 53 | .reveal p { 54 | margin: 20px 0; 55 | line-height: 1.3; } 56 | 57 | /* Ensure certain elements are never larger than the slide itself */ 58 | .reveal img, 59 | .reveal video, 60 | .reveal iframe { 61 | max-width: 95%; 62 | max-height: 95%; } 63 | 64 | .reveal strong, 65 | .reveal b { 66 | font-weight: bold; } 67 | 68 | .reveal em { 69 | font-style: italic; } 70 | 71 | .reveal ol, 72 | .reveal dl, 73 | .reveal ul { 74 | display: inline-block; 75 | text-align: left; 76 | margin: 0 0 0 1em; } 77 | 78 | .reveal ol { 79 | list-style-type: decimal; } 80 | 81 | .reveal ul { 82 | list-style-type: disc; } 83 | 84 | .reveal ul ul { 85 | list-style-type: square; } 86 | 87 | .reveal ul ul ul { 88 | list-style-type: circle; } 89 | 90 | .reveal ul ul, 91 | .reveal ul ol, 92 | .reveal ol ol, 93 | .reveal ol ul { 94 | display: block; 95 | margin-left: 40px; } 96 | 97 | .reveal dt { 98 | font-weight: bold; } 99 | 100 | .reveal dd { 101 | margin-left: 40px; } 102 | 103 | .reveal q, 104 | .reveal blockquote { 105 | quotes: none; } 106 | 107 | .reveal blockquote { 108 | display: block; 109 | position: relative; 110 | margin: 20px auto; 111 | padding: 5px; 112 | font-style: italic; 113 | background: rgba(255, 255, 255, 0.05); 114 | } 115 | 116 | .reveal blockquote p:first-child, 117 | .reveal blockquote p:last-child { 118 | display: inline-block; } 119 | 120 | .reveal q { 121 | font-style: italic; } 122 | 123 | .reveal pre { 124 | display: block; 125 | position: relative; 126 | width: 90%; 127 | margin: 20px auto; 128 | text-align: left; 129 | font-size: 0.55em; 130 | font-family: monospace; 131 | line-height: 1.2em; 132 | word-wrap: break-word; } 133 | 134 | .reveal code { 135 | font-family: monospace; } 136 | 137 | .reveal pre code { 138 | display: block; 139 | padding: 5px; 140 | overflow: auto; 141 | max-height: 400px; 142 | word-wrap: normal; } 143 | 144 | .reveal table { 145 | margin: auto; 146 | border-collapse: collapse; 147 | border-spacing: 0; } 148 | 149 | .reveal table th { 150 | font-weight: bold; } 151 | 152 | .reveal table th, 153 | .reveal table td { 154 | text-align: left; 155 | padding: 0.2em 0.5em 0.2em 0.5em; 156 | border-bottom: 1px solid; } 157 | 158 | .reveal table th[align="center"], 159 | .reveal table td[align="center"] { 160 | text-align: center; } 161 | 162 | .reveal table th[align="right"], 163 | .reveal table td[align="right"] { 164 | text-align: right; } 165 | 166 | .reveal table tbody tr:last-child th, 167 | .reveal table tbody tr:last-child td { 168 | border-bottom: none; } 169 | 170 | .reveal sup { 171 | vertical-align: super; } 172 | 173 | .reveal sub { 174 | vertical-align: sub; } 175 | 176 | .reveal small { 177 | display: inline-block; 178 | font-size: 0.6em; 179 | line-height: 1.2em; 180 | vertical-align: top; } 181 | 182 | .reveal small * { 183 | vertical-align: top; } 184 | 185 | /********************************************* 186 | * LINKS 187 | *********************************************/ 188 | .reveal a { 189 | color: #1abc9c; 190 | text-decoration: none; 191 | border-bottom: none !important; 192 | -webkit-transition: color .15s ease; 193 | -moz-transition: color .15s ease; 194 | transition: color .15s ease; } 195 | 196 | .reveal a:hover { 197 | color: #2e354f; 198 | text-shadow: none; 199 | border: none; } 200 | 201 | .reveal .roll span:after { 202 | color: #fff; 203 | background: #1a53a1; } 204 | 205 | /********************************************* 206 | * IMAGES 207 | *********************************************/ 208 | .reveal section img { 209 | margin: 15px 0px; 210 | background: rgba(255, 255, 255, 0.12); 211 | border: 2px solid #1ABC9C; 212 | box-shadow: 0 0 10px rgba(0, 0, 0, 0.15); } 213 | 214 | .reveal section img.plain { 215 | border: 0; 216 | box-shadow: none; } 217 | 218 | .reveal a img { 219 | -webkit-transition: all .15s linear; 220 | -moz-transition: all .15s linear; 221 | transition: all .15s linear; } 222 | 223 | .reveal a:hover img { 224 | background: rgba(255, 255, 255, 0.2); 225 | border-color: #1abc9c; 226 | box-shadow: 0 0 20px rgba(0, 0, 0, 0.55); } 227 | 228 | /********************************************* 229 | * NAVIGATION CONTROLS 230 | *********************************************/ 231 | .reveal .controls .navigate-left, 232 | .reveal .controls .navigate-left.enabled { 233 | border-right-color: #1abc9c; } 234 | 235 | .reveal .controls .navigate-right, 236 | .reveal .controls .navigate-right.enabled { 237 | border-left-color: #1abc9c; } 238 | 239 | .reveal .controls .navigate-up, 240 | .reveal .controls .navigate-up.enabled { 241 | border-bottom-color: #1abc9c; } 242 | 243 | .reveal .controls .navigate-down, 244 | .reveal .controls .navigate-down.enabled { 245 | border-top-color: #1abc9c; } 246 | 247 | .reveal .controls .navigate-left.enabled:hover { 248 | border-right-color: #2e354f; } 249 | 250 | .reveal .controls .navigate-right.enabled:hover { 251 | border-left-color: #2e354f; } 252 | 253 | .reveal .controls .navigate-up.enabled:hover { 254 | border-bottom-color: #2e354f; } 255 | 256 | .reveal .controls .navigate-down.enabled:hover { 257 | border-top-color: #2e354f; } 258 | 259 | /********************************************* 260 | * PROGRESS BAR 261 | *********************************************/ 262 | .reveal .progress { 263 | background: rgba(0, 0, 0, 0.2); } 264 | 265 | .reveal .progress span { 266 | background: #1abc9c; 267 | -webkit-transition: width 800ms cubic-bezier(0.26, 0.86, 0.44, 0.985); 268 | -moz-transition: width 800ms cubic-bezier(0.26, 0.86, 0.44, 0.985); 269 | transition: width 800ms cubic-bezier(0.26, 0.86, 0.44, 0.985); } 270 | 271 | /** 272 | * Monod customization 273 | */ 274 | .reveal .no-border img { 275 | border: 0 !important; 276 | box-shadow: none !important; 277 | background: none !important; 278 | } 279 | 280 | .reveal .no-bullet li { 281 | list-style-type: none; 282 | } 283 | 284 | .reveal input[type="checkbox"] { 285 | zoom: 2; 286 | } 287 | -------------------------------------------------------------------------------- /css/reveal.css: -------------------------------------------------------------------------------- 1 | /*! 2 | * reveal.js 3 | * http://lab.hakim.se/reveal-js 4 | * MIT licensed 5 | * 6 | * Copyright (C) 2016 Hakim El Hattab, http://hakim.se 7 | */ 8 | /********************************************* 9 | * RESET STYLES 10 | *********************************************/ 11 | 12 | /* 13 | * Updated by William: 14 | * - removed html, body below 15 | * - removed global style 16 | * - removed .reveal span 17 | */ 18 | 19 | .reveal div, .reveal applet, .reveal object, .reveal iframe, 20 | .reveal h1, .reveal h2, .reveal h3, .reveal h4, .reveal h5, .reveal h6, .reveal p, .reveal blockquote, .reveal pre, 21 | .reveal a, .reveal abbr, .reveal acronym, .reveal address, .reveal big, .reveal cite, .reveal code, 22 | .reveal del, .reveal dfn, .reveal em, .reveal img, .reveal ins, .reveal kbd, .reveal q, .reveal s, .reveal samp, 23 | .reveal small, .reveal strike, .reveal strong, .reveal sub, .reveal sup, .reveal tt, .reveal var, 24 | .reveal b, .reveal u, .reveal center, 25 | .reveal dl, .reveal dt, .reveal dd, .reveal ol, .reveal ul, .reveal li, 26 | .reveal fieldset, .reveal form, .reveal label, .reveal legend, 27 | .reveal table, .reveal caption, .reveal tbody, .reveal tfoot, .reveal thead, .reveal tr, .reveal th, .reveal td, 28 | .reveal article, .reveal aside, .reveal canvas, .reveal details, .reveal embed, 29 | .reveal figure, .reveal figcaption, .reveal footer, .reveal header, .reveal hgroup, 30 | .reveal menu, .reveal nav, .reveal output, .reveal ruby, .reveal section, .reveal summary, 31 | .reveal time, .reveal mark, .reveal audio, .reveal video { 32 | margin: 0; 33 | padding: 0; 34 | border: 0; 35 | font-size: 100%; 36 | font: inherit; 37 | vertical-align: baseline; } 38 | 39 | .reveal article, .reveal aside, .reveal details, .reveal figcaption, .reveal figure, 40 | .reveal footer, .reveal header, .reveal hgroup, .reveal menu, .reveal nav, .reveal section { 41 | display: block; } 42 | 43 | /********************************************* 44 | * VIEW FRAGMENTS 45 | *********************************************/ 46 | .reveal .slides section .fragment { 47 | opacity: 0; 48 | visibility: hidden; 49 | -webkit-transition: all .2s ease; 50 | transition: all .2s ease; } 51 | .reveal .slides section .fragment.visible { 52 | opacity: 1; 53 | visibility: visible; } 54 | 55 | .reveal .slides section .fragment.grow { 56 | opacity: 1; 57 | visibility: visible; } 58 | .reveal .slides section .fragment.grow.visible { 59 | -webkit-transform: scale(1.3); 60 | transform: scale(1.3); } 61 | 62 | .reveal .slides section .fragment.shrink { 63 | opacity: 1; 64 | visibility: visible; } 65 | .reveal .slides section .fragment.shrink.visible { 66 | -webkit-transform: scale(0.7); 67 | transform: scale(0.7); } 68 | 69 | .reveal .slides section .fragment.zoom-in { 70 | -webkit-transform: scale(0.1); 71 | transform: scale(0.1); } 72 | .reveal .slides section .fragment.zoom-in.visible { 73 | -webkit-transform: none; 74 | transform: none; } 75 | 76 | .reveal .slides section .fragment.fade-out { 77 | opacity: 1; 78 | visibility: visible; } 79 | .reveal .slides section .fragment.fade-out.visible { 80 | opacity: 0; 81 | visibility: hidden; } 82 | 83 | .reveal .slides section .fragment.semi-fade-out { 84 | opacity: 1; 85 | visibility: visible; } 86 | .reveal .slides section .fragment.semi-fade-out.visible { 87 | opacity: 0.5; 88 | visibility: visible; } 89 | 90 | .reveal .slides section .fragment.strike { 91 | opacity: 1; 92 | visibility: visible; } 93 | .reveal .slides section .fragment.strike.visible { 94 | text-decoration: line-through; } 95 | 96 | .reveal .slides section .fragment.fade-up { 97 | -webkit-transform: translate(0, 20%); 98 | transform: translate(0, 20%); } 99 | .reveal .slides section .fragment.fade-up.visible { 100 | -webkit-transform: translate(0, 0); 101 | transform: translate(0, 0); } 102 | 103 | .reveal .slides section .fragment.fade-down { 104 | -webkit-transform: translate(0, -20%); 105 | transform: translate(0, -20%); } 106 | .reveal .slides section .fragment.fade-down.visible { 107 | -webkit-transform: translate(0, 0); 108 | transform: translate(0, 0); } 109 | 110 | .reveal .slides section .fragment.fade-right { 111 | -webkit-transform: translate(-20%, 0); 112 | transform: translate(-20%, 0); } 113 | .reveal .slides section .fragment.fade-right.visible { 114 | -webkit-transform: translate(0, 0); 115 | transform: translate(0, 0); } 116 | 117 | .reveal .slides section .fragment.fade-left { 118 | -webkit-transform: translate(20%, 0); 119 | transform: translate(20%, 0); } 120 | .reveal .slides section .fragment.fade-left.visible { 121 | -webkit-transform: translate(0, 0); 122 | transform: translate(0, 0); } 123 | 124 | .reveal .slides section .fragment.current-visible { 125 | opacity: 0; 126 | visibility: hidden; } 127 | .reveal .slides section .fragment.current-visible.current-fragment { 128 | opacity: 1; 129 | visibility: visible; } 130 | 131 | .reveal .slides section .fragment.highlight-red, 132 | .reveal .slides section .fragment.highlight-current-red, 133 | .reveal .slides section .fragment.highlight-green, 134 | .reveal .slides section .fragment.highlight-current-green, 135 | .reveal .slides section .fragment.highlight-blue, 136 | .reveal .slides section .fragment.highlight-current-blue { 137 | opacity: 1; 138 | visibility: visible; } 139 | 140 | .reveal .slides section .fragment.highlight-red.visible { 141 | color: #ff2c2d; } 142 | 143 | .reveal .slides section .fragment.highlight-green.visible { 144 | color: #17ff2e; } 145 | 146 | .reveal .slides section .fragment.highlight-blue.visible { 147 | color: #1b91ff; } 148 | 149 | .reveal .slides section .fragment.highlight-current-red.current-fragment { 150 | color: #ff2c2d; } 151 | 152 | .reveal .slides section .fragment.highlight-current-green.current-fragment { 153 | color: #17ff2e; } 154 | 155 | .reveal .slides section .fragment.highlight-current-blue.current-fragment { 156 | color: #1b91ff; } 157 | 158 | /********************************************* 159 | * DEFAULT ELEMENT STYLES 160 | *********************************************/ 161 | /* Fixes issue in Chrome where italic fonts did not appear when printing to PDF */ 162 | .reveal:after { 163 | content: ''; 164 | font-style: italic; } 165 | 166 | .reveal iframe { 167 | z-index: 1; } 168 | 169 | /** Prevents layering issues in certain browser/transition combinations */ 170 | .reveal a { 171 | position: relative; } 172 | 173 | .reveal .stretch { 174 | max-width: none; 175 | max-height: none; } 176 | 177 | .reveal pre.stretch code { 178 | height: 100%; 179 | max-height: 100%; 180 | box-sizing: border-box; } 181 | 182 | /********************************************* 183 | * CONTROLS 184 | *********************************************/ 185 | .reveal .controls { 186 | display: none; 187 | position: fixed; 188 | width: 110px; 189 | height: 110px; 190 | z-index: 30; 191 | right: 10px; 192 | bottom: 10px; 193 | -webkit-user-select: none; } 194 | 195 | .reveal .controls button { 196 | padding: 0; 197 | position: absolute; 198 | opacity: 0.05; 199 | width: 0; 200 | height: 0; 201 | background-color: transparent; 202 | border: 12px solid transparent; 203 | -webkit-transform: scale(0.9999); 204 | transform: scale(0.9999); 205 | -webkit-transition: all 0.2s ease; 206 | transition: all 0.2s ease; 207 | -webkit-appearance: none; 208 | -webkit-tap-highlight-color: transparent; } 209 | 210 | .reveal .controls .enabled { 211 | opacity: 0.7; 212 | cursor: pointer; } 213 | 214 | .reveal .controls .enabled:active { 215 | margin-top: 1px; } 216 | 217 | .reveal .controls .navigate-left { 218 | top: 42px; 219 | border-right-width: 22px; 220 | border-right-color: #000; } 221 | 222 | .reveal .controls .navigate-left.fragmented { 223 | opacity: 0.3; } 224 | 225 | .reveal .controls .navigate-right { 226 | left: 74px; 227 | top: 42px; 228 | border-left-width: 22px; 229 | border-left-color: #000; } 230 | 231 | .reveal .controls .navigate-right.fragmented { 232 | opacity: 0.3; } 233 | 234 | .reveal .controls .navigate-up { 235 | left: 42px; 236 | border-bottom-width: 22px; 237 | border-bottom-color: #000; } 238 | 239 | .reveal .controls .navigate-up.fragmented { 240 | opacity: 0.3; } 241 | 242 | .reveal .controls .navigate-down { 243 | left: 42px; 244 | top: 74px; 245 | border-top-width: 22px; 246 | border-top-color: #000; } 247 | 248 | .reveal .controls .navigate-down.fragmented { 249 | opacity: 0.3; } 250 | 251 | /********************************************* 252 | * PROGRESS BAR 253 | *********************************************/ 254 | .reveal .progress { 255 | position: fixed; 256 | display: none; 257 | height: 3px; 258 | width: 100%; 259 | bottom: 0; 260 | left: 0; 261 | z-index: 10; 262 | background-color: rgba(0, 0, 0, 0.2); } 263 | 264 | .reveal .progress:after { 265 | content: ''; 266 | display: block; 267 | position: absolute; 268 | height: 20px; 269 | width: 100%; 270 | top: -20px; } 271 | 272 | .reveal .progress span { 273 | display: block; 274 | height: 100%; 275 | width: 0px; 276 | background-color: #000; 277 | -webkit-transition: width 800ms cubic-bezier(0.26, 0.86, 0.44, 0.985); 278 | transition: width 800ms cubic-bezier(0.26, 0.86, 0.44, 0.985); } 279 | 280 | /********************************************* 281 | * SLIDE NUMBER 282 | *********************************************/ 283 | .reveal .slide-number { 284 | position: fixed; 285 | display: block; 286 | right: 8px; 287 | bottom: 8px; 288 | z-index: 31; 289 | font-family: Helvetica, sans-serif; 290 | font-size: 12px; 291 | line-height: 1; 292 | color: #fff; 293 | background-color: rgba(0, 0, 0, 0.4); 294 | padding: 5px; } 295 | 296 | .reveal .slide-number-delimiter { 297 | margin: 0 3px; } 298 | 299 | /********************************************* 300 | * SLIDES 301 | *********************************************/ 302 | .reveal { 303 | position: relative; 304 | width: 100%; 305 | height: 100%; 306 | overflow: hidden; 307 | -ms-touch-action: none; 308 | touch-action: none; } 309 | 310 | .reveal .slides { 311 | position: absolute; 312 | width: 100%; 313 | height: 100%; 314 | top: 0; 315 | right: 0; 316 | bottom: 0; 317 | left: 0; 318 | margin: auto; 319 | overflow: visible; 320 | z-index: 1; 321 | text-align: center; 322 | -webkit-perspective: 600px; 323 | perspective: 600px; 324 | -webkit-perspective-origin: 50% 40%; 325 | perspective-origin: 50% 40%; } 326 | 327 | .reveal .slides > section { 328 | -ms-perspective: 600px; } 329 | 330 | .reveal .slides > section, 331 | .reveal .slides > section > section { 332 | display: none; 333 | position: absolute; 334 | width: 100%; 335 | padding: 20px 0px; 336 | z-index: 10; 337 | -webkit-transform-style: preserve-3d; 338 | transform-style: preserve-3d; 339 | -webkit-transition: -webkit-transform-origin 800ms cubic-bezier(0.26, 0.86, 0.44, 0.985), -webkit-transform 800ms cubic-bezier(0.26, 0.86, 0.44, 0.985), visibility 800ms cubic-bezier(0.26, 0.86, 0.44, 0.985), opacity 800ms cubic-bezier(0.26, 0.86, 0.44, 0.985); 340 | transition: transform-origin 800ms cubic-bezier(0.26, 0.86, 0.44, 0.985), transform 800ms cubic-bezier(0.26, 0.86, 0.44, 0.985), visibility 800ms cubic-bezier(0.26, 0.86, 0.44, 0.985), opacity 800ms cubic-bezier(0.26, 0.86, 0.44, 0.985); } 341 | 342 | /* Global transition speed settings */ 343 | .reveal[data-transition-speed="fast"] .slides section { 344 | -webkit-transition-duration: 400ms; 345 | transition-duration: 400ms; } 346 | 347 | .reveal[data-transition-speed="slow"] .slides section { 348 | -webkit-transition-duration: 1200ms; 349 | transition-duration: 1200ms; } 350 | 351 | /* Slide-specific transition speed overrides */ 352 | .reveal .slides section[data-transition-speed="fast"] { 353 | -webkit-transition-duration: 400ms; 354 | transition-duration: 400ms; } 355 | 356 | .reveal .slides section[data-transition-speed="slow"] { 357 | -webkit-transition-duration: 1200ms; 358 | transition-duration: 1200ms; } 359 | 360 | .reveal .slides > section.stack { 361 | padding-top: 0; 362 | padding-bottom: 0; } 363 | 364 | .reveal .slides > section.present, 365 | .reveal .slides > section > section.present { 366 | display: block; 367 | z-index: 11; 368 | opacity: 1; } 369 | 370 | .reveal.center, 371 | .reveal.center .slides, 372 | .reveal.center .slides section { 373 | min-height: 0 !important; } 374 | 375 | /* Don't allow interaction with invisible slides */ 376 | .reveal .slides > section.future, 377 | .reveal .slides > section > section.future, 378 | .reveal .slides > section.past, 379 | .reveal .slides > section > section.past { 380 | pointer-events: none; } 381 | 382 | .reveal.overview .slides > section, 383 | .reveal.overview .slides > section > section { 384 | pointer-events: auto; } 385 | 386 | .reveal .slides > section.past, 387 | .reveal .slides > section.future, 388 | .reveal .slides > section > section.past, 389 | .reveal .slides > section > section.future { 390 | opacity: 0; } 391 | 392 | /********************************************* 393 | * Mixins for readability of transitions 394 | *********************************************/ 395 | /********************************************* 396 | * SLIDE TRANSITION 397 | * Aliased 'linear' for backwards compatibility 398 | *********************************************/ 399 | .reveal.slide section { 400 | -webkit-backface-visibility: hidden; 401 | backface-visibility: hidden; } 402 | 403 | .reveal .slides > section[data-transition=slide].past, 404 | .reveal .slides > section[data-transition~=slide-out].past, 405 | .reveal.slide .slides > section:not([data-transition]).past { 406 | -webkit-transform: translate(-150%, 0); 407 | transform: translate(-150%, 0); } 408 | 409 | .reveal .slides > section[data-transition=slide].future, 410 | .reveal .slides > section[data-transition~=slide-in].future, 411 | .reveal.slide .slides > section:not([data-transition]).future { 412 | -webkit-transform: translate(150%, 0); 413 | transform: translate(150%, 0); } 414 | 415 | .reveal .slides > section > section[data-transition=slide].past, 416 | .reveal .slides > section > section[data-transition~=slide-out].past, 417 | .reveal.slide .slides > section > section:not([data-transition]).past { 418 | -webkit-transform: translate(0, -150%); 419 | transform: translate(0, -150%); } 420 | 421 | .reveal .slides > section > section[data-transition=slide].future, 422 | .reveal .slides > section > section[data-transition~=slide-in].future, 423 | .reveal.slide .slides > section > section:not([data-transition]).future { 424 | -webkit-transform: translate(0, 150%); 425 | transform: translate(0, 150%); } 426 | 427 | .reveal.linear section { 428 | -webkit-backface-visibility: hidden; 429 | backface-visibility: hidden; } 430 | 431 | .reveal .slides > section[data-transition=linear].past, 432 | .reveal .slides > section[data-transition~=linear-out].past, 433 | .reveal.linear .slides > section:not([data-transition]).past { 434 | -webkit-transform: translate(-150%, 0); 435 | transform: translate(-150%, 0); } 436 | 437 | .reveal .slides > section[data-transition=linear].future, 438 | .reveal .slides > section[data-transition~=linear-in].future, 439 | .reveal.linear .slides > section:not([data-transition]).future { 440 | -webkit-transform: translate(150%, 0); 441 | transform: translate(150%, 0); } 442 | 443 | .reveal .slides > section > section[data-transition=linear].past, 444 | .reveal .slides > section > section[data-transition~=linear-out].past, 445 | .reveal.linear .slides > section > section:not([data-transition]).past { 446 | -webkit-transform: translate(0, -150%); 447 | transform: translate(0, -150%); } 448 | 449 | .reveal .slides > section > section[data-transition=linear].future, 450 | .reveal .slides > section > section[data-transition~=linear-in].future, 451 | .reveal.linear .slides > section > section:not([data-transition]).future { 452 | -webkit-transform: translate(0, 150%); 453 | transform: translate(0, 150%); } 454 | 455 | /********************************************* 456 | * CONVEX TRANSITION 457 | * Aliased 'default' for backwards compatibility 458 | *********************************************/ 459 | .reveal .slides > section[data-transition=default].past, 460 | .reveal .slides > section[data-transition~=default-out].past, 461 | .reveal.default .slides > section:not([data-transition]).past { 462 | -webkit-transform: translate3d(-100%, 0, 0) rotateY(-90deg) translate3d(-100%, 0, 0); 463 | transform: translate3d(-100%, 0, 0) rotateY(-90deg) translate3d(-100%, 0, 0); } 464 | 465 | .reveal .slides > section[data-transition=default].future, 466 | .reveal .slides > section[data-transition~=default-in].future, 467 | .reveal.default .slides > section:not([data-transition]).future { 468 | -webkit-transform: translate3d(100%, 0, 0) rotateY(90deg) translate3d(100%, 0, 0); 469 | transform: translate3d(100%, 0, 0) rotateY(90deg) translate3d(100%, 0, 0); } 470 | 471 | .reveal .slides > section > section[data-transition=default].past, 472 | .reveal .slides > section > section[data-transition~=default-out].past, 473 | .reveal.default .slides > section > section:not([data-transition]).past { 474 | -webkit-transform: translate3d(0, -300px, 0) rotateX(70deg) translate3d(0, -300px, 0); 475 | transform: translate3d(0, -300px, 0) rotateX(70deg) translate3d(0, -300px, 0); } 476 | 477 | .reveal .slides > section > section[data-transition=default].future, 478 | .reveal .slides > section > section[data-transition~=default-in].future, 479 | .reveal.default .slides > section > section:not([data-transition]).future { 480 | -webkit-transform: translate3d(0, 300px, 0) rotateX(-70deg) translate3d(0, 300px, 0); 481 | transform: translate3d(0, 300px, 0) rotateX(-70deg) translate3d(0, 300px, 0); } 482 | 483 | .reveal .slides > section[data-transition=convex].past, 484 | .reveal .slides > section[data-transition~=convex-out].past, 485 | .reveal.convex .slides > section:not([data-transition]).past { 486 | -webkit-transform: translate3d(-100%, 0, 0) rotateY(-90deg) translate3d(-100%, 0, 0); 487 | transform: translate3d(-100%, 0, 0) rotateY(-90deg) translate3d(-100%, 0, 0); } 488 | 489 | .reveal .slides > section[data-transition=convex].future, 490 | .reveal .slides > section[data-transition~=convex-in].future, 491 | .reveal.convex .slides > section:not([data-transition]).future { 492 | -webkit-transform: translate3d(100%, 0, 0) rotateY(90deg) translate3d(100%, 0, 0); 493 | transform: translate3d(100%, 0, 0) rotateY(90deg) translate3d(100%, 0, 0); } 494 | 495 | .reveal .slides > section > section[data-transition=convex].past, 496 | .reveal .slides > section > section[data-transition~=convex-out].past, 497 | .reveal.convex .slides > section > section:not([data-transition]).past { 498 | -webkit-transform: translate3d(0, -300px, 0) rotateX(70deg) translate3d(0, -300px, 0); 499 | transform: translate3d(0, -300px, 0) rotateX(70deg) translate3d(0, -300px, 0); } 500 | 501 | .reveal .slides > section > section[data-transition=convex].future, 502 | .reveal .slides > section > section[data-transition~=convex-in].future, 503 | .reveal.convex .slides > section > section:not([data-transition]).future { 504 | -webkit-transform: translate3d(0, 300px, 0) rotateX(-70deg) translate3d(0, 300px, 0); 505 | transform: translate3d(0, 300px, 0) rotateX(-70deg) translate3d(0, 300px, 0); } 506 | 507 | /********************************************* 508 | * CONCAVE TRANSITION 509 | *********************************************/ 510 | .reveal .slides > section[data-transition=concave].past, 511 | .reveal .slides > section[data-transition~=concave-out].past, 512 | .reveal.concave .slides > section:not([data-transition]).past { 513 | -webkit-transform: translate3d(-100%, 0, 0) rotateY(90deg) translate3d(-100%, 0, 0); 514 | transform: translate3d(-100%, 0, 0) rotateY(90deg) translate3d(-100%, 0, 0); } 515 | 516 | .reveal .slides > section[data-transition=concave].future, 517 | .reveal .slides > section[data-transition~=concave-in].future, 518 | .reveal.concave .slides > section:not([data-transition]).future { 519 | -webkit-transform: translate3d(100%, 0, 0) rotateY(-90deg) translate3d(100%, 0, 0); 520 | transform: translate3d(100%, 0, 0) rotateY(-90deg) translate3d(100%, 0, 0); } 521 | 522 | .reveal .slides > section > section[data-transition=concave].past, 523 | .reveal .slides > section > section[data-transition~=concave-out].past, 524 | .reveal.concave .slides > section > section:not([data-transition]).past { 525 | -webkit-transform: translate3d(0, -80%, 0) rotateX(-70deg) translate3d(0, -80%, 0); 526 | transform: translate3d(0, -80%, 0) rotateX(-70deg) translate3d(0, -80%, 0); } 527 | 528 | .reveal .slides > section > section[data-transition=concave].future, 529 | .reveal .slides > section > section[data-transition~=concave-in].future, 530 | .reveal.concave .slides > section > section:not([data-transition]).future { 531 | -webkit-transform: translate3d(0, 80%, 0) rotateX(70deg) translate3d(0, 80%, 0); 532 | transform: translate3d(0, 80%, 0) rotateX(70deg) translate3d(0, 80%, 0); } 533 | 534 | /********************************************* 535 | * ZOOM TRANSITION 536 | *********************************************/ 537 | .reveal .slides section[data-transition=zoom], 538 | .reveal.zoom .slides section:not([data-transition]) { 539 | -webkit-transition-timing-function: ease; 540 | transition-timing-function: ease; } 541 | 542 | .reveal .slides > section[data-transition=zoom].past, 543 | .reveal .slides > section[data-transition~=zoom-out].past, 544 | .reveal.zoom .slides > section:not([data-transition]).past { 545 | visibility: hidden; 546 | -webkit-transform: scale(16); 547 | transform: scale(16); } 548 | 549 | .reveal .slides > section[data-transition=zoom].future, 550 | .reveal .slides > section[data-transition~=zoom-in].future, 551 | .reveal.zoom .slides > section:not([data-transition]).future { 552 | visibility: hidden; 553 | -webkit-transform: scale(0.2); 554 | transform: scale(0.2); } 555 | 556 | .reveal .slides > section > section[data-transition=zoom].past, 557 | .reveal .slides > section > section[data-transition~=zoom-out].past, 558 | .reveal.zoom .slides > section > section:not([data-transition]).past { 559 | -webkit-transform: translate(0, -150%); 560 | transform: translate(0, -150%); } 561 | 562 | .reveal .slides > section > section[data-transition=zoom].future, 563 | .reveal .slides > section > section[data-transition~=zoom-in].future, 564 | .reveal.zoom .slides > section > section:not([data-transition]).future { 565 | -webkit-transform: translate(0, 150%); 566 | transform: translate(0, 150%); } 567 | 568 | /********************************************* 569 | * CUBE TRANSITION 570 | *********************************************/ 571 | .reveal.cube .slides { 572 | -webkit-perspective: 1300px; 573 | perspective: 1300px; } 574 | 575 | .reveal.cube .slides section { 576 | padding: 30px; 577 | min-height: 700px; 578 | -webkit-backface-visibility: hidden; 579 | backface-visibility: hidden; 580 | box-sizing: border-box; } 581 | 582 | .reveal.center.cube .slides section { 583 | min-height: 0; } 584 | 585 | .reveal.cube .slides section:not(.stack):before { 586 | content: ''; 587 | position: absolute; 588 | display: block; 589 | width: 100%; 590 | height: 100%; 591 | left: 0; 592 | top: 0; 593 | background: rgba(0, 0, 0, 0.1); 594 | border-radius: 4px; 595 | -webkit-transform: translateZ(-20px); 596 | transform: translateZ(-20px); } 597 | 598 | .reveal.cube .slides section:not(.stack):after { 599 | content: ''; 600 | position: absolute; 601 | display: block; 602 | width: 90%; 603 | height: 30px; 604 | left: 5%; 605 | bottom: 0; 606 | background: none; 607 | z-index: 1; 608 | border-radius: 4px; 609 | box-shadow: 0px 95px 25px rgba(0, 0, 0, 0.2); 610 | -webkit-transform: translateZ(-90px) rotateX(65deg); 611 | transform: translateZ(-90px) rotateX(65deg); } 612 | 613 | .reveal.cube .slides > section.stack { 614 | padding: 0; 615 | background: none; } 616 | 617 | .reveal.cube .slides > section.past { 618 | -webkit-transform-origin: 100% 0%; 619 | transform-origin: 100% 0%; 620 | -webkit-transform: translate3d(-100%, 0, 0) rotateY(-90deg); 621 | transform: translate3d(-100%, 0, 0) rotateY(-90deg); } 622 | 623 | .reveal.cube .slides > section.future { 624 | -webkit-transform-origin: 0% 0%; 625 | transform-origin: 0% 0%; 626 | -webkit-transform: translate3d(100%, 0, 0) rotateY(90deg); 627 | transform: translate3d(100%, 0, 0) rotateY(90deg); } 628 | 629 | .reveal.cube .slides > section > section.past { 630 | -webkit-transform-origin: 0% 100%; 631 | transform-origin: 0% 100%; 632 | -webkit-transform: translate3d(0, -100%, 0) rotateX(90deg); 633 | transform: translate3d(0, -100%, 0) rotateX(90deg); } 634 | 635 | .reveal.cube .slides > section > section.future { 636 | -webkit-transform-origin: 0% 0%; 637 | transform-origin: 0% 0%; 638 | -webkit-transform: translate3d(0, 100%, 0) rotateX(-90deg); 639 | transform: translate3d(0, 100%, 0) rotateX(-90deg); } 640 | 641 | /********************************************* 642 | * PAGE TRANSITION 643 | *********************************************/ 644 | .reveal.page .slides { 645 | -webkit-perspective-origin: 0% 50%; 646 | perspective-origin: 0% 50%; 647 | -webkit-perspective: 3000px; 648 | perspective: 3000px; } 649 | 650 | .reveal.page .slides section { 651 | padding: 30px; 652 | min-height: 700px; 653 | box-sizing: border-box; } 654 | 655 | .reveal.page .slides section.past { 656 | z-index: 12; } 657 | 658 | .reveal.page .slides section:not(.stack):before { 659 | content: ''; 660 | position: absolute; 661 | display: block; 662 | width: 100%; 663 | height: 100%; 664 | left: 0; 665 | top: 0; 666 | background: rgba(0, 0, 0, 0.1); 667 | -webkit-transform: translateZ(-20px); 668 | transform: translateZ(-20px); } 669 | 670 | .reveal.page .slides section:not(.stack):after { 671 | content: ''; 672 | position: absolute; 673 | display: block; 674 | width: 90%; 675 | height: 30px; 676 | left: 5%; 677 | bottom: 0; 678 | background: none; 679 | z-index: 1; 680 | border-radius: 4px; 681 | box-shadow: 0px 95px 25px rgba(0, 0, 0, 0.2); 682 | -webkit-transform: translateZ(-90px) rotateX(65deg); } 683 | 684 | .reveal.page .slides > section.stack { 685 | padding: 0; 686 | background: none; } 687 | 688 | .reveal.page .slides > section.past { 689 | -webkit-transform-origin: 0% 0%; 690 | transform-origin: 0% 0%; 691 | -webkit-transform: translate3d(-40%, 0, 0) rotateY(-80deg); 692 | transform: translate3d(-40%, 0, 0) rotateY(-80deg); } 693 | 694 | .reveal.page .slides > section.future { 695 | -webkit-transform-origin: 100% 0%; 696 | transform-origin: 100% 0%; 697 | -webkit-transform: translate3d(0, 0, 0); 698 | transform: translate3d(0, 0, 0); } 699 | 700 | .reveal.page .slides > section > section.past { 701 | -webkit-transform-origin: 0% 0%; 702 | transform-origin: 0% 0%; 703 | -webkit-transform: translate3d(0, -40%, 0) rotateX(80deg); 704 | transform: translate3d(0, -40%, 0) rotateX(80deg); } 705 | 706 | .reveal.page .slides > section > section.future { 707 | -webkit-transform-origin: 0% 100%; 708 | transform-origin: 0% 100%; 709 | -webkit-transform: translate3d(0, 0, 0); 710 | transform: translate3d(0, 0, 0); } 711 | 712 | /********************************************* 713 | * FADE TRANSITION 714 | *********************************************/ 715 | .reveal .slides section[data-transition=fade], 716 | .reveal.fade .slides section:not([data-transition]), 717 | .reveal.fade .slides > section > section:not([data-transition]) { 718 | -webkit-transform: none; 719 | transform: none; 720 | -webkit-transition: opacity 0.5s; 721 | transition: opacity 0.5s; } 722 | 723 | .reveal.fade.overview .slides section, 724 | .reveal.fade.overview .slides > section > section { 725 | -webkit-transition: none; 726 | transition: none; } 727 | 728 | /********************************************* 729 | * NO TRANSITION 730 | *********************************************/ 731 | .reveal .slides section[data-transition=none], 732 | .reveal.none .slides section:not([data-transition]) { 733 | -webkit-transform: none; 734 | transform: none; 735 | -webkit-transition: none; 736 | transition: none; } 737 | 738 | /********************************************* 739 | * PAUSED MODE 740 | *********************************************/ 741 | .reveal .pause-overlay { 742 | position: fixed; 743 | top: 0; 744 | left: 0; 745 | width: 100%; 746 | height: 100%; 747 | background: black; 748 | visibility: hidden; 749 | opacity: 0; 750 | z-index: 100; 751 | -webkit-transition: all 1s ease; 752 | transition: all 1s ease; } 753 | 754 | .reveal.paused .pause-overlay { 755 | visibility: visible; 756 | opacity: 1; } 757 | 758 | /********************************************* 759 | * FALLBACK 760 | *********************************************/ 761 | .no-transforms { 762 | overflow-y: auto; } 763 | 764 | .no-transforms .reveal .slides { 765 | position: relative; 766 | width: 80%; 767 | height: auto !important; 768 | top: 0; 769 | left: 50%; 770 | margin: 0; 771 | text-align: center; } 772 | 773 | .no-transforms .reveal .controls, 774 | .no-transforms .reveal .progress { 775 | display: none !important; } 776 | 777 | .no-transforms .reveal .slides section { 778 | display: block !important; 779 | opacity: 1 !important; 780 | position: relative !important; 781 | height: auto; 782 | min-height: 0; 783 | top: 0; 784 | left: -50%; 785 | margin: 70px 0; 786 | -webkit-transform: none; 787 | transform: none; } 788 | 789 | .no-transforms .reveal .slides section section { 790 | left: 0; } 791 | 792 | .reveal .no-transition, 793 | .reveal .no-transition * { 794 | -webkit-transition: none !important; 795 | transition: none !important; } 796 | 797 | /********************************************* 798 | * PER-SLIDE BACKGROUNDS 799 | *********************************************/ 800 | .reveal .backgrounds { 801 | position: absolute; 802 | width: 100%; 803 | height: 100%; 804 | top: 0; 805 | left: 0; 806 | -webkit-perspective: 600px; 807 | perspective: 600px; } 808 | 809 | .reveal .slide-background { 810 | display: none; 811 | position: absolute; 812 | width: 100%; 813 | height: 100%; 814 | opacity: 0; 815 | visibility: hidden; 816 | background-color: transparent; 817 | background-position: 50% 50%; 818 | background-repeat: no-repeat; 819 | background-size: cover; 820 | -webkit-transition: all 800ms cubic-bezier(0.26, 0.86, 0.44, 0.985); 821 | transition: all 800ms cubic-bezier(0.26, 0.86, 0.44, 0.985); } 822 | 823 | .reveal .slide-background.stack { 824 | display: block; } 825 | 826 | .reveal .slide-background.present { 827 | opacity: 1; 828 | visibility: visible; } 829 | 830 | .print-pdf .reveal .slide-background { 831 | opacity: 1 !important; 832 | visibility: visible !important; } 833 | 834 | /* Video backgrounds */ 835 | .reveal .slide-background video { 836 | position: absolute; 837 | width: 100%; 838 | height: 100%; 839 | max-width: none; 840 | max-height: none; 841 | top: 0; 842 | left: 0; } 843 | 844 | /* Immediate transition style */ 845 | .reveal[data-background-transition=none] > .backgrounds .slide-background, 846 | .reveal > .backgrounds .slide-background[data-background-transition=none] { 847 | -webkit-transition: none; 848 | transition: none; } 849 | 850 | /* Slide */ 851 | .reveal[data-background-transition=slide] > .backgrounds .slide-background, 852 | .reveal > .backgrounds .slide-background[data-background-transition=slide] { 853 | opacity: 1; 854 | -webkit-backface-visibility: hidden; 855 | backface-visibility: hidden; } 856 | 857 | .reveal[data-background-transition=slide] > .backgrounds .slide-background.past, 858 | .reveal > .backgrounds .slide-background.past[data-background-transition=slide] { 859 | -webkit-transform: translate(-100%, 0); 860 | transform: translate(-100%, 0); } 861 | 862 | .reveal[data-background-transition=slide] > .backgrounds .slide-background.future, 863 | .reveal > .backgrounds .slide-background.future[data-background-transition=slide] { 864 | -webkit-transform: translate(100%, 0); 865 | transform: translate(100%, 0); } 866 | 867 | .reveal[data-background-transition=slide] > .backgrounds .slide-background > .slide-background.past, 868 | .reveal > .backgrounds .slide-background > .slide-background.past[data-background-transition=slide] { 869 | -webkit-transform: translate(0, -100%); 870 | transform: translate(0, -100%); } 871 | 872 | .reveal[data-background-transition=slide] > .backgrounds .slide-background > .slide-background.future, 873 | .reveal > .backgrounds .slide-background > .slide-background.future[data-background-transition=slide] { 874 | -webkit-transform: translate(0, 100%); 875 | transform: translate(0, 100%); } 876 | 877 | /* Convex */ 878 | .reveal[data-background-transition=convex] > .backgrounds .slide-background.past, 879 | .reveal > .backgrounds .slide-background.past[data-background-transition=convex] { 880 | opacity: 0; 881 | -webkit-transform: translate3d(-100%, 0, 0) rotateY(-90deg) translate3d(-100%, 0, 0); 882 | transform: translate3d(-100%, 0, 0) rotateY(-90deg) translate3d(-100%, 0, 0); } 883 | 884 | .reveal[data-background-transition=convex] > .backgrounds .slide-background.future, 885 | .reveal > .backgrounds .slide-background.future[data-background-transition=convex] { 886 | opacity: 0; 887 | -webkit-transform: translate3d(100%, 0, 0) rotateY(90deg) translate3d(100%, 0, 0); 888 | transform: translate3d(100%, 0, 0) rotateY(90deg) translate3d(100%, 0, 0); } 889 | 890 | .reveal[data-background-transition=convex] > .backgrounds .slide-background > .slide-background.past, 891 | .reveal > .backgrounds .slide-background > .slide-background.past[data-background-transition=convex] { 892 | opacity: 0; 893 | -webkit-transform: translate3d(0, -100%, 0) rotateX(90deg) translate3d(0, -100%, 0); 894 | transform: translate3d(0, -100%, 0) rotateX(90deg) translate3d(0, -100%, 0); } 895 | 896 | .reveal[data-background-transition=convex] > .backgrounds .slide-background > .slide-background.future, 897 | .reveal > .backgrounds .slide-background > .slide-background.future[data-background-transition=convex] { 898 | opacity: 0; 899 | -webkit-transform: translate3d(0, 100%, 0) rotateX(-90deg) translate3d(0, 100%, 0); 900 | transform: translate3d(0, 100%, 0) rotateX(-90deg) translate3d(0, 100%, 0); } 901 | 902 | /* Concave */ 903 | .reveal[data-background-transition=concave] > .backgrounds .slide-background.past, 904 | .reveal > .backgrounds .slide-background.past[data-background-transition=concave] { 905 | opacity: 0; 906 | -webkit-transform: translate3d(-100%, 0, 0) rotateY(90deg) translate3d(-100%, 0, 0); 907 | transform: translate3d(-100%, 0, 0) rotateY(90deg) translate3d(-100%, 0, 0); } 908 | 909 | .reveal[data-background-transition=concave] > .backgrounds .slide-background.future, 910 | .reveal > .backgrounds .slide-background.future[data-background-transition=concave] { 911 | opacity: 0; 912 | -webkit-transform: translate3d(100%, 0, 0) rotateY(-90deg) translate3d(100%, 0, 0); 913 | transform: translate3d(100%, 0, 0) rotateY(-90deg) translate3d(100%, 0, 0); } 914 | 915 | .reveal[data-background-transition=concave] > .backgrounds .slide-background > .slide-background.past, 916 | .reveal > .backgrounds .slide-background > .slide-background.past[data-background-transition=concave] { 917 | opacity: 0; 918 | -webkit-transform: translate3d(0, -100%, 0) rotateX(-90deg) translate3d(0, -100%, 0); 919 | transform: translate3d(0, -100%, 0) rotateX(-90deg) translate3d(0, -100%, 0); } 920 | 921 | .reveal[data-background-transition=concave] > .backgrounds .slide-background > .slide-background.future, 922 | .reveal > .backgrounds .slide-background > .slide-background.future[data-background-transition=concave] { 923 | opacity: 0; 924 | -webkit-transform: translate3d(0, 100%, 0) rotateX(90deg) translate3d(0, 100%, 0); 925 | transform: translate3d(0, 100%, 0) rotateX(90deg) translate3d(0, 100%, 0); } 926 | 927 | /* Zoom */ 928 | .reveal[data-background-transition=zoom] > .backgrounds .slide-background, 929 | .reveal > .backgrounds .slide-background[data-background-transition=zoom] { 930 | -webkit-transition-timing-function: ease; 931 | transition-timing-function: ease; } 932 | 933 | .reveal[data-background-transition=zoom] > .backgrounds .slide-background.past, 934 | .reveal > .backgrounds .slide-background.past[data-background-transition=zoom] { 935 | opacity: 0; 936 | visibility: hidden; 937 | -webkit-transform: scale(16); 938 | transform: scale(16); } 939 | 940 | .reveal[data-background-transition=zoom] > .backgrounds .slide-background.future, 941 | .reveal > .backgrounds .slide-background.future[data-background-transition=zoom] { 942 | opacity: 0; 943 | visibility: hidden; 944 | -webkit-transform: scale(0.2); 945 | transform: scale(0.2); } 946 | 947 | .reveal[data-background-transition=zoom] > .backgrounds .slide-background > .slide-background.past, 948 | .reveal > .backgrounds .slide-background > .slide-background.past[data-background-transition=zoom] { 949 | opacity: 0; 950 | visibility: hidden; 951 | -webkit-transform: scale(16); 952 | transform: scale(16); } 953 | 954 | .reveal[data-background-transition=zoom] > .backgrounds .slide-background > .slide-background.future, 955 | .reveal > .backgrounds .slide-background > .slide-background.future[data-background-transition=zoom] { 956 | opacity: 0; 957 | visibility: hidden; 958 | -webkit-transform: scale(0.2); 959 | transform: scale(0.2); } 960 | 961 | /* Global transition speed settings */ 962 | .reveal[data-transition-speed="fast"] > .backgrounds .slide-background { 963 | -webkit-transition-duration: 400ms; 964 | transition-duration: 400ms; } 965 | 966 | .reveal[data-transition-speed="slow"] > .backgrounds .slide-background { 967 | -webkit-transition-duration: 1200ms; 968 | transition-duration: 1200ms; } 969 | 970 | /********************************************* 971 | * OVERVIEW 972 | *********************************************/ 973 | .reveal.overview { 974 | -webkit-perspective-origin: 50% 50%; 975 | perspective-origin: 50% 50%; 976 | -webkit-perspective: 700px; 977 | perspective: 700px; } 978 | .reveal.overview .slides section { 979 | height: 100%; 980 | top: 0 !important; 981 | opacity: 1 !important; 982 | overflow: hidden; 983 | visibility: visible !important; 984 | cursor: pointer; 985 | box-sizing: border-box; } 986 | .reveal.overview .slides section:hover, 987 | .reveal.overview .slides section.present { 988 | outline: 10px solid rgba(150, 150, 150, 0.4); 989 | outline-offset: 10px; } 990 | .reveal.overview .slides section .fragment { 991 | opacity: 1; 992 | -webkit-transition: none; 993 | transition: none; } 994 | .reveal.overview .slides section:after, 995 | .reveal.overview .slides section:before { 996 | display: none !important; } 997 | .reveal.overview .slides > section.stack { 998 | padding: 0; 999 | top: 0 !important; 1000 | background: none; 1001 | outline: none; 1002 | overflow: visible; } 1003 | .reveal.overview .backgrounds { 1004 | -webkit-perspective: inherit; 1005 | perspective: inherit; } 1006 | .reveal.overview .backgrounds .slide-background { 1007 | opacity: 1; 1008 | visibility: visible; 1009 | outline: 10px solid rgba(150, 150, 150, 0.1); 1010 | outline-offset: 10px; } 1011 | 1012 | .reveal.overview .slides section, 1013 | .reveal.overview-deactivating .slides section { 1014 | -webkit-transition: none; 1015 | transition: none; } 1016 | 1017 | .reveal.overview .backgrounds .slide-background, 1018 | .reveal.overview-deactivating .backgrounds .slide-background { 1019 | -webkit-transition: none; 1020 | transition: none; } 1021 | 1022 | .reveal.overview-animated .slides { 1023 | -webkit-transition: -webkit-transform 0.4s ease; 1024 | transition: transform 0.4s ease; } 1025 | 1026 | /********************************************* 1027 | * RTL SUPPORT 1028 | *********************************************/ 1029 | .reveal.rtl .slides, 1030 | .reveal.rtl .slides h1, 1031 | .reveal.rtl .slides h2, 1032 | .reveal.rtl .slides h3, 1033 | .reveal.rtl .slides h4, 1034 | .reveal.rtl .slides h5, 1035 | .reveal.rtl .slides h6 { 1036 | direction: rtl; 1037 | font-family: sans-serif; } 1038 | 1039 | .reveal.rtl pre, 1040 | .reveal.rtl code { 1041 | direction: ltr; } 1042 | 1043 | .reveal.rtl ol, 1044 | .reveal.rtl ul { 1045 | text-align: right; } 1046 | 1047 | .reveal.rtl .progress span { 1048 | float: right; } 1049 | 1050 | /********************************************* 1051 | * LINK PREVIEW OVERLAY 1052 | *********************************************/ 1053 | .reveal .overlay { 1054 | position: absolute; 1055 | top: 0; 1056 | left: 0; 1057 | width: 100%; 1058 | height: 100%; 1059 | z-index: 1000; 1060 | background: rgba(0, 0, 0, 0.9); 1061 | opacity: 0; 1062 | visibility: hidden; 1063 | -webkit-transition: all 0.3s ease; 1064 | transition: all 0.3s ease; } 1065 | 1066 | .reveal .overlay.visible { 1067 | opacity: 1; 1068 | visibility: visible; } 1069 | 1070 | .reveal .overlay .spinner { 1071 | position: absolute; 1072 | display: block; 1073 | top: 50%; 1074 | left: 50%; 1075 | width: 32px; 1076 | height: 32px; 1077 | margin: -16px 0 0 -16px; 1078 | z-index: 10; 1079 | background-image: url(data:image/gif;base64,R0lGODlhIAAgAPMAAJmZmf%2F%2F%2F6%2Bvr8nJybW1tcDAwOjo6Nvb26ioqKOjo7Ozs%2FLy8vz8%2FAAAAAAAAAAAACH%2FC05FVFNDQVBFMi4wAwEAAAAh%2FhpDcmVhdGVkIHdpdGggYWpheGxvYWQuaW5mbwAh%2BQQJCgAAACwAAAAAIAAgAAAE5xDISWlhperN52JLhSSdRgwVo1ICQZRUsiwHpTJT4iowNS8vyW2icCF6k8HMMBkCEDskxTBDAZwuAkkqIfxIQyhBQBFvAQSDITM5VDW6XNE4KagNh6Bgwe60smQUB3d4Rz1ZBApnFASDd0hihh12BkE9kjAJVlycXIg7CQIFA6SlnJ87paqbSKiKoqusnbMdmDC2tXQlkUhziYtyWTxIfy6BE8WJt5YJvpJivxNaGmLHT0VnOgSYf0dZXS7APdpB309RnHOG5gDqXGLDaC457D1zZ%2FV%2FnmOM82XiHRLYKhKP1oZmADdEAAAh%2BQQJCgAAACwAAAAAIAAgAAAE6hDISWlZpOrNp1lGNRSdRpDUolIGw5RUYhhHukqFu8DsrEyqnWThGvAmhVlteBvojpTDDBUEIFwMFBRAmBkSgOrBFZogCASwBDEY%2FCZSg7GSE0gSCjQBMVG023xWBhklAnoEdhQEfyNqMIcKjhRsjEdnezB%2BA4k8gTwJhFuiW4dokXiloUepBAp5qaKpp6%2BHo7aWW54wl7obvEe0kRuoplCGepwSx2jJvqHEmGt6whJpGpfJCHmOoNHKaHx61WiSR92E4lbFoq%2BB6QDtuetcaBPnW6%2BO7wDHpIiK9SaVK5GgV543tzjgGcghAgAh%2BQQJCgAAACwAAAAAIAAgAAAE7hDISSkxpOrN5zFHNWRdhSiVoVLHspRUMoyUakyEe8PTPCATW9A14E0UvuAKMNAZKYUZCiBMuBakSQKG8G2FzUWox2AUtAQFcBKlVQoLgQReZhQlCIJesQXI5B0CBnUMOxMCenoCfTCEWBsJColTMANldx15BGs8B5wlCZ9Po6OJkwmRpnqkqnuSrayqfKmqpLajoiW5HJq7FL1Gr2mMMcKUMIiJgIemy7xZtJsTmsM4xHiKv5KMCXqfyUCJEonXPN2rAOIAmsfB3uPoAK%2B%2BG%2Bw48edZPK%2BM6hLJpQg484enXIdQFSS1u6UhksENEQAAIfkECQoAAAAsAAAAACAAIAAABOcQyEmpGKLqzWcZRVUQnZYg1aBSh2GUVEIQ2aQOE%2BG%2BcD4ntpWkZQj1JIiZIogDFFyHI0UxQwFugMSOFIPJftfVAEoZLBbcLEFhlQiqGp1Vd140AUklUN3eCA51C1EWMzMCezCBBmkxVIVHBWd3HHl9JQOIJSdSnJ0TDKChCwUJjoWMPaGqDKannasMo6WnM562R5YluZRwur0wpgqZE7NKUm%2BFNRPIhjBJxKZteWuIBMN4zRMIVIhffcgojwCF117i4nlLnY5ztRLsnOk%2BaV%2BoJY7V7m76PdkS4trKcdg0Zc0tTcKkRAAAIfkECQoAAAAsAAAAACAAIAAABO4QyEkpKqjqzScpRaVkXZWQEximw1BSCUEIlDohrft6cpKCk5xid5MNJTaAIkekKGQkWyKHkvhKsR7ARmitkAYDYRIbUQRQjWBwJRzChi9CRlBcY1UN4g0%2FVNB0AlcvcAYHRyZPdEQFYV8ccwR5HWxEJ02YmRMLnJ1xCYp0Y5idpQuhopmmC2KgojKasUQDk5BNAwwMOh2RtRq5uQuPZKGIJQIGwAwGf6I0JXMpC8C7kXWDBINFMxS4DKMAWVWAGYsAdNqW5uaRxkSKJOZKaU3tPOBZ4DuK2LATgJhkPJMgTwKCdFjyPHEnKxFCDhEAACH5BAkKAAAALAAAAAAgACAAAATzEMhJaVKp6s2nIkolIJ2WkBShpkVRWqqQrhLSEu9MZJKK9y1ZrqYK9WiClmvoUaF8gIQSNeF1Er4MNFn4SRSDARWroAIETg1iVwuHjYB1kYc1mwruwXKC9gmsJXliGxc%2BXiUCby9ydh1sOSdMkpMTBpaXBzsfhoc5l58Gm5yToAaZhaOUqjkDgCWNHAULCwOLaTmzswadEqggQwgHuQsHIoZCHQMMQgQGubVEcxOPFAcMDAYUA85eWARmfSRQCdcMe0zeP1AAygwLlJtPNAAL19DARdPzBOWSm1brJBi45soRAWQAAkrQIykShQ9wVhHCwCQCACH5BAkKAAAALAAAAAAgACAAAATrEMhJaVKp6s2nIkqFZF2VIBWhUsJaTokqUCoBq%2BE71SRQeyqUToLA7VxF0JDyIQh%2FMVVPMt1ECZlfcjZJ9mIKoaTl1MRIl5o4CUKXOwmyrCInCKqcWtvadL2SYhyASyNDJ0uIiRMDjI0Fd30%2FiI2UA5GSS5UDj2l6NoqgOgN4gksEBgYFf0FDqKgHnyZ9OX8HrgYHdHpcHQULXAS2qKpENRg7eAMLC7kTBaixUYFkKAzWAAnLC7FLVxLWDBLKCwaKTULgEwbLA4hJtOkSBNqITT3xEgfLpBtzE%2FjiuL04RGEBgwWhShRgQExHBAAh%2BQQJCgAAACwAAAAAIAAgAAAE7xDISWlSqerNpyJKhWRdlSAVoVLCWk6JKlAqAavhO9UkUHsqlE6CwO1cRdCQ8iEIfzFVTzLdRAmZX3I2SfZiCqGk5dTESJeaOAlClzsJsqwiJwiqnFrb2nS9kmIcgEsjQydLiIlHehhpejaIjzh9eomSjZR%2BipslWIRLAgMDOR2DOqKogTB9pCUJBagDBXR6XB0EBkIIsaRsGGMMAxoDBgYHTKJiUYEGDAzHC9EACcUGkIgFzgwZ0QsSBcXHiQvOwgDdEwfFs0sDzt4S6BK4xYjkDOzn0unFeBzOBijIm1Dgmg5YFQwsCMjp1oJ8LyIAACH5BAkKAAAALAAAAAAgACAAAATwEMhJaVKp6s2nIkqFZF2VIBWhUsJaTokqUCoBq%2BE71SRQeyqUToLA7VxF0JDyIQh%2FMVVPMt1ECZlfcjZJ9mIKoaTl1MRIl5o4CUKXOwmyrCInCKqcWtvadL2SYhyASyNDJ0uIiUd6GGl6NoiPOH16iZKNlH6KmyWFOggHhEEvAwwMA0N9GBsEC6amhnVcEwavDAazGwIDaH1ipaYLBUTCGgQDA8NdHz0FpqgTBwsLqAbWAAnIA4FWKdMLGdYGEgraigbT0OITBcg5QwPT4xLrROZL6AuQAPUS7bxLpoWidY0JtxLHKhwwMJBTHgPKdEQAACH5BAkKAAAALAAAAAAgACAAAATrEMhJaVKp6s2nIkqFZF2VIBWhUsJaTokqUCoBq%2BE71SRQeyqUToLA7VxF0JDyIQh%2FMVVPMt1ECZlfcjZJ9mIKoaTl1MRIl5o4CUKXOwmyrCInCKqcWtvadL2SYhyASyNDJ0uIiUd6GAULDJCRiXo1CpGXDJOUjY%2BYip9DhToJA4RBLwMLCwVDfRgbBAaqqoZ1XBMHswsHtxtFaH1iqaoGNgAIxRpbFAgfPQSqpbgGBqUD1wBXeCYp1AYZ19JJOYgH1KwA4UBvQwXUBxPqVD9L3sbp2BNk2xvvFPJd%2BMFCN6HAAIKgNggY0KtEBAAh%2BQQJCgAAACwAAAAAIAAgAAAE6BDISWlSqerNpyJKhWRdlSAVoVLCWk6JKlAqAavhO9UkUHsqlE6CwO1cRdCQ8iEIfzFVTzLdRAmZX3I2SfYIDMaAFdTESJeaEDAIMxYFqrOUaNW4E4ObYcCXaiBVEgULe0NJaxxtYksjh2NLkZISgDgJhHthkpU4mW6blRiYmZOlh4JWkDqILwUGBnE6TYEbCgevr0N1gH4At7gHiRpFaLNrrq8HNgAJA70AWxQIH1%2BvsYMDAzZQPC9VCNkDWUhGkuE5PxJNwiUK4UfLzOlD4WvzAHaoG9nxPi5d%2BjYUqfAhhykOFwJWiAAAIfkECQoAAAAsAAAAACAAIAAABPAQyElpUqnqzaciSoVkXVUMFaFSwlpOCcMYlErAavhOMnNLNo8KsZsMZItJEIDIFSkLGQoQTNhIsFehRww2CQLKF0tYGKYSg%2BygsZIuNqJksKgbfgIGepNo2cIUB3V1B3IvNiBYNQaDSTtfhhx0CwVPI0UJe0%2Bbm4g5VgcGoqOcnjmjqDSdnhgEoamcsZuXO1aWQy8KAwOAuTYYGwi7w5h%2BKr0SJ8MFihpNbx%2B4Erq7BYBuzsdiH1jCAzoSfl0rVirNbRXlBBlLX%2BBP0XJLAPGzTkAuAOqb0WT5AH7OcdCm5B8TgRwSRKIHQtaLCwg1RAAAOwAAAAAAAAAAAA%3D%3D); 1080 | visibility: visible; 1081 | opacity: 0.6; 1082 | -webkit-transition: all 0.3s ease; 1083 | transition: all 0.3s ease; } 1084 | 1085 | .reveal .overlay header { 1086 | position: absolute; 1087 | left: 0; 1088 | top: 0; 1089 | width: 100%; 1090 | height: 40px; 1091 | z-index: 2; 1092 | border-bottom: 1px solid #222; } 1093 | 1094 | .reveal .overlay header a { 1095 | display: inline-block; 1096 | width: 40px; 1097 | height: 40px; 1098 | padding: 0 10px; 1099 | float: right; 1100 | opacity: 0.6; 1101 | box-sizing: border-box; } 1102 | 1103 | .reveal .overlay header a:hover { 1104 | opacity: 1; } 1105 | 1106 | .reveal .overlay header a .icon { 1107 | display: inline-block; 1108 | width: 20px; 1109 | height: 20px; 1110 | background-position: 50% 50%; 1111 | background-size: 100%; 1112 | background-repeat: no-repeat; } 1113 | 1114 | .reveal .overlay header a.close .icon { 1115 | background-image: url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAABkklEQVRYR8WX4VHDMAxG6wnoJrABZQPYBCaBTWAD2g1gE5gg6OOsXuxIlr40d81dfrSJ9V4c2VLK7spHuTJ/5wpM07QXuXc5X0opX2tEJcadjHuV80li/FgxTIEK/5QBCICBD6xEhSMGHgQPgBgLiYVAB1dpSqKDawxTohFw4JSEA3clzgIBPCURwE2JucBR7rhPJJv5OpJwDX+SfDjgx1wACQeJG1aChP9K/IMmdZ8DtESV1WyP3Bt4MwM6sj4NMxMYiqUWHQu4KYA/SYkIjOsm3BXYWMKFDwU2khjCQ4ELJUJ4SmClRArOCmSXGuKma0fYD5CbzHxFpCSGAhfAVSSUGDUk2BWZaff2g6GE15BsBQ9nwmpIGDiyHQddwNTMKkbZaf9fajXQca1EX44puJZUsnY0ObGmITE3GVLCbEhQUjGVt146j6oasWN+49Vph2w1pZ5EansNZqKBm1txbU57iRRcZ86RWMDdWtBJUHBHwoQPi1GV+JCbntmvok7iTX4/Up9mgyTc/FJYDTcndgH/AA5A/CHsyEkVAAAAAElFTkSuQmCC); } 1116 | 1117 | .reveal .overlay header a.external .icon { 1118 | background-image: url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAAcElEQVRYR+2WSQoAIQwEzf8f7XiOMkUQxUPlGkM3hVmiQfQR9GYnH1SsAQlI4DiBqkCMoNb9y2e90IAEJPAcgdznU9+engMaeJ7Azh5Y1U67gAho4DqBqmB1buAf0MB1AlVBek83ZPkmJMGc1wAR+AAqod/B97TRpQAAAABJRU5ErkJggg==); } 1119 | 1120 | .reveal .overlay .viewport { 1121 | position: absolute; 1122 | display: -webkit-box; 1123 | display: -webkit-flex; 1124 | display: -ms-flexbox; 1125 | display: flex; 1126 | top: 40px; 1127 | right: 0; 1128 | bottom: 0; 1129 | left: 0; } 1130 | 1131 | .reveal .overlay.overlay-preview .viewport iframe { 1132 | width: 100%; 1133 | height: 100%; 1134 | max-width: 100%; 1135 | max-height: 100%; 1136 | border: 0; 1137 | opacity: 0; 1138 | visibility: hidden; 1139 | -webkit-transition: all 0.3s ease; 1140 | transition: all 0.3s ease; } 1141 | 1142 | .reveal .overlay.overlay-preview.loaded .viewport iframe { 1143 | opacity: 1; 1144 | visibility: visible; } 1145 | 1146 | .reveal .overlay.overlay-preview.loaded .spinner { 1147 | opacity: 0; 1148 | visibility: hidden; 1149 | -webkit-transform: scale(0.2); 1150 | transform: scale(0.2); } 1151 | 1152 | .reveal .overlay.overlay-help .viewport { 1153 | overflow: auto; 1154 | color: #fff; } 1155 | 1156 | .reveal .overlay.overlay-help .viewport .viewport-inner { 1157 | width: 600px; 1158 | margin: auto; 1159 | padding: 20px 20px 80px 20px; 1160 | text-align: center; 1161 | letter-spacing: normal; } 1162 | 1163 | .reveal .overlay.overlay-help .viewport .viewport-inner .title { 1164 | font-size: 20px; } 1165 | 1166 | .reveal .overlay.overlay-help .viewport .viewport-inner table { 1167 | border: 1px solid #fff; 1168 | border-collapse: collapse; 1169 | font-size: 16px; } 1170 | 1171 | .reveal .overlay.overlay-help .viewport .viewport-inner table th, 1172 | .reveal .overlay.overlay-help .viewport .viewport-inner table td { 1173 | width: 200px; 1174 | padding: 14px; 1175 | border: 1px solid #fff; 1176 | vertical-align: middle; } 1177 | 1178 | .reveal .overlay.overlay-help .viewport .viewport-inner table th { 1179 | padding-top: 20px; 1180 | padding-bottom: 20px; } 1181 | 1182 | /********************************************* 1183 | * PLAYBACK COMPONENT 1184 | *********************************************/ 1185 | .reveal .playback { 1186 | position: fixed; 1187 | left: 15px; 1188 | bottom: 20px; 1189 | z-index: 30; 1190 | cursor: pointer; 1191 | -webkit-transition: all 400ms ease; 1192 | transition: all 400ms ease; } 1193 | 1194 | .reveal.overview .playback { 1195 | opacity: 0; 1196 | visibility: hidden; } 1197 | 1198 | /********************************************* 1199 | * ROLLING LINKS 1200 | *********************************************/ 1201 | .reveal .roll { 1202 | display: inline-block; 1203 | line-height: 1.2; 1204 | overflow: hidden; 1205 | vertical-align: top; 1206 | -webkit-perspective: 400px; 1207 | perspective: 400px; 1208 | -webkit-perspective-origin: 50% 50%; 1209 | perspective-origin: 50% 50%; } 1210 | 1211 | .reveal .roll:hover { 1212 | background: none; 1213 | text-shadow: none; } 1214 | 1215 | .reveal .roll span { 1216 | display: block; 1217 | position: relative; 1218 | padding: 0 2px; 1219 | pointer-events: none; 1220 | -webkit-transition: all 400ms ease; 1221 | transition: all 400ms ease; 1222 | -webkit-transform-origin: 50% 0%; 1223 | transform-origin: 50% 0%; 1224 | -webkit-transform-style: preserve-3d; 1225 | transform-style: preserve-3d; 1226 | -webkit-backface-visibility: hidden; 1227 | backface-visibility: hidden; } 1228 | 1229 | .reveal .roll:hover span { 1230 | background: rgba(0, 0, 0, 0.5); 1231 | -webkit-transform: translate3d(0px, 0px, -45px) rotateX(90deg); 1232 | transform: translate3d(0px, 0px, -45px) rotateX(90deg); } 1233 | 1234 | .reveal .roll span:after { 1235 | content: attr(data-title); 1236 | display: block; 1237 | position: absolute; 1238 | left: 0; 1239 | top: 0; 1240 | padding: 0 2px; 1241 | -webkit-backface-visibility: hidden; 1242 | backface-visibility: hidden; 1243 | -webkit-transform-origin: 50% 0%; 1244 | transform-origin: 50% 0%; 1245 | -webkit-transform: translate3d(0px, 110%, 0px) rotateX(-90deg); 1246 | transform: translate3d(0px, 110%, 0px) rotateX(-90deg); } 1247 | -------------------------------------------------------------------------------- /fonts/lato/LatoLatin-Bold.eot: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/fonts/lato/LatoLatin-Bold.eot -------------------------------------------------------------------------------- /fonts/lato/LatoLatin-Bold.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/fonts/lato/LatoLatin-Bold.ttf -------------------------------------------------------------------------------- /fonts/lato/LatoLatin-Bold.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/fonts/lato/LatoLatin-Bold.woff -------------------------------------------------------------------------------- /fonts/lato/LatoLatin-BoldItalic.eot: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/fonts/lato/LatoLatin-BoldItalic.eot -------------------------------------------------------------------------------- /fonts/lato/LatoLatin-BoldItalic.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/fonts/lato/LatoLatin-BoldItalic.ttf -------------------------------------------------------------------------------- /fonts/lato/LatoLatin-BoldItalic.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/fonts/lato/LatoLatin-BoldItalic.woff -------------------------------------------------------------------------------- /fonts/lato/LatoLatin-Italic.eot: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/fonts/lato/LatoLatin-Italic.eot -------------------------------------------------------------------------------- /fonts/lato/LatoLatin-Italic.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/fonts/lato/LatoLatin-Italic.ttf -------------------------------------------------------------------------------- /fonts/lato/LatoLatin-Italic.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/fonts/lato/LatoLatin-Italic.woff -------------------------------------------------------------------------------- /fonts/lato/LatoLatin-Regular.eot: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/fonts/lato/LatoLatin-Regular.eot -------------------------------------------------------------------------------- /fonts/lato/LatoLatin-Regular.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/fonts/lato/LatoLatin-Regular.ttf -------------------------------------------------------------------------------- /fonts/lato/LatoLatin-Regular.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/fonts/lato/LatoLatin-Regular.woff -------------------------------------------------------------------------------- /fonts/lato/LatoLatinLight-Italic.eot: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/fonts/lato/LatoLatinLight-Italic.eot -------------------------------------------------------------------------------- /fonts/lato/LatoLatinLight-Italic.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/fonts/lato/LatoLatinLight-Italic.ttf -------------------------------------------------------------------------------- /fonts/lato/LatoLatinLight-Italic.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/fonts/lato/LatoLatinLight-Italic.woff -------------------------------------------------------------------------------- /fonts/lato/LatoLatinLight-Regular.eot: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/fonts/lato/LatoLatinLight-Regular.eot -------------------------------------------------------------------------------- /fonts/lato/LatoLatinLight-Regular.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/fonts/lato/LatoLatinLight-Regular.ttf -------------------------------------------------------------------------------- /fonts/lato/LatoLatinLight-Regular.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/fonts/lato/LatoLatinLight-Regular.woff -------------------------------------------------------------------------------- /images/aglio-example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/images/aglio-example.png -------------------------------------------------------------------------------- /images/aglio.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/images/aglio.png -------------------------------------------------------------------------------- /images/apiary-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/images/apiary-1.png -------------------------------------------------------------------------------- /images/apiary-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/images/apiary-2.png -------------------------------------------------------------------------------- /images/apiblueprint.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/images/apiblueprint.png -------------------------------------------------------------------------------- /images/apiplatform.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/images/apiplatform.png -------------------------------------------------------------------------------- /images/application-state.svg: -------------------------------------------------------------------------------- 1 | 2 | 4 | 6 | 7 | 9 | 10 | AppState 11 | 12 | [null] 13 | 14 | [null] 15 | 16 | 17 | Homepage 18 | 19 | Homepage 20 | 21 | 22 | [null]->Homepage 23 | 24 | 25 | GET / 26 | 27 | 28 | User list 29 | 30 | User list 31 | 32 | 33 | Homepage->User list 34 | 35 | 36 | GET /users 37 | 38 | 39 | User list->User list 40 | 41 | 42 | POST /users 43 | 44 | 45 | User #123 46 | 47 | User #123 48 | 49 | 50 | User list->User #123 51 | 52 | 53 | GET /users/123 54 | 55 | 56 | 57 | -------------------------------------------------------------------------------- /images/drakov.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/images/drakov.gif -------------------------------------------------------------------------------- /images/dredd.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/images/dredd.png -------------------------------------------------------------------------------- /images/graphql.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/images/graphql.png -------------------------------------------------------------------------------- /images/hurlit.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/images/hurlit.png -------------------------------------------------------------------------------- /images/jsonapi.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/images/jsonapi.png -------------------------------------------------------------------------------- /images/mmmh.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/images/mmmh.png -------------------------------------------------------------------------------- /images/nope.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/images/nope.gif -------------------------------------------------------------------------------- /images/oai.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/images/oai.png -------------------------------------------------------------------------------- /images/postman.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/images/postman.png -------------------------------------------------------------------------------- /images/resource-state.svg: -------------------------------------------------------------------------------- 1 | 2 | 4 | 6 | 7 | 9 | 10 | ResourceState 11 | cluster0 12 | 13 | Initial state 14 | 15 | cluster1 16 | 17 | New state 18 | 19 | 20 | homepage1 21 | 22 | Homepage 23 | 24 | 25 | homepage1->homepage1 26 | 27 | 28 | GET / 29 | 30 | 31 | User list (2 users) 32 | 33 | User list (2 users) 34 | 35 | 36 | User list (2 users)->User list (2 users) 37 | 38 | 39 | GET /users 40 | 41 | 42 | User list (3 users) 43 | 44 | User list (3 users) 45 | 46 | 47 | User list (2 users)->User list (3 users) 48 | 49 | 50 | POST 51 | 52 | 53 | Homepage 54 | 55 | Homepage 56 | 57 | 58 | Homepage->Homepage 59 | 60 | 61 | GET / 62 | 63 | 64 | User list (3 users)->User list (3 users) 65 | 66 | 67 | GET /users 68 | 69 | 70 | 71 | -------------------------------------------------------------------------------- /images/rmm.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/images/rmm.png -------------------------------------------------------------------------------- /images/trump.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/images/trump.png -------------------------------------------------------------------------------- /images/twitter-example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/willdurand-slides/pragmatic-apis-101/ad746396ba2dbb04a20d073e15a01a7a64c6f9a9/images/twitter-example.png -------------------------------------------------------------------------------- /index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | William Durand 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 25 | 26 | 27 | 28 |
29 |
30 |
35 |
36 |
37 |
38 | 39 | 40 | 41 | 42 | 59 | 60 | 61 | -------------------------------------------------------------------------------- /monod.md: -------------------------------------------------------------------------------- 1 | # Pragmatic APIs 101 2 | 3 | _William Durand — October 29th, 2016 — Symfony Camp :ua:_ 4 | 5 | --- 6 | 7 | ## What's REST? 8 | 9 | ---- 10 | 11 | ### REpresentational State Transfer 12 | 13 | REST is the underlying architectural principle of the web. 14 | 15 | It is formalized as a set of constraints, described in **Roy Fielding**'s PhD dissertation. 16 | 17 | ---- 18 | 19 | ### Richardson Maturity Model 20 | 21 | ![](http://localhost:8000/images/rmm.png) 22 | 23 | ---- 24 | 25 | ### Levels 0, 1, and 2 26 | 27 | * It is all about **resources** 28 | * **Client** uses specific HTTP **verbs** 29 | * **Server** uses HTTP **status codes** 30 | * Content Negotiation 31 | 32 | ---- 33 | 34 | ### Level 3 - Hypermedia Controls 35 | 36 | * Service discovery via **relations** 37 | * **Hypermedia** formats (e.g. _HTML_, _HAL_, _JSONAPI_) 38 | * Resources are not important, their **representations** are! 39 | * URI design does **not** matter (URI template) 40 | * **Client's experience** is crucial! 41 | * Protocol & **application semantics** 42 | 43 | ---- 44 | 45 | ### HATEOAS 46 | 47 | **H**ypermedia **A**s **T**he **E**ngine **O**f **A**pplication **S**tate 48 |
49 |
50 | 51 | It means that hypermedia should be used to find your 52 |
way through the API. It is all about **state 53 | transitions**. 54 | 55 | Your application is just a big **state machine**. 56 | 57 | ---- 58 | 59 | ### Resource vs Representation 60 | 61 | A **resource** can be anything, and can have more than one representation. A **representation** describes resource state. 62 | 63 | ---- 64 | 65 | ### Protocol Semantics 66 | 67 | How the underlying resource should behave under HTTP? 68 | 69 | ---- 70 | 71 | ### Application Semantics 72 | 73 | What, **specifically**, will happen to the 74 |
application or resource state? 75 | 76 | ---- 77 | 78 | ### The Semantic Challenge* 79 | 80 | Some standards have a good protocol-level 81 | semantics but no application-level 82 | semantics (_Collection+JSON_, _Atom_). 83 |
84 |
85 | Some standards define a lot of application-level semantics but no protocol semantics (_Microformats_, _Microdata_). 86 | 87 |
88 | :::small 89 | * = as described in Richardson and Amundsen's “RESTful Web APIs” book 90 | ::: 91 | 92 | ---- 93 | 94 | ### Profiles 95 | 96 | A **profile** is **defined** to not alter the semantics of the
resource representation 97 | itself, but **to allow clients to
learn about additional semantics**, [RFC 6906](https://tools.ietf.org/html/rfc6906). 98 |
99 |
100 | Does not have to be **machine-readable** but recommended. 101 | 102 | ---- 103 | 104 | ### Examples 105 | 106 | * Traditional API documentation 107 | * _XMDP_ (for _XHTML_ documents) 108 | * _**ALPS**_ (_XMDP_ on steroids) 109 | * Embedded doc. (as in _HAL_/_Siren_) 110 | * _JSON-LD_, _**JSON Schema**_ 111 | 112 | --- 113 | 114 | ## State Of The ~~Art~~ Industry 115 | 116 | ---- 117 | 118 | ### We all want RESTful APIs 119 | 120 | ---- 121 | 122 | ![](http://localhost:8000/images/twitter-example.png) 123 | 124 | ### Yes. 125 | 126 | ---- 127 | 128 | ### Is My API RESTful When I Use JSON? 129 | 130 | _[Short answer: **no**. Long answer: no, not yet. 131 |
RESTful API must use hypermedia formats. JSON is 132 |
**not** a hypermedia format](http://restcookbook.com/Mediatypes/json/), 133 | The REST CookBook_. 134 | 135 | ---- 136 | 137 | ### No Relations = No REST 138 | 139 | _[If the engine of application state (and hence the 140 | API) 141 |
is not being driven by hypertext, then it 142 | cannot be 143 |
RESTful and cannot be a REST API](http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven), Roy Fielding_. 144 | 145 | ---- 146 | 147 | ### s/REST/HTTP++/ 148 | 149 | REST APIs are a myth, _i.e._ too complex in real life. 150 | 151 |
152 | 153 | _[99.99% of the RESTful APIs out there aren’t fully 154 | compliant
with Roy Fielding’s conception of 155 | REST](http://www.timelessrepo.com/haters-gonna-hateoas), Steve Klabnik_. 156 | 157 | ---- 158 | 159 | ### Are we all screwed and should
we all jump to GraphQL? 160 | 161 | ---- 162 | 163 | ### Nope. 164 | 165 | --- 166 | 167 | ## The Pragmatic Way 168 | 169 | Well-designed, pragmatic, and future-proof APIs. 170 | 171 | ![](http://localhost:8000/images/trump.png) 172 | {no-border} 173 | 174 | --- 175 | 176 | ## :fa-book: Documentation 177 | 178 | ---- 179 | 180 | ### API Blueprint
![](http://localhost:8000/images/apiblueprint.png){no-border} 181 | 182 | ---- 183 | 184 | ### Apiary
![](http://localhost:8000/images/apiary-1.png){no-border} 185 | 186 | ---- 187 | 188 | ### Apiary
![](http://localhost:8000/images/apiary-2.png){no-border} 189 | 190 | ---- 191 | 192 | ### Aglio
![](http://localhost:8000/images/aglio-example.png){no-border} 193 | 194 | ---- 195 | 196 | ### Moooocks! 197 | 198 | (Apiary / [Drakov](https://github.com/Aconex/drakov))
![](http://localhost:8000/images/drakov.gif) 199 | 200 | ---- 201 | 202 | ### JSON Schema 203 | 204 | (Apiary / Aglio thanks to [MSON](https://help.apiary.io/api_101/mson-tutorial/)) 205 | 206 | ``` 207 | + Attributes 208 | + data (object) 209 | + id: `123` (string, required) - The identifier 210 | ``` 211 | 212 | ``` json 213 | { 214 | "$schema": "http://json-schema.org/draft-04/schema#", 215 | "type": "object", 216 | "properties": { 217 | "data": { 218 | "type": "object", 219 | "properties": { 220 | "id": { "type": "string", "description": "The identifier" } 221 | }, 222 | "required": [ "id" ] 223 | } 224 | } 225 | } 226 | ``` 227 | 228 | ---- 229 | 230 | ![](http://localhost:8000/images/oai.png) 231 | {no-border} 232 | 233 | (ex-Swagger) 234 | 235 | ---- 236 | 237 | ### Symfony/PHP 238 | 239 | * NelmioApiDocBundle ([#900](https://github.com/nelmio/NelmioApiDocBundle/issues/900)) 240 | * [A Tool to Convert NelmioApiDocBundle to Swagger PHP](https://blog.liip.ch/archive/2016/05/11/convert-nelmioapidocbundle-to-swagger-php.html) by Liip (blog post) 241 | * [Jane](https://github.com/janephp/jane) (JSON Schema) and [Jane Open Api](https://github.com/janephp/openapi) (Open API) 242 | 243 | ---- 244 | 245 | ### Advices 246 | 247 | * Write documentation first, then code 248 | * Must be under version control 249 | * Test your documentation (build / [Dredd](https://github.com/apiaryio/dredd)) 250 | 251 | 252 | --- 253 | 254 | ## :fa-code: Code 255 | 256 | ---- 257 | 258 | ### Symfony/PHP 259 | 260 | * [Symfony REST Edition](https://github.com/gimler/symfony-rest-edition) = Great for HTTP++ APIs 261 | 262 | * [FOSRestBundle](https://github.com/FriendsOfSymfony/FOSRestBundle) + [Hateoas](https://github.com/willdurand/Hateoas) = HAL 263 | 264 | * [Fractal](https://github.com/thephpleague/fractal), [Negotiation](https://github.com/willdurand/Negotiation), etc. 265 | 266 | ---- 267 | 268 | ![](http://localhost:8000/images/apiplatform.png) 269 | {no-border} 270 | 271 | ---- 272 | 273 | ![](http://localhost:8000/images/jsonapi.png) 274 | {no-border} 275 | 276 | ---- 277 | 278 | ### JSON API 279 | 280 | `application/vnd.api+json` 281 | 282 | ``` json 283 | { 284 | "data": { 285 | "id": "41c6cf", 286 | "type": "sequence", 287 | "attributes": { 288 | "name": "> Demo 1", 289 | "sequence": "ATCGAATCGGTTTAAAATCGATTCCCGAAAA" 290 | } 291 | }, 292 | "links": { 293 | "parent": "/data/27d99b56", 294 | "self": "/data/27d99b56/41c6cf", 295 | "source": "https://example.org/demo-sequence.fasta", 296 | "profile": "/profiles/data/sequence" 297 | } 298 | } 299 | ``` 300 | 301 | ---- 302 | 303 | ### Errors 304 | 305 | ``` json 306 | { 307 | "errors": [ 308 | { 309 | "code": "404", 310 | "status": "404", 311 | "title": "Not Found", 312 | "detail": "The URL you are trying to reach does not exist.", 313 | "links": { 314 | "about": "https://httpstatuses.com/404", 315 | "profile": "/profiles/errors" 316 | } 317 | } 318 | ] 319 | } 320 | ``` 321 | 322 | ---- 323 | 324 | ### Update with ~~PUT~~ PATCH 325 | 326 | ``` 327 | PATCH /upload/jobs/27d99b56-9327-4d28-a69c-31229bf971aa 328 | 329 | Content-Type: application/vnd.api+json 330 | Accept: application/vnd.api+json 331 | ``` 332 | ``` json 333 | // /!\ request payload below 334 | { 335 | "data": { 336 | "id": "27d99b56-9327-4d28-a69c-31229bf971aa", 337 | "type": "upload-jobs", 338 | "attributes": { 339 | "data_type": "sequence", 340 | "file_type": "fasta" 341 | } 342 | } 343 | } 344 | ``` 345 | 346 | (Yes... I wrote about [PATCH'ing correctly](http://williamdurand.fr/2014/02/14/please-do-not-patch-like-an-idiot/)) 347 | 348 | ---- 349 | 350 | ### Sparse Fieldsets :fa-heart: 351 | with the `fields` query parameter 352 | 353 | ``` 354 | GET /data/27d99b56?fields[sequence]=name 355 | 356 | Accept: application/vnd.api+json 357 | ``` 358 | 359 | ``` json 360 | "data": [ 361 | { 362 | "id": "41c6cf", 363 | "type": "sequence", 364 | "attributes": { "name": "> Demo 1" } 365 | }, 366 | { 367 | "id": "787ff2", 368 | "type": "sequence", 369 | "attributes": { "name": "> Seq. 2" } 370 | } 371 | ] 372 | ``` 373 | 374 | ---- 375 | 376 | ### Filtering 377 | with the `filter` query parameter 378 | 379 | ``` 380 | GET /data/27d99b56?fields[sequence]=sequence \ 381 | &filter={"name": { "$regex": "/demo/", "$options": "i"}} 382 | 383 | Accept: application/vnd.api+json 384 | ``` 385 | ``` json 386 | "data": [ 387 | { 388 | "id": "41c6cf", 389 | "type": "sequence", 390 | "attributes": { 391 | "sequence": "ATCGAATCGGTTTAAAATCGATTCCCGAAAA" 392 | } 393 | } 394 | ] 395 | ``` 396 | 397 | ---- 398 | 399 | ### Pagination 400 | with the `page` query parameter 401 | 402 | ``` 403 | { 404 | "data": [ ... ], 405 | "links": { 406 | "next": "/data/8f7d5ef1?page[cursor]=57de7ff7&page[limit]=1", 407 | "prev": "/data/8f7d5ef1?page[cursor]=-57de7ff7&page[limit]=1" 408 | }, 409 | "meta": { 410 | "page": { 411 | "after": "57de7ff7", 412 | "before": "-57de7ff7", 413 | "count": 3138, 414 | "limit": 1 415 | } 416 | } 417 | } 418 | ``` 419 | 420 | ---- 421 | 422 | ### Inclusion 423 | with the `include` query parameter 424 | 425 | ``` 426 | GET /data/27d99b56?include=ANYTHING 427 | 428 | Accept: application/vnd.api+json 429 | ``` 430 | ```json 431 | { 432 | "data": [ ... ], 433 | "included": [ 434 | ANYTHING 435 | ] 436 | } 437 | ``` 438 | 439 | ---- 440 | 441 | ### Asynchronous Processing (1/3) 442 | 443 | ``` 444 | POST /upload 445 | 446 | Content-Length: 87 447 | Content-Type: text/csv 448 | Accept: application/vnd.api+json 449 | ``` 450 | ```json 451 | HTTP/1.1 202 Accepted 452 | Content-Type: application/vnd.api+json 453 | Content-Location: /upload/jobs/27d99b56 454 | 455 | { 456 | "data": { 457 | "id": "27d99b56", 458 | "type": "upload-jobs", 459 | "attributes": { 460 | "status": "Processing..." 461 | } 462 | } 463 | } 464 | ``` 465 | 466 | ---- 467 | 468 | ### Asynchronous Processing (2/3) 469 | 470 | ``` 471 | GET /upload/jobs/27d99b56 472 | 473 | Accept: application/vnd.api+json 474 | ``` 475 | ``` 476 | HTTP/1.1 303 See other 477 | Location: /data/27d99b56 478 | ``` 479 | 480 | ---- 481 | 482 | ### Asynchronous Processing (3/3) 483 | 484 | Degraded mode for browsers with the `Prefer` header 485 | 486 |
487 | 488 | ``` 489 | GET /upload/jobs/27d99b56 490 | 491 | Accept: application/vnd.api+json 492 | Prefer: status=201 493 | ``` 494 | ``` 495 | HTTP/1.1 201 Created 496 | Location: /data/27d99b56 497 | ``` 498 | 499 | ---- 500 | 501 | ### Recap' 502 | 503 | * JSON API helps writing REST APIs 504 | 505 | * It is OK to take shortcuts (sometimes) 506 | 507 | * JSON schema for (application) semantics 508 | 509 | --- 510 | 511 | ## :fa-check-circle: Testing 512 | 513 | ---- 514 | 515 | ### PHPUnit + Guzzle 516 | 517 | ```php 518 | public function testPOST() 519 | { 520 | // ... create Guzzle $client 521 | 522 | $request = $client->post('/api/programmers', null, json_encode($data)); 523 | $response = $request->send(); 524 | 525 | $request = $client->post('/api/programmers', null, json_encode($data)); 526 | $response = $request->send(); 527 | 528 | $this->assertEquals(201, $response->getStatusCode()); 529 | $this->assertTrue($response->hasHeader('Location')); 530 | $data = json_decode($response->getBody(true), true); 531 | $this->assertArrayHasKey('nickname', $data); 532 | } 533 | ``` 534 | 535 | ::: small 536 | Source: https://knpuniversity.com/screencast/rest/testing-phpunit 537 | ::: 538 | 539 | ---- 540 | 541 | ### Behat 542 | 543 | ``` 544 | # api/features/programmer.feature 545 | # ... 546 | 547 | Scenario: Create a programmer 548 | Given I have the payload: 549 | """ 550 | { 551 | "nickname": "ObjectOrienter", 552 | "avatarNumber" : "2", 553 | "tagLine": "I'm from a test!" 554 | } 555 | """ 556 | When I request "POST /api/programmers" 557 | Then the response status code should be 201 558 | And the "nickname" property should equal "ObjectOrienter" 559 | ``` 560 | 561 | ::: small 562 | Source: https://knpuniversity.com/screencast/rest/testing 563 | ::: 564 | 565 | ---- 566 | 567 | ### Chakram 568 | 569 | ``` javascript 570 | describe("HTTP assertions", function () { 571 | it("should make HTTP assertions easy", function () { 572 | var response = chakram.get("http://httpbin.org/get?test=chakram"); 573 | 574 | expect(response).to.have.status(200); 575 | expect(response).to.have.header("content-type", "application/json"); 576 | expect(response).not.to.be.encoded.with.gzip; 577 | expect(response).to.comprise.of.json({ 578 | args: { test: "chakram" } 579 | }); 580 | return chakram.wait(); 581 | }); 582 | }); 583 | ``` 584 | ----- 585 | http://dareid.github.io/chakram/ 586 | 587 | ---- 588 | 589 | ### Frisby 590 | 591 | ``` javascript 592 | var frisby = require('frisby'); 593 | 594 | frisby.create('Get Brightbit Twitter feed') 595 | .get('https://api.twitter.com/1/statuses/user_timeline.json?screen_name=brightbit') 596 | .expectStatus(200) 597 | .expectHeaderContains('content-type', 'application/json') 598 | .expectJSON('0', { 599 | user: { 600 | verified: false, 601 | location: "Oklahoma City, OK", 602 | url: "http://brightb.it" 603 | } 604 | }) 605 | .toss(); 606 | ``` 607 | ----- 608 | http://frisbyjs.com 609 | 610 | ---- 611 | 612 | ### Dredd (for API doc) 613 | 614 | ![](http://localhost:8000/images/dredd.png){no-border} 615 | 616 | ----- 617 | https://github.com/apiaryio/dredd 618 | 619 | ---- 620 | 621 | ### Postman
![](http://localhost:8000/images/postman.png){no-border} 622 | 623 | ---- 624 | 625 | ### Hurl . it
![](http://localhost:8000/images/hurlit.png){no-border} 626 | 627 | ---- 628 | 629 | ### And... 630 | 631 | * [HTTPie](https://github.com/jkbrzt/httpie): cURL-like tool for humans 632 | * [jq](https://stedolan.github.io/jq/): like `sed` for JSON data 633 | 634 |
635 | You can add this to your `.zshrc`: 636 | 637 | ``` 638 | jsonapi() { 639 | http "$@" Accept:application/vnd.api+json \ 640 | Content-Type:application/vnd.api+json 641 | } 642 | ``` 643 | 644 | --- 645 | 646 | ## Conclusion 647 | 648 | ---- 649 | 650 | ### :fa-book: Documentation 651 | 1. Very important 652 | 1. Write it **first** 653 | 1. Test it 654 | 655 | ---- 656 | 657 | ### :fa-code: Code 658 | 1. I :heart: JSON API 659 | 1. It is OK not to be 100% REST compliant 660 | 1. **TEST YOUR API!** 661 | 662 | ---- 663 | 664 | ### :fa-check-circle: Testing 665 | 666 | 1. No excuse! 667 | 1. No excuse! 668 | 1. No excuse! 669 | 670 | --- 671 | 672 | ## One More Thing 673 | 674 | I did not talk about :fa-lock: **security**, but: 675 |
676 |
677 | 678 | API key / Authorization header are a good start 679 | 680 | OAuth is not for authentication, [OpenID Connect](http://openid.net/connect/) is! 681 | 682 | JWT ([LexikJWTAuthenticationBundle](https://github.com/lexik/LexikJWTAuthenticationBundle)) is trendy 683 | 684 | Check out [Auth0 article on Symfony](https://auth0.com/docs/quickstart/backend/php-symfony) 685 | 686 | --- 687 | 688 | ### A: I don't know.
![](http://localhost:8000/images/graphql.png){no-border} 689 | 690 | --- 691 | 692 | ## Thank you. 693 | #### Questions? 694 | 695 |
696 | * :fa-globe: [williamdurand.fr](http://williamdurand.fr) 697 | * :fa-github: [github.com/willdurand](https://github.com/willdurand) 698 | * :fa-twitter: [@couac](https://twitter.com/couac) 699 | {no-bullet} -------------------------------------------------------------------------------- /slides.md: -------------------------------------------------------------------------------- 1 | # Pragmatic APIs 101 2 | 3 | _William Durand — October 29th, 2016 — Symfony Camp UA_ 4 | 5 | --- 6 | 7 | ## What's REST? 8 | 9 | ---- 10 | 11 | ### REpresentational State Transfer 12 | 13 | REST is the underlying architectural principle of the web. 14 | 15 | It is formalized as a set of constraints, described in **Roy Fielding**'s PhD dissertation. 16 | 17 | ---- 18 | 19 | ### Richardson Maturity Model 20 | 21 | ![](images/rmm.png) 22 | 23 | ---- 24 | 25 | ### Levels 0, 1, and 2 26 | 27 | * It is all about **resources** 28 | * **Client** uses specific HTTP **verbs** 29 | * **Server** uses HTTP **status codes** 30 | * Content Negotiation 31 | 32 | ---- 33 | 34 | ### Level 3 - Hypermedia Controls 35 | 36 | * Service discovery via **relations** 37 | * **Hypermedia** formats (e.g. _HTML_, _HAL_, _JSONAPI_) 38 | * Resources are not important, their **representations** are! 39 | * URI design does **not** matter (URI template) 40 | * **Client's experience** is crucial! 41 | * Protocol & **application semantics** 42 | 43 | ---- 44 | 45 | ### HATEOAS 46 | 47 | **H**ypermedia **A**s **T**he **E**ngine **O**f **A**pplication **S**tate 48 |
49 |
50 | 51 | It means that hypermedia should be used to find your 52 |
way through the API. It is all about **state 53 | transitions**. 54 | 55 | Your application is just a big **state machine**. 56 | 57 | ---- 58 | 59 | ### Resource vs Representation 60 | 61 | A **resource** can be anything, and can have more than one representation. A **representation** describes resource state. 62 | 63 | ---- 64 | 65 | ### Protocol Semantics 66 | 67 | How the underlying resource should behave under HTTP? 68 | 69 | ---- 70 | 71 | ### Application Semantics 72 | 73 | What, **specifically**, will happen to the 74 |
application or resource state? 75 | 76 | ---- 77 | 78 | ### The Semantic Challenge* 79 | 80 | Some standards have a good protocol-level 81 | semantics but no application-level 82 | semantics (_Collection+JSON_, _Atom_). 83 |
84 |
85 | Some standards define a lot of application-level semantics but no protocol semantics (_Microformats_, _Microdata_). 86 | 87 |
88 | 89 | * = as described in Richardson and Amundsen's “RESTful Web APIs” book 90 | 91 | 92 | ---- 93 | 94 | ### Profiles 95 | 96 | A **profile** is **defined** to not alter the semantics of the
resource representation 97 | itself, but **to allow clients to
learn about additional semantics**, [RFC 6906](https://tools.ietf.org/html/rfc6906). 98 |
99 |
100 | Does not have to be **machine-readable** but recommended. 101 | 102 | ---- 103 | 104 | ### Examples 105 | 106 | * Traditional API documentation 107 | * _XMDP_ (for _XHTML_ documents) 108 | * _**ALPS**_ (_XMDP_ on steroids) 109 | * Embedded doc. (as in _HAL_/_Siren_) 110 | * _JSON-LD_, _**JSON Schema**_ 111 | 112 | --- 113 | 114 | ## State Of The ~~Art~~ Industry 115 | 116 | ---- 117 | 118 | ### We all want RESTful APIs 119 | 120 | ---- 121 | 122 | ![](images/twitter-example.png) 123 | 124 | ### Yes. 125 | 126 | ---- 127 | 128 | ### Is My API RESTful When I Use JSON? 129 | 130 | _[Short answer: **no**. Long answer: no, not yet. 131 |
RESTful API must use hypermedia formats. JSON is 132 |
**not** a hypermedia format](http://restcookbook.com/Mediatypes/json/), 133 | The REST CookBook_. 134 | 135 | ---- 136 | 137 | ### No Relations = No REST 138 | 139 | _[If the engine of application state (and hence the 140 | API) 141 |
is not being driven by hypertext, then it 142 | cannot be 143 |
RESTful and cannot be a REST API](http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven), Roy Fielding_. 144 | 145 | ---- 146 | 147 | ### s/REST/HTTP++/ 148 | 149 | REST APIs are a myth, _i.e._ too complex in real life. 150 | 151 |
152 | 153 | _[99.99% of the RESTful APIs out there aren’t fully 154 | compliant
with Roy Fielding’s conception of 155 | REST](http://www.timelessrepo.com/haters-gonna-hateoas), Steve Klabnik_. 156 | 157 | ---- 158 | 159 | ### Are we all screwed and should
we all jump to GraphQL? 160 | 161 | ---- 162 | 163 | ### Nope. 164 | 165 | --- 166 | 167 | ## The Pragmatic Way 168 | 169 | Well-designed, pragmatic, and future-proof APIs. 170 | 171 | ![](images/trump.png) 172 | 173 | 174 | --- 175 | 176 | ## Documentation 177 | 178 | ---- 179 | 180 | ### API Blueprint
![](images/apiblueprint.png) 181 | 182 | ---- 183 | 184 | ### Apiary
![](images/apiary-1.png) 185 | 186 | ---- 187 | 188 | ### Apiary
![](images/apiary-2.png) 189 | 190 | ---- 191 | 192 | ### Aglio
![](images/aglio-example.png) 193 | 194 | ---- 195 | 196 | ### Moooocks! 197 | 198 | (Apiary / [Drakov](https://github.com/Aconex/drakov))
![](images/drakov.gif) 199 | 200 | ---- 201 | 202 | ### JSON Schema 203 | 204 | (Apiary / Aglio thanks to [MSON](https://help.apiary.io/api_101/mson-tutorial/)) 205 | 206 | ``` 207 | + Attributes 208 | + data (object) 209 | + id: `123` (string, required) - The identifier 210 | ``` 211 | 212 | ``` json 213 | { 214 | "$schema": "http://json-schema.org/draft-04/schema#", 215 | "type": "object", 216 | "properties": { 217 | "data": { 218 | "type": "object", 219 | "properties": { 220 | "id": { "type": "string", "description": "The identifier" } 221 | }, 222 | "required": [ "id" ] 223 | } 224 | } 225 | } 226 | ``` 227 | 228 | ---- 229 | 230 | ![](images/oai.png) 231 | 232 | 233 | (ex-Swagger) 234 | 235 | ---- 236 | 237 | ### Symfony/PHP 238 | 239 | * NelmioApiDocBundle ([#900](https://github.com/nelmio/NelmioApiDocBundle/issues/900)) 240 | * [A Tool to Convert NelmioApiDocBundle to Swagger PHP](https://blog.liip.ch/archive/2016/05/11/convert-nelmioapidocbundle-to-swagger-php.html) by Liip (blog post) 241 | * [Jane](https://github.com/janephp/jane) (JSON Schema) and [Jane Open Api](https://github.com/janephp/openapi) (Open API) 242 | 243 | ---- 244 | 245 | ### Advices 246 | 247 | * Write documentation first, then code 248 | * Must be under version control 249 | * Test your documentation (build / [Dredd](https://github.com/apiaryio/dredd)) 250 | 251 | 252 | --- 253 | 254 | ## Code 255 | 256 | ---- 257 | 258 | ### Symfony/PHP 259 | 260 | * [Symfony REST Edition](https://github.com/gimler/symfony-rest-edition) = Great for HTTP++ APIs 261 | 262 | * [FOSRestBundle](https://github.com/FriendsOfSymfony/FOSRestBundle) + [Hateoas](https://github.com/willdurand/Hateoas) = HAL 263 | 264 | * [Fractal](https://github.com/thephpleague/fractal), [Negotiation](https://github.com/willdurand/Negotiation), etc. 265 | 266 | ---- 267 | 268 | ![](images/apiplatform.png) 269 | 270 | 271 | ---- 272 | 273 | ![](images/jsonapi.png) 274 | 275 | 276 | ---- 277 | 278 | ### JSON API 279 | 280 | `application/vnd.api+json` 281 | 282 | ``` json 283 | { 284 | "data": { 285 | "id": "41c6cf", 286 | "type": "sequence", 287 | "attributes": { 288 | "name": "> Demo 1", 289 | "sequence": "ATCGAATCGGTTTAAAATCGATTCCCGAAAA" 290 | } 291 | }, 292 | "links": { 293 | "parent": "/data/27d99b56", 294 | "self": "/data/27d99b56/41c6cf", 295 | "source": "https://example.org/demo-sequence.fasta", 296 | "profile": "/profiles/data/sequence" 297 | } 298 | } 299 | ``` 300 | 301 | ---- 302 | 303 | ### Errors 304 | 305 | ``` json 306 | { 307 | "errors": [ 308 | { 309 | "code": "404", 310 | "status": "404", 311 | "title": "Not Found", 312 | "detail": "The URL you are trying to reach does not exist.", 313 | "links": { 314 | "about": "https://httpstatuses.com/404", 315 | "profile": "/profiles/errors" 316 | } 317 | } 318 | ] 319 | } 320 | ``` 321 | 322 | ---- 323 | 324 | ### Update with ~~PUT~~ PATCH 325 | 326 | ``` 327 | PATCH /upload/jobs/27d99b56-9327-4d28-a69c-31229bf971aa 328 | 329 | Content-Type: application/vnd.api+json 330 | Accept: application/vnd.api+json 331 | ``` 332 | ``` json 333 | // /!\ request payload below 334 | { 335 | "data": { 336 | "id": "27d99b56-9327-4d28-a69c-31229bf971aa", 337 | "type": "upload-jobs", 338 | "attributes": { 339 | "data_type": "sequence", 340 | "file_type": "fasta" 341 | } 342 | } 343 | } 344 | ``` 345 | 346 | (Yes... I wrote about [PATCH'ing correctly](http://williamdurand.fr/2014/02/14/please-do-not-patch-like-an-idiot/)) 347 | 348 | ---- 349 | 350 | ### Sparse Fieldsets 351 | with the `fields` query parameter 352 | 353 | ``` 354 | GET /data/27d99b56?fields[sequence]=name 355 | 356 | Accept: application/vnd.api+json 357 | ``` 358 | 359 | ``` json 360 | "data": [ 361 | { 362 | "id": "41c6cf", 363 | "type": "sequence", 364 | "attributes": { "name": "> Demo 1" } 365 | }, 366 | { 367 | "id": "787ff2", 368 | "type": "sequence", 369 | "attributes": { "name": "> Seq. 2" } 370 | } 371 | ] 372 | ``` 373 | 374 | ---- 375 | 376 | ### Filtering 377 | with the `filter` query parameter 378 | 379 | ``` 380 | GET /data/27d99b56?fields[sequence]=sequence \ 381 | &filter={"name": { "$regex": "/demo/", "$options": "i"}} 382 | 383 | Accept: application/vnd.api+json 384 | ``` 385 | ``` json 386 | "data": [ 387 | { 388 | "id": "41c6cf", 389 | "type": "sequence", 390 | "attributes": { 391 | "sequence": "ATCGAATCGGTTTAAAATCGATTCCCGAAAA" 392 | } 393 | } 394 | ] 395 | ``` 396 | 397 | ---- 398 | 399 | ### Pagination 400 | with the `page` query parameter 401 | 402 | ``` 403 | { 404 | "data": [ ... ], 405 | "links": { 406 | "next": "/data/8f7d5ef1?page[cursor]=57de7ff7&page[limit]=1", 407 | "prev": "/data/8f7d5ef1?page[cursor]=-57de7ff7&page[limit]=1" 408 | }, 409 | "meta": { 410 | "page": { 411 | "after": "57de7ff7", 412 | "before": "-57de7ff7", 413 | "count": 3138, 414 | "limit": 1 415 | } 416 | } 417 | } 418 | ``` 419 | 420 | ---- 421 | 422 | ### Inclusion 423 | with the `include` query parameter 424 | 425 | ``` 426 | GET /data/27d99b56?include=ANYTHING 427 | 428 | Accept: application/vnd.api+json 429 | ``` 430 | ```json 431 | { 432 | "data": [ ... ], 433 | "included": [ 434 | ANYTHING 435 | ] 436 | } 437 | ``` 438 | 439 | ---- 440 | 441 | ### Asynchronous Processing (1/3) 442 | 443 | ``` 444 | POST /upload 445 | 446 | Content-Length: 87 447 | Content-Type: text/csv 448 | Accept: application/vnd.api+json 449 | ``` 450 | ```json 451 | HTTP/1.1 202 Accepted 452 | Content-Type: application/vnd.api+json 453 | Content-Location: /upload/jobs/27d99b56 454 | 455 | { 456 | "data": { 457 | "id": "27d99b56", 458 | "type": "upload-jobs", 459 | "attributes": { 460 | "status": "Processing..." 461 | } 462 | } 463 | } 464 | ``` 465 | 466 | ---- 467 | 468 | ### Asynchronous Processing (2/3) 469 | 470 | ``` 471 | GET /upload/jobs/27d99b56 472 | 473 | Accept: application/vnd.api+json 474 | ``` 475 | ``` 476 | HTTP/1.1 303 See other 477 | Location: /data/27d99b56 478 | ``` 479 | 480 | ---- 481 | 482 | ### Asynchronous Processing (3/3) 483 | 484 | Degraded mode for browsers with the `Prefer` header 485 | 486 |
487 | 488 | ``` 489 | GET /upload/jobs/27d99b56 490 | 491 | Accept: application/vnd.api+json 492 | Prefer: status=201 493 | ``` 494 | ``` 495 | HTTP/1.1 201 Created 496 | Location: /data/27d99b56 497 | ``` 498 | 499 | ---- 500 | 501 | ### Recap' 502 | 503 | * JSON API helps writing REST APIs 504 | 505 | * It is OK to take shortcuts (sometimes) 506 | 507 | * JSON schema for (application) semantics 508 | 509 | --- 510 | 511 | ## Testing 512 | 513 | ---- 514 | 515 | ### PHPUnit + Guzzle 516 | 517 | ```php 518 | public function testPOST() 519 | { 520 | // ... create Guzzle $client 521 | 522 | $request = $client->post('/api/programmers', null, json_encode($data)); 523 | $response = $request->send(); 524 | 525 | $request = $client->post('/api/programmers', null, json_encode($data)); 526 | $response = $request->send(); 527 | 528 | $this->assertEquals(201, $response->getStatusCode()); 529 | $this->assertTrue($response->hasHeader('Location')); 530 | $data = json_decode($response->getBody(true), true); 531 | $this->assertArrayHasKey('nickname', $data); 532 | } 533 | ``` 534 | 535 | 536 | Source: https://knpuniversity.com/screencast/rest/testing-phpunit 537 | 538 | 539 | ---- 540 | 541 | ### Behat 542 | 543 | ``` 544 | # api/features/programmer.feature 545 | # ... 546 | 547 | Scenario: Create a programmer 548 | Given I have the payload: 549 | """ 550 | { 551 | "nickname": "ObjectOrienter", 552 | "avatarNumber" : "2", 553 | "tagLine": "I'm from a test!" 554 | } 555 | """ 556 | When I request "POST /api/programmers" 557 | Then the response status code should be 201 558 | And the "nickname" property should equal "ObjectOrienter" 559 | ``` 560 | 561 | 562 | Source: https://knpuniversity.com/screencast/rest/testing 563 | 564 | 565 | ---- 566 | 567 | ### Chakram 568 | 569 | ``` javascript 570 | describe("HTTP assertions", function () { 571 | it("should make HTTP assertions easy", function () { 572 | var response = chakram.get("http://httpbin.org/get?test=chakram"); 573 | 574 | expect(response).to.have.status(200); 575 | expect(response).to.have.header("content-type", "application/json"); 576 | expect(response).not.to.be.encoded.with.gzip; 577 | expect(response).to.comprise.of.json({ 578 | args: { test: "chakram" } 579 | }); 580 | return chakram.wait(); 581 | }); 582 | }); 583 | ``` 584 | ----- 585 | http://dareid.github.io/chakram/ 586 | 587 | ---- 588 | 589 | ### Frisby 590 | 591 | ``` javascript 592 | var frisby = require('frisby'); 593 | 594 | frisby.create('Get Brightbit Twitter feed') 595 | .get('https://api.twitter.com/1/statuses/user_timeline.json?screen_name=brightbit') 596 | .expectStatus(200) 597 | .expectHeaderContains('content-type', 'application/json') 598 | .expectJSON('0', { 599 | user: { 600 | verified: false, 601 | location: "Oklahoma City, OK", 602 | url: "http://brightb.it" 603 | } 604 | }) 605 | .toss(); 606 | ``` 607 | ----- 608 | http://frisbyjs.com 609 | 610 | ---- 611 | 612 | ### Dredd (for API doc) 613 | 614 | ![](images/dredd.png) 615 | 616 | ----- 617 | https://github.com/apiaryio/dredd 618 | 619 | ---- 620 | 621 | ### Postman
![](images/postman.png) 622 | 623 | ---- 624 | 625 | ### Hurl . it
![](images/hurlit.png) 626 | 627 | ---- 628 | 629 | ### And... 630 | 631 | * [HTTPie](https://github.com/jkbrzt/httpie): cURL-like tool for humans 632 | * [jq](https://stedolan.github.io/jq/): like `sed` for JSON data 633 | 634 |
635 | You can add this to your `.zshrc`: 636 | 637 | ``` 638 | jsonapi() { 639 | http "$@" Accept:application/vnd.api+json \ 640 | Content-Type:application/vnd.api+json 641 | } 642 | ``` 643 | 644 | --- 645 | 646 | ## Conclusion 647 | 648 | ---- 649 | 650 | ### Documentation 651 | 1. Very important 652 | 1. Write it **first** 653 | 1. Test it 654 | 655 | ---- 656 | 657 | ### Code 658 | 1. I JSON API 659 | 1. It is OK not to be 100% REST compliant 660 | 1. **TEST YOUR API!** 661 | 662 | ---- 663 | 664 | ### Testing 665 | 666 | 1. No excuse! 667 | 1. No excuse! 668 | 1. No excuse! 669 | 670 | --- 671 | 672 | ## One More Thing 673 | 674 | I did not talk about **security**, but: 675 |
676 |
677 | 678 | API key / Authorization header are a good start 679 | 680 | OAuth is not for authentication, [OpenID Connect](http://openid.net/connect/) is! 681 | 682 | JWT ([LexikJWTAuthenticationBundle](https://github.com/lexik/LexikJWTAuthenticationBundle)) is trendy 683 | 684 | Check out [Auth0 article on Symfony](https://auth0.com/docs/quickstart/backend/php-symfony) 685 | 686 | --- 687 | 688 | ### A: I don't know.
![](images/graphql.png) 689 | 690 | --- 691 | 692 | ## Thank you. 693 | #### Questions? 694 | 695 |
696 | * [williamdurand.fr](http://williamdurand.fr) 697 | * [github.com/willdurand](https://github.com/willdurand) 698 | * [@couac](https://twitter.com/couac) 699 | --------------------------------------------------------------------------------