Welcome

Welcome to “WebAPI Discovery” group!

The article from which our journey began: https://blog.apis.guru/api-discovery-can-we-do-better-2336706d5407

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.