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?

[ncthbrt]

We (WhereIsMyTransport) would be very interested.

[cmerrick]

We (stitchdata.com) extract data from dozens of APIs. We think this is a great idea. +1

[adamretter]

+1

[bert2002]

Would love to see this happen.

[mateomurphy]

EntryPoint would seem to be a good type for individual API calls (which should definitely have their own type). But overall API should probably be a Service. Net and/or Web API could be subtype of API

[dberlind]

On ProgrammableWeb, we are making reference more and more to "networkable"
APIs vs. just Web (HTTP) APIs. The latest data model behind our directories
reflects this and one of the strongest use cases has to do with the
Internet of Things which for some "things" doesn't involve HTTP at all (ie:
MQTT over TCP/IP).

On Mon, Nov 21, 2016 at 11:27 AM, Mateo Murphy notifications@github.com
wrote:

EntryPoint would seem to be a good type for individual API calls (which
should definitely have their own type). But overall API should probably be
a Service. Net and/or Web API could be subtype of API

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
#1423 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AGVdulSuAr3bh0q1Pu3B-rTAdHwDmRweks5rAcZmgaJpZM4KnIBY
.

[ivan-gammel]

I like this proposal and my company will eventually support it by publishing some of our REST APIs this way. Some things I'd personally be glad to see:

1. Indication of REST API maturity level (resources/verbs/HATEOAS)
2. For Level 3 REST APIs what are the supported formats (HAL, Siren etc)

[dberlind]

Ivan, how does data get curated or policed? Is it essentially crowdsourced
by populating a schema as is the case with other schemas such as recipes,
reviews, etc. The reason I ask is that, in our experience of doing this
sort of thing for over a decade, we know for sure that many API providers
(not all, but enough to poison the well) will provide whatever data makes
them look best as opposed to what data is most truthful. For example, API
providers will say they support hypermedia when they don't. That sort of
thing. Sometimes, it's because a non-technical person (eg: a marketing or
SEO person) is responsible for maintaining that data.

David Berlind
editor in chief
ProgrammableWeb.com

On Mon, Nov 21, 2016 at 12:14 PM, Ivan Gammel notifications@github.com
wrote:

I like this proposal and my company will eventually support it by
publishing some of our REST APIs this way. Some things I'd personally be
glad to see:

1. Indication of REST API maturity level (resources/verbs/HATEOAS)
2. For Level 3 REST APIs what are the supported formats (HAL, Siren
   etc)

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
#1423 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AGVduo_lEmMWgOsVzE7XChgN9qmivrzCks5rAdFogaJpZM4KnIBY
.

[chrisgandi]

This is really needed

[schwartzMS]

I would be interested in implementing this on our site.

[berezovskyi]

@dberlind I think the only reliable way to verify that the API conforms to its declaration is to have the API provide this information itself (e.g. https://www.w3.org/TR/ldp-primer/#filelookup for LDP-enabled apps, WSDL for SOAP etc.) and verify it programmatically. But this seems not to be the purpose behind this PR: it would be good to annotate the existing (i.e. legacy) APIs, in a noninvasive manner (i.e. via such tags in the API documentation).

[dberlind]

Thanks @andrew. What about subjective information that less easy to verify
and potentially more about gaming search? For example, referring to @ivan's
Medium post, if I'm an unscrupulous SEO (those don't exist, right?) or a
marketing person who is judged on eyeballs, and I know that the search term
"email API" is getting a lot of hits on Google, I might gladly put "email"
into the category field and description field (assuming those fields are
part of the schema) even if my API isn't exactly an email API. This is
exactly the behavior we've seen when crowdsourcing this data set on
ProgrammableWeb and we have wrestled with this problem for years. Also,
would a schema be deemed invalid (iow, not processable) if it was missing
the above suggested declaration? If the answer to that is "no," then
ultimately, you still have the issue of search results being gamed or
corrupted.

On Mon, Nov 21, 2016 at 1:05 PM, Andrew Berezovskyi <
notifications@github.com> wrote:

