-
Notifications
You must be signed in to change notification settings - Fork 8
/
Copy pathapistrat.xml
315 lines (315 loc) · 19.6 KB
/
apistrat.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="hotspot/hotspot/hotspot.xsl"?>
<?hotspot layout-path="hotspot/hotspot/layout" ?>
<?hotspot kilauea-path="hotspot/kilauea" ?>
<?hotspot layout="apiacademy-new" ?>
<hotspot xmlns="http://dret.net/xmlns/hotspot/1" xmlns:hotspot="http://dret.net/xmlns/hotspot/1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://dret.net/xmlns/hotspot/1 hotspot/hotspot/schemas/hotspot.xsd">
<script src="http://platform.twitter.com/widgets.js" type="text/javascript"></script>
<configuration>
<link subsections="yes" bookmarks="yes" versions="apistrat.xml" home="./" help="quick" contents="./" author="http://dret.net/netdret/"/>
<paths img="img" listing="src"/>
<outline count-text=" [*]" count-depth="all"/>
<hyperlink extra=""/>
<extension file="html" link=""/>
<counter separator=": "/>
<kilauea xmlns="http://xmlns.sharpeleven.net/kilauea">
<plugins>
<touch/>
</plugins>
</kilauea>
</configuration>
<license uri="http://creativecommons.org/licenses/by/3.0/" short="CC 3.0">
<div class="license">
<p><a rel="license" title="view full text of license" href="http://creativecommons.org/licenses/by/3.0/"><img alt="Creative Commons License" src="hotspot/hotspot/layout/apiacademy/apiacademy/somerights20.png" border="0" height="31" width="88"/></a></p>
<p><a class="outlink" rel="license" title="view full text of license" href="http://creativecommons.org/licenses/by/3.0/">This work is licensed under a CC<br/>Attribution 3.0 Unported License</a></p>
</div>
</license>
<title><a href="https://events.linuxfoundation.org/events/apistrat-2018/">API Strategy & Practice 2018</a></title>
<presentation id="index">
<title>May Contain Nuts: The Case for API Labeling</title>
<toc class="abstract">The technical aspect of APIs has been widely discussed with description languages such as Swagger/OpenAPI. The non-functional aspects are harder to formalize, but can also benefit from a framework in which information can be represented and used. The idea of "API Labels" is equivalent to that of standardized labeling systems in other product spaces, for example for food or for machinery. There often is a framework in place that allows users to understand key aspects of the product. This framework focuses on areas that are important and helpful to make an initial product selection. In the API space, numerous standards and best practices have evolved how APIs can be described and/or documented. This presentation provides an overview of the existing approaches, how to use them, and proposes an additional layer on top of which API labeling becomes more unified, and thus more useful.</toc>
<author><a href="http://dret.net/netdret/">Erik Wilde</a> <a href="http://twitter.com/dret" class="twitter-follow-button" data-size="large" title="Erik Wilde on Twitter: @dret">(<code>@dret</code>)</a></author>
<affiliation><a href="http://www.apiacademy.co/">API Academy</a>, <a href="http://www.ca.com/">CA Technologies</a></affiliation>
<date short="2018-09-25">September 25, 2018</date>
<copyright>2018 Erik Wilde</copyright>
<toc class="resources"><a href="http://www.apiacademy.co/">API Academy</a> · <a href="http://www.apiacademy.co/microservice-architecture-the-oreilly-book/" title="Mike Amundsen, Matt McLarty, Ronnie Mitra, and Irakli Nadareishvili, 'Microservice Architecture: Aligning Principles, Practices, and Culture', O'Reilly Media, June 2016">MSA Book</a></toc>
<slide id="summary">
<title>Summary</title>
<p class="abstract"><toc class="abstract"/></p>
</slide>
<part id="introduction">
<title>Introduction</title>
<slide id="dretwitter">
<title><code>@dret</code> on Twitter/GitHub</title>
<img src="dret.png" title="dret" href="http://twitter.com/dret" style=" width : 90% ; height : 70% ; object-fit : contain ; margin : 0% 4% 0% 4% ; "/>
</slide>
<slide id="api-academy">
<title><a href="http://www.apiacademy.co/">API Academy</a></title>
<img src="academy-logo.png" href="http://www.apiacademy.co/" title="API Academy" style="float: right ; width : 30% ; margin : 4% ; "/>
<ul>
<li>Global Team working on <em>API Strategy and Design</em> topics</li>
<ul>
<li><a href="http://www.apiacademy.co/team_member/matt-mclarty/">Matt McLarty</a> (Vancouver): <a href="http://twitter.com/MattMcLartyBC" class="twitter-follow-button" title="Matt McLarty on Twitter: @MattMcLartyBC"><code>@MattMcLartyBC</code></a><script src="http://platform.twitter.com/widgets.js" type="text/javascript"></script></li>
<li><a href="http://www.apiacademy.co/team_member/mike-amundsen/">Mike Amundsen</a> (Cincinnati): <a href="http://twitter.com/mamund" class="twitter-follow-button" title="Mike Amundsen on Twitter: @mamund"><code>@mamund</code></a><script src="http://platform.twitter.com/widgets.js" type="text/javascript"></script></li>
<li><a href="http://www.apiacademy.co/team_member/mehdi-medjaoui/">Mehdi Medjaoui</a> (San Francisco): <a href="http://twitter.com/medjawii" class="twitter-follow-button" title="Mehdi Medjaoui on Twitter: @medjawii"><code>@medjawii</code></a><script src="http://platform.twitter.com/widgets.js" type="text/javascript"></script></li>
<li><a href="http://www.apiacademy.co/team_member/ronnie-mitra/">Ronnie Mitra</a> (London): <a href="http://twitter.com/mitraman" class="twitter-follow-button" title="Ronnie Mitra on Twitter: @mitraman"><code>@mitraman</code></a><script src="http://platform.twitter.com/widgets.js" type="text/javascript"></script></li>
<li><a href="http://www.apiacademy.co/team_member/erik-wilde/">Erik Wilde</a> (Zürich): <a href="http://twitter.com/dret" class="twitter-follow-button" title="Erik Wilde on Twitter: @dret"><code>@dret</code></a><script src="http://platform.twitter.com/widgets.js" type="text/javascript"></script></li>
</ul>
<li>Evangelizing ideas and technologies</li>
<ul>
<li>Speaking (conferences, events)</li>
<li>Teaching (workshops, bootcamps)</li>
<li>Publishing (blogs, articles, books, <a href="https://soundcloud.com/user-426834320">podcasts</a>)</li>
<li>Doing (side projects on API-related topics)</li>
<li>Standardizing (participating in specification work)</li>
</ul>
</ul>
</slide>
<slide id="dret">
<title>About Me</title>
<ul>
<li><a href="http://dret.net/netdret/publications#wil97b">Ph.D. in Communications Systems</a> from <a href="http://www.ethz.ch/">ETH Zürich</a></li>
<li>Working on Web Architecture after writing <a href="http://dret.net/netdret/publications#wil98">the first Web Technology book</a></li>
<li>UC Berkeley (2006-2011), working on <a href="http://dret.net/netdret/publications#wil09g">Service Models for Open Government</a></li>
<li>EMC (2011-2014), working on transforming software products into service platforms</li>
<li>Siemens (2014-2015), working on using <em title="Internet of Things">IoT</em> to build <em title="Web of Things">WoT</em> (<q>APIs for Things</q>)</li>
<li>Joined <a href="http://www.ca.com/" title="CA Technologies">CA</a>'s <a href="http://www.apiacademy.co/">API Academy</a> in 2016 and now all about API Strategy and Design</li>
<li>Active in the usual places such as <a href="http://twitter.com/dret" title="@dret">Twitter</a>, <a href="http://github.com/dret" title="dret">GitHub</a>, <a href="http://dret.typepad.com/dretblog/">my blog</a>, <a href="http://www.linkedin.com/in/netdret">LinkedIn</a>, and <a href="https://www.flickr.com/photos/dret/" title="dret">flickr</a></li>
</ul>
</slide>
</part>
<part id="why-labels">
<title>Why Labels?</title>
<slide id="food-labels">
<title>Food Labels</title>
<img title="Food Labels" href="https://www.google.ch/search?q=food+labels&tbm=isch" src="food-labels.png" style=" width : 90% ; height : 70% ; object-fit : contain ; margin : 0% 4% 0% 4% ; "/>
</slide>
<slide id="safety-labels">
<title>Safety Labels</title>
<img title="Product Safety Labels" href="https://www.google.ch/search?q=product+safety+labels&tbm=isch" src="safety-labels.png" style=" width : 90% ; height : 70% ; object-fit : contain ; margin : 0% 4% 0% 4% ; "/>
</slide>
<slide id="label-complexity">
<title>Label Design and Complexity</title>
<img src="vacuum-label.png" style=" width : 90% ; height : 70% ; object-fit : contain ; margin : 0% 4% 0% 4% ; "/>
</slide>
<slide id="landscape-management">
<title><span title="Obsessive Compulsive Disorder">OCD</span>? Landscape Management!</title>
<img src="vacuum-landscape.png" style=" width : 90% ; height : 70% ; object-fit : contain ; margin : 0% 4% 0% 4% ; "/>
</slide>
<slide id="labels-work">
<title>Why Do Labels Work?</title>
<blockquote>
<p>Goal: Information about all/many products in large landscapes.</p>
<p>Non-goal: Every possible detail about every single product.</p>
</blockquote>
<ul>
<li>Simple/simplified description of important product aspects</li>
<li>Supported across large sets of products (sometimes even across categories)</li>
<li>Defined/assigned/verified/certified by a trusted third party</li>
</ul>
</slide>
</part>
<part id="why-api-labels">
<title>Why API Labels?</title>
<slide id="label-sharing">
<title>Labels: Sharing + Loose Coupling</title>
<img src="label-scenario-people.png" style=" width : 90% ; height : 70% ; object-fit : contain ; margin : 0% 4% 0% 4% ; "/>
</slide>
<slide id="api-the-apis">
<title>API the APIs</title>
<blockquote><q>If you want to say something <em>about</em> your API, say it <em>through</em> your API.</q></blockquote>
<ul>
<li>Configuration/description/documentation as code</li>
<li>Accessible to tooling and automation</li>
<li>Separate representation and label semantics</li>
</ul>
</slide>
<slide id="dataset-search">
<title>Better Descriptions ⇒ Better Search and Use</title>
<ul>
<li>Google just (September 2018) launched <a href="https://toolbox.google.com/datasetsearch">Google Dataset Search</a></li>
<ul>
<li>It is <a href="https://www.blog.google/products/search/making-it-easier-discover-datasets/">based on dataset descriptions</a> which are <a href="https://schema.org/">based on <code>schema.org</code></a></li>
</ul>
<li>Public description and search helps aggregators (and their users)</li>
<li>Private description helps internal management and landscaping</li>
</ul>
</slide>
<slide id="label-scenarios">
<title>API Label Scenarios</title>
<ul>
<li>API labels are not intended to replace API descriptions</li>
<ul>
<li>Descriptions are more detailed and complex</li>
</ul>
<li>API labels as a way to <em>expose/share information internally</em></li>
<ul>
<li>Managing labels types/values and trust is relatively easy</li>
</ul>
<li>API labels as a way to <em>expose/share information publicly</em></li>
<ul>
<li>Managing labels types/values and trust becomes more challenging</li>
</ul>
</ul>
</slide>
<slide id="label-scenario-declared">
<title>Get API Labels</title>
<img src="label-scenario-declared.png" style=" width : 90% ; height : 70% ; object-fit : contain ; margin : 0% 4% 0% 4% ; "/>
</slide>
<slide id="label-scenario-certified">
<title>Get Certified Labels from 3rd Party</title>
<img src="label-scenario-certified.png" style=" width : 90% ; height : 70% ; object-fit : contain ; margin : 0% 4% 0% 4% ; "/>
</slide>
<slide id="label-scenario-assigned">
<title>Get Labels Assigned by 3rd Party</title>
<img src="label-scenario-assigned.png" style=" width : 90% ; height : 70% ; object-fit : contain ; margin : 0% 4% 0% 4% ; "/>
</slide>
<slide id="label-scenario-discovery-assigned">
<title>Assigned Labels for API Discovery</title>
<img src="label-scenario-discovery-assigned.png" style=" width : 90% ; height : 70% ; object-fit : contain ; margin : 0% 4% 0% 4% ; "/>
</slide>
<slide id="label-scenario-discovery-declared">
<title>Declared Labels for API Discovery</title>
<img src="label-scenario-discovery-declared.png" style=" width : 90% ; height : 70% ; object-fit : contain ; margin : 0% 4% 0% 4% ; "/>
</slide>
</part>
<part id="value-space">
<title>The API Label Value Space</title>
<slide id="api-label-types">
<title>API Label Types</title>
<ul>
<li>Label types can be <em>registered</em> or <em>extension</em> label types</li>
<li><em>Registered label types</em> are managed in an <a href="https://github.com/API-Labels/API-label-registry">open API label type registry</a></li>
<ul>
<li>Registered types have well-known names that are simple strings</li>
</ul>
<li><em>Extension label types</em> can be used by anybody with no registration required</li>
<ul>
<li>Extension types have self-describing names that are URIs</li>
</ul>
</ul>
</slide>
<slide id="spdx-values">
<title><a href="https://spdx.org/" title="Software Package Data Exchange">SPDX</a> <a href="https://spdx.org/licenses/">License Values</a></title>
<table class="sortable" style="margin: auto ; width: calc(100% - 5em);">
<thead><tr>
<th>Full name</th><th>Identifier</th></tr></thead>
<tbody>
<tr>
<td><a href="https://spdx.org/licenses/0BSD.html">BSD Zero Clause License</a></td>
<td about="https://spdx.org/licenses/0BSD.html"><code>0BSD</code></td>
</tr>
<tr>
<td><a href="https://spdx.org/licenses/AAL.html">Attribution Assurance License</a></td>
<td about="https://spdx.org/licenses/AAL.html"><code>AAL</code></td>
</tr>
<tr>
<td><a href="https://spdx.org/licenses/Abstyles.html">Abstyles License</a></td>
<td about="https://spdx.org/licenses/Abstyles.html"><code>Abstyles</code></td>
</tr>
<tr>
<td><a href="https://spdx.org/licenses/Adobe-2006.html">Adobe Systems Incorporated Source Code License Agreement</a></td>
<td about="https://spdx.org/licenses/Adobe-2006.html"><code>Adobe-2006</code></td>
</tr>
<tr>
<td><a href="https://spdx.org/licenses/Adobe-Glyph.html">Adobe Glyph List License</a></td>
<td about="https://spdx.org/licenses/Adobe-Glyph.html"><code>Adobe-Glyph</code></td>
</tr>
<tr>
<td><a href="https://spdx.org/licenses/ADSL.html">Amazon Digital Services License</a></td>
<td about="https://spdx.org/licenses/ADSL.html"><code>ADSL</code></td>
</tr>
<tr>
<td><a href="https://spdx.org/licenses/AFL-1.1.html">Academic Free License v1.1</a></td>
<td about="https://spdx.org/licenses/AFL-1.1.html"><code>AFL-1.1</code></td>
</tr>
<tr>
<td><a href="https://spdx.org/licenses/AFL-1.2.html">Academic Free License v1.2</a></td>
<td about="https://spdx.org/licenses/AFL-1.2.html"><code>AFL-1.2</code></td>
</tr>
<tr>
<td><a href="https://spdx.org/licenses/AFL-2.0.html">Academic Free License v2.0</a></td>
<td about="https://spdx.org/licenses/AFL-2.0.html"><code>AFL-2.0</code></td>
</tr>
<tr>
<td><a href="https://spdx.org/licenses/AFL-2.1.html">Academic Free License v2.1</a></td>
<td about="https://spdx.org/licenses/AFL-2.1.html"><code>AFL-2.1</code></td>
</tr>
<tr>
<td><a href="https://spdx.org/licenses/AFL-3.0.html">Academic Free License v3.0</a></td>
<td about="https://spdx.org/licenses/AFL-3.0.html"><code>AFL-3.0</code></td>
</tr>
<tr>
<td><a href="https://spdx.org/licenses/Afmparse.html">Afmparse License</a></td>
<td about="https://spdx.org/licenses/Afmparse.html"><code>Afmparse</code></td>
</tr>
<tr>
<td><a href="https://spdx.org/licenses/AGPL-1.0-only.html">Affero General Public License v1.0 only</a></td>
<td about="https://spdx.org/licenses/AGPL-1.0-only.html"><code>AGPL-1.0-only</code></td>
</tr>
<tr>
<td><a href="https://spdx.org/licenses/AGPL-1.0-or-later.html">Affero General Public License v1.0 or later</a></td>
<td about="https://spdx.org/licenses/AGPL-1.0-or-later.html"><code>AGPL-1.0-or-later</code></td>
</tr>
</tbody>
</table>
</slide>
</part>
<part id="api-label-recipe">
<title>A Recipe for API Labels</title>
<slide id="label-scenario-declared-how">
<title>Get API Labels! But How?</title>
<img src="label-scenario-declared.png" style=" width : 90% ; height : 70% ; object-fit : contain ; margin : 0% 4% 0% 4% ; "/>
</slide>
<slide id="label-scenario-formats">
<title>API Label Formats</title>
<img src="label-scenario-formats.png" style=" width : 90% ; height : 70% ; object-fit : contain ; margin : 0% 4% 0% 4% ; "/>
</slide>
<slide id="home-documents">
<title><a href="https://tools.ietf.org/html/draft-nottingham-json-home">Home Documents for HTTP APIs</a></title>
<listing src="home.json"/>
</slide>
<slide id="home-documents">
<title>Finding Labels</title>
<listing src="home-labels.json" line="2-8"/>
<listing src="labels.json"/>
</slide>
</part>
<part id="conclusions">
<title>Conclusions</title>
<slide id="label-sharing-repeat">
<title>Labels: Sharing + Loose Coupling</title>
<img src="label-scenario-people.png" style=" width : 90% ; height : 70% ; object-fit : contain ; margin : 0% 4% 0% 4% ; "/>
</slide>
<slide id="related-work">
<title>Related Work</title>
<ul>
<li><a href="http://pivio.io/">Pivio</a> for service documentation and discovery</li>
<li><a href="http://apisjson.org/">APIs.json</a> for describing API operations</li>
<li><a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#infoObject">OpenAPI <em>Info Object</em></a> and possible extensions</li>
<li><a href="https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/#user-documentation">RAML <em>User Documentation</em></a> and possible extensions</li>
</ul>
</slide>
<slide id="next-steps">
<title>API Labels: Next Steps</title>
<ul>
<li>Decoupling labels from specific API styles and descriptions</li>
<li>Collect use cases and patterns for using API labels</li>
<li>Converge on a format and establish a registry for shared label types</li>
</ul>
</slide>
<slide id="resources">
<title>Additional Resources</title>
<ul>
<li><a href="https://github.com/API-Labels"><code>API-Labels</code></a> organization on GitHub</li>
<ul>
<li><a href="https://github.com/API-Labels/label-format"><code>label-format</code></a> repository for the label format</li>
<li><a href="https://github.com/API-Labels/API-label-registry"><code>API-label-registry</code></a> repository for the registry of API labels</li>
</ul>
<li>Cesare Pautasso and Erik Wilde, "May Contain Nuts: The Case for API Labels", 14th International Workshop on Engineering Service-Oriented Applications and Cloud Services (WESOACS 2018), Como, Italy, September 2018. ( <a href="http://dret.net/netdret/publications#pau18a">paper</a> / <a href="http://www.pautasso.info/talks/2018/2018-WESOACS-APIlabels">presentation slides</a> )</li>
<li>These slides online: <a href="http://dret.net/lectures/apistrat-2018"><code>dret.net/lectures/apistrat-2018</code></a> (<a href="http://github.com/dret/lectures/tree/master/apistrat-2018">slide sources</a>)</li>
</ul>
</slide>
</part>
</presentation>
</hotspot>