A group to develop a mechanism for the automatic discovery of WebAPIs, by
extending the schema.org vocabulary.
Increasingly, large online platforms and services provide one or more Web
APIs for third-party developers. Moreover, many companies build WebAPIs as
their primary product (Email API, SMS API, etc.). This has resulted in an
explosion of the number of WebAPIs in recent years. Developers spend a
significant amount of time searching for suitable WebAPIs to meet their
needs.
Our intention is to work closely with Schema.org to define a
WebAPI-specific extension and promote usage of this extension among API
owners. In the long run, our aim is to contribute this extension into the
core Schema.org vocabulary.
To achieve these goals we are seeking feedback and collaboration from API
owners, DX specialists, API description language experts and maintainers of
various API catalogs.
Note: Community Groups are proposed and run by the community. Although W3C hosts these
conversations, the groups do not necessarily represent the views of the W3C Membership or staff.
The chairs of the WebAPI Discovery Community Group are pleased to announce the first published draft of WADG0001 – a proposal to create an extension of the schema.org WebAPI type, to aid further discovery of machine- and human- readable API definitions and related documentation.
Feedback on this first draft, which is expected to undergo much change, is eagerly appreciated.
There is ongoing work to extend Schema.org vocabulary with “WebAPI” type. You can track it in this issue and this PR. However, current proposal includes only Organisation/Service related fields (name, logo, ToS, etc.) and link to API documentation.
Task of this group is to further extend “WebAPI” type with properties like transport protocols (HTTP(S), WebSockets, others), high-level protocol (SOAP, GraphQL, Hydra, etc.), payload format (XML, JSON, CSV), base or entry-point URL, link to machine readable API description, etc.
Some core principals of this group:
– Our intent is to define the flexible format to document existing and possibly future WebAPIs. That’s why we shouldn’t enforce or promote the use of any specific API technology, protocol, etc.
– We shouldn’t use controversial terms like REST, Hypermedia, etc. Architectural styles are hard to quantify and they provoke a lot of unproductive discussions. Proposed Schema.org extensions should use only terms documented in RFCs or any other official standards.
– By WebAPI we mean APIs based on Web technologies (HTTP(S), WebSockets, etc.). So non-WebAPIs are beyond the scope of this group.
– Documenting individual endpoints, functions, actions, etc. is very technology dependent. It should be handled by API itself (SOAP, Hydra, GraphQL, …) or by separate standards (WADL, OpenAPI, RAML, …). At the same time proposed Schema.org extensions should provide enough information for API clients to being able to access these mechanisms.
A group to develop a mechanism for the automatic discovery of WebAPIs, by
extending the schema.org vocabulary.
Increasingly, large online platforms and services provide one or more Web
APIs for third-party developers. Moreover, many companies build WebAPIs as
their primary product (Email API, SMS API, etc.). This has resulted in an
explosion of the number of WebAPIs in recent years. Developers spend a
significant amount of time searching for suitable WebAPIs to meet their
needs.
Our intention is to work closely with Schema.org to define a
WebAPI-specific extension and promote usage of this extension among API
owners. In the long run, our aim is to contribute this extension into the
core Schema.org vocabulary.
To achieve these goals we are seeking feedback and collaboration from API
owners, DX specialists, API description language experts and maintainers of
various API catalogs.
This is a community initiative. This group was originally proposed on 2016-12-01 by Ivan Goncharov. The following people supported its creation: Ivan Goncharov, Mike Ralphson, Roman Hotsiy, Jesse van Dam, Mohamed ZERGAOUI. W3C’s hosting of this group does not imply endorsement of the activities.
webapi-discovery/