@dberlind https://github.com/dberlind I think the only reliable way to
verify that the API conforms to its declaration is to have the API provide
this information itself (e.g. https://www.w3.org/TR/ldp-primer/#filelookup
for LDP-enabled apps, WSDL for SOAP etc.) and verify it programmatically.
But this seems not to be the purpose behind this PR: it would be good to
annotate the existing (i.e. legacy) APIs, in a noninvasive manner (i.e. via
such tags in the API documentation).

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#1423 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AGVdutDE274hHwlC7qEFi-I0txHqpTHWks5rAd1RgaJpZM4KnIBY
.

[digitalmaster]

@IvanGoncharov This type of out of the box, community driven thinking is why i love what i do. Would love to see this implemented. 👍

[ivan-gammel]

@dberlind to defend from "dark" SEO, it may be useful to include "dependsOn" attribute to API and web site metadata, that will list all APIs referenced by the described resource. API providers will require the inclusion in dependsOn in their terms of service and search engines may use it to rank search results by popularity. API catalogs may also include the APIs that they list and have validated in their dependsOn attribute as a proof of the metadata correctness.

[dberlind]

thanks @ivan-gammel, I apologize, but your answer shot right over my head. For example, why would an API provider require "dependsOn" in their ToS? Algorithmically, how would "dependsOn" influence rank?

[jeffrogers]

Are there provisions to describe whether the API is publicly consumable or whether it requires authentication and authorization?

[shibumi]

Hi, everybody. I am a junior researcher and I am highly interested in this topic.
I just have a few questions: Did you thought about adding/using concepts of the OWL-S or WSMO for your WebAPI Ontology for schema.org?

I know, both concepts are from 2004. But there were people who thought about the same concepts.
For example they've have introduced the concept of "Inputs, Outputs, Preconditions, Effects" for a service. Input and Output refer to a a webAPI (you know, the normal JSON request and response...) + semantic description of both. Preconditions and Effects, however, refer to an action in the physical word.. like "your creditcard needs to be charged for using this service" and effects like:"Your creditcard is charged now"..

what do you think?

EDIT:

Some additional feedback: I am missing a 'targetPort' in your current model. Or do you plan to just set this port via URL or EndpointURL?

[westurner]

What would be necessary to support either or both standards with schema.org RDFS?

…

On Mon, Feb 3, 2020, 11:52 AM Christian Rebischke ***@***.***> wrote: Hi, everybody. I am a junior researcher and I am highly interested in this topic. I just have a few questions: Did you thought about adding/using concepts of the OWL-S or WSMO for your WebAPI Ontology for schema.org? I know, both concepts are from 2004. But there were people who thought about the same concepts. For example they've have introduced the concept of "Inputs, Outputs, Preconditions, Effects" for a service. Input and Output refer to a a webAPI (you know, the normal JSON request and response...) + semantic description of both. Preconditions and Effects, however, refer to an action in the physical word.. like "your creditcard needs to be charged for using this service" and effects like:"Your creditcard is charged now".. what do you think? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#1423?email_source=notifications&email_token=AAAMNS723CCXPRF3BTQA7QDRBBDU7A5CNFSM4CU4QBMKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEKUSFDY#issuecomment-581509775>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAMNS6FQM7VAZYT25UT7G3RBBDU7ANCNFSM4CU4QBMA> .

[shibumi]

I strongly suggest not to support it. However it would make sense to adopt concepts from both standards. The standards are de facto dead (nobody is using it, except a small research group bubble maybe). No tools exist for these standard and XML/WSDL seems pretty outdated, but the some of the concepts are great.

[shibumi]

So what needs to be done to finish this project? I have registered in the W3 community and I would like to help.

I've found also a paper that doesn't look so different: http://www.semantic-web-journal.net/system/files/swj1144.pdf

Do you have any paper about this webapi type submission?

[smrgeoinfo]

Some other efforts along these lines:
EarthCube Resource Registry, API resource type

Discussion of Machine actionable Links, somewhat dated, but covers a lot of the content information that needs to be accounted.

