[http://creativecommons.org/licenses/by/3.0/]
This work is licensed under a CC
Attribution 3.0 Unported License [http://creativecommons.org/licenses/by/3.0/]
@dret
on Twitter/GitHub
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.
@MattMcLartyBC
[http://twitter.com/MattMcLartyBC]@mamund
[http://twitter.com/mamund]@medjawii
[http://twitter.com/medjawii]@mitraman
[http://twitter.com/mitraman]@dret
[http://twitter.com/dret]APIs for Things)
Goal: Information about all/many products in large landscapes.
Non-goal: Every possible detail about every single product.
If you want to say something about your API, say it through your API.
schema.org
[https://schema.org/]Full name | Identifier |
---|---|
BSD Zero Clause License [https://spdx.org/licenses/0BSD.html] | 0BSD |
Attribution Assurance License [https://spdx.org/licenses/AAL.html] | AAL |
Abstyles License [https://spdx.org/licenses/Abstyles.html] | Abstyles |
Adobe Systems Incorporated Source Code License Agreement [https://spdx.org/licenses/Adobe-2006.html] | Adobe-2006 |
Adobe Glyph List License [https://spdx.org/licenses/Adobe-Glyph.html] | Adobe-Glyph |
Amazon Digital Services License [https://spdx.org/licenses/ADSL.html] | ADSL |
Academic Free License v1.1 [https://spdx.org/licenses/AFL-1.1.html] | AFL-1.1 |
Academic Free License v1.2 [https://spdx.org/licenses/AFL-1.2.html] | AFL-1.2 |
Academic Free License v2.0 [https://spdx.org/licenses/AFL-2.0.html] | AFL-2.0 |
Academic Free License v2.1 [https://spdx.org/licenses/AFL-2.1.html] | AFL-2.1 |
Academic Free License v3.0 [https://spdx.org/licenses/AFL-3.0.html] | AFL-3.0 |
Afmparse License [https://spdx.org/licenses/Afmparse.html] | Afmparse |
Affero General Public License v1.0 only [https://spdx.org/licenses/AGPL-1.0-only.html] | AGPL-1.0-only |
Affero General Public License v1.0 or later [https://spdx.org/licenses/AGPL-1.0-or-later.html] | AGPL-1.0-or-later |
{ "api": { "title": "Example API", "links": { "author": "mailto:api-admin@example.com", "describedBy": "https://example.com/api-docs/" } }, "resources": { "tag:me@example.com,2016:widgets": {"href": "/widgets/"}, "tag:me@example.com,2016:widget": { "hrefTemplate": "/widgets/{widget_id}", "hrefVars": {"widget_id": "https://example.org/param/widget"}, "hints": { "allow": [ "GET", "PUT", "DELETE", "PATCH" ], "formats": {"application/json": {}}, "acceptPatch": ["application/json-patch+json"], "acceptRanges": ["bytes"] } } } }
"api": { "title": "Example API", "links": { "author": "mailto:api-admin@example.com", "describedBy": "https://example.com/api-docs/", "labels": "https://example.com/labels.json" }
{"labels": { "API": { "version": "1.3.42", "SPDX-license": "ADSL", "http://example.com/privatelabeltype": "some label value" }}}
API-Labels
[https://github.com/API-Labels] organization on GitHub
label-format
[https://github.com/API-Labels/label-format] repository for the label format
API-label-registry
[https://github.com/API-Labels/API-label-registry] repository for the registry of API labels
dret.net/lectures/apistrat-2018
[http://dret.net/lectures/apistrat-2018] (slide sources [http://github.com/dret/lectures/tree/master/apistrat-2018])