Add "WebAPI" type

[IvanGoncharov]

At the moment Schema.org don't have appropriate type to describe Web APIs.
By WebAPI I mean any API which uses HTTP/HTTPS as transport mechanism including REST API, SOAP, GraphQL, etc.
At the moment there is no scalable mechanism to discover publicly available APIs on the internet.
Closest solution so far is API catalogs, and for the last two year, I have been maintaining my own.
But it's hard to maintain and impossible to scale.

On the other hand, almost all public APIs have dedicated HTML pages where they can use Schema.org types.
Ideally it should have fields like:

• Title, Description, Logo
• License, ToS
• Support contacts
• Version, e.g. 1.0.0
• list of base URLs, e.g. http://api.example.com/v1, https://api.example.com/v1/
• Type of service: RESTful, SOAP, GraphQL
• Link to API Description

I want to work on a PR adding WebAPI type to schema.org.
Can you please advice which base type should I derive it from?
And should I submit it as PR or you have some formal procedure?

[jaygray0919]

This would complement work done here:
http://webdatacommons.org/structureddata/

[IvanGoncharov]

@jaygray0919 It will benefit entire developers community since a huge amount of data can be accessed only through Web APIs. And for many companies describing their existing Web APIs will be the first step toward Linked Data.

[IvanGoncharov]

@danbri @RichardWallis I'm ready to start working on PR, can you please answer my questions?

Can you please advice which base type should I derive it from?
And should I submit it as PR or you have some formal procedure?

[RichardWallis]

@IvanGoncharov apologies for being a bit slow in responding.

I can see the basic need for something like this - I would like to see some indication of who would apply it to their sites (other than yourself of course).

Most of the properties you describe could be generally available via any Type in Schema (Title (name), description, URLs, etc.) and via the organization Offering the API (Service?) (Logo, Contacts etc.)

As to a base type to enhance or subtype, my inclination is to look at EntryPoint which is generally describing something similar. Not sure if we just enhance that type with a few more specific properties, or create a more specific subtype for API (do we need to constrain it to WebAPI ?)

In the current structure EntryPoint is accessed via the target property of Action and its subtypes. Maybe a new APIAction subtype would work here. This would enable that a description of the Organization/Service that is providing the API to be linked to the actual API description via potentialAction.

[thadguidry]

@RichardWallis I've pinged David and Wendell from ProgrammableWeb.com to voice their opinions here as well. Hopefully they respond shortly.

[dberlind]

Hey all, I've received @thadguidry's email and replied. As you can imagine, this is an issue that is core to our mission. It's practically our purpose in life. So, we do spend a disproportionate amount of our time thinking about API discovery and search and developing an understanding of what exactly developers want when they start to look for APIs. So, we certainly appreciate the outreach to better understand what role we can play.

[IvanGoncharov]

I can see the basic need for something like this - I would like to see some indication of who would apply it to their sites (other than yourself of course).

@RichardWallis I think it's most important question and should be answered before technical ones.
And it should be answered by API owners and DX guys so I publish a post on our blog asking for feedback: https://blog.apis.guru/api-discovery-can-we-do-better-2336706d5407

[tlrobinson]

This is a great idea.

Nitpick: I'm not sure "web" is the best name for the type of APIs you're talking about, basically 3rd party APIs. HTTP is certainly the most common transport these days but that might not always be the case. Also, "web" generally implies hypertext (of course that's the "H" in HTTP but almost no APIs actually use hypertext)

[pjz]

...so 'net API' instead of 'web API'?

[shashanksingh]

Hey Guys,
We at faasos (on-demand-delivery)-would love to have these openly discoverable api schema for our public api's.

URL : www.faasos.com

[mesteche]

I'm not sure "web" is the best name for the type of APIs you're talking about, basically 3rd party APIs. HTTP is certainly the most common transport these days but that might not always be the case. Also, "web" generally implies hypertext (of course that's the "H" in HTTP but almost no APIs actually use hypertext)

With WebSockets and WebRTC, this is becoming less and less true.

[maccman]

@clearbit would love to see this.

[sotaan]

Hey!
I really like this idea since it will make API discovery smoother

[L4in]

As someone who already lost countless hours trying to find good APIs, I totally back up this idea.
A lot of people not in tech complained about how programming looks complex by lack of documentation or visibility - I tend to disagree because this is less and less true - and this is definitely a change needed to welcome even more people into writing their own stuff.

[asbjornu]

This sounds a lot like Hydra's ApiDocumentation. Please have a look; perhaps there's something that could be learned one way or another.

@tlrobinson:

Nitpick: I'm not sure "web" is the best name for the type of APIs you're talking about, basically 3rd party APIs. HTTP is certainly the most common transport these days but that might not always be the case. Also, "web" generally implies hypertext (of course that's the "H" in HTTP but almost no APIs actually use hypertext)

But won't you agree that having a document describing your API and perhaps even being so bold as to linking to your initial API endpoint, would make at least the Web API description a hypertext format?