Example schema.org JSON-LD:
CHORDS
IRIS data
Template for service description, using potential action

There's a lot of interest in this in the science data community!

[smrgeoinfo]

see also https://github.com/schemaorg/schemaorg/issues/2340
https://github.com/schemaorg/schemaorg/issues/2342
https://github.com/earthcubearchitecture-project418/p419dcatservices
https://www.w3.org/TR/vocab-dcat-2/#Class:Data_Service
Machine Readable Web APIs with Schema.org

[smrgeoinfo]

From the perspective of EarthScience data, we're dealing with LOTS of data with varying degrees of granularity. Packaged 'datasets' that can be downloaded as files (simple sdo:downloadURL) are common, but volumetrically minor compared to the volume of data becoming available via API based services (for accessing legacy data) and dataFeeds for accessing real-time data. What we need are conventions for how to generate a high level record describing e.g.

• a monitoring site that has multiple sensors, with datafeeds from each sensor that are time series for which the sampling interval, and temporal coverage are important. Granular access to the actual time series required for research is via a webAPI that supports requests for site, sensor type, time window, aggregation...etc.

• a geochemical database that includes data from ~100K sites, multiple samples from a site, and various analytical results from each sample. Metadata needs to describe the webAPI that enables requests for particular sampled features, analytes, sampling time, analysis method...

• a geothermal well database that has ~million wells, with various logs and observation data for each well. Metadata needs to describe the webAPI that enables request for particular observations, from particular depths, particular formations, sampling time, observation method.

you get the picture... Some kind of API description that indicates what parameters can be specified for filtering, what kind of request input or response output format can be specified -- not just JSON, XML, RDF, but what is the schema, what vocabularies are used, what is the profile for the interchange format. URI templates are an obvious approach, but there also needs to be content negotiation possible on the requests , and there is currently no mechanism via URI templates to indicate content negotiation options....

[Sohamd00]

We at Sprinkle Data, use multiple APIs to extract the data.

[smrgeoinfo]

@Sohamd00 if those APIs were to be exposed via schema.org descriptions for indexing by some aggregator, and use by other client applications to automate access to Sprinkle data, how would you build those descriptions with schema.org vocabulary?

[Sohamd00]

@smrgeoinfo Sprinkle does extract and import data using API keys. But for building those descriptions with schema.org we need to have a detailed understanding.

[nickevansuk]

Just updating the thread here with some progress that has been made on this:

• https://webapi-discovery.github.io/rfcs/rfc0001.html has been updated based on the finalised DCAT v2 and the suggestions above, and its language translated into schema.org's machinery
• We've created a PR based on this: WebAPI update based on #1423 #2635

What do you think? Especially on the proposals included here: https://webapi-discovery.github.io/rfcs/rfc0001.html. Although they do not cover all use cases mentioned above, they do take us quite a few steps forward.

[nickevansuk]

So #2635 is now set for inclusion in the next schema.org release, however there is one outstanding issue that we're seeking consensus on...

It would be great to get your opinion on webapi-discovery/rfcs#10, in the context of this draft.

Any other feedback welcome of course!

[westurner]

Examples of how to represent GraphQL, SPARQL, LDP, and SOLID APIs would tremendously improve likelihood of adoption of this very useful method for API discovery.

When I link people to https://schema.org/WebAPI and reference #example2, I shouldn't expect them to do much more than copy and paste and change values.

[github-actions]

This issue is being tagged as Stale due to inactivity.

[nickevansuk]

Just noting this is currently blocked on @danbri response on #2635. We have consensus on this next step otherwise.

[ThisIsMissEm]

Should this also cover a services' privacy policy and acceptable use policy documents? (not just the terms of service)

[AlasdairGray]

Is the documentation property only for linking to the API definition or can it be used to link to other types of documentation and for other types of resources.

Could it be used to link a dataset to a web page that provides more detailed documentation about the dataset than you find on the landing page, e.g. for UniProt the landing page would point to uniprot.org but the documentation could link to the help page https://www.uniprot.org/help.