-
Notifications
You must be signed in to change notification settings - Fork 812
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add "WebAPI" type #1423
Comments
This would complement work done here: |
@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. |
@danbri @RichardWallis I'm ready to start working on PR, can you please answer my questions?
|
@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. |
@RichardWallis I've pinged David and Wendell from ProgrammableWeb.com to voice their opinions here as well. Hopefully they respond shortly. |
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. |
@RichardWallis I think it's most important question and should be answered before technical ones. |
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) |
...so 'net API' instead of 'web API'? |
Hey Guys, URL : www.faasos.com |
With WebSockets and WebRTC, this is becoming less and less true. |
@clearbit would love to see this. |
Hey! |
As someone who already lost countless hours trying to find good APIs, I totally back up this idea. |
This sounds a lot like Hydra's
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? |
We (WhereIsMyTransport) would be very interested. |
We (stitchdata.com) extract data from dozens of APIs. We think this is a great idea. +1 |
+1 |
Would love to see this happen. |
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 |
On ProgrammableWeb, we are making reference more and more to "networkable" On Mon, Nov 21, 2016 at 11:27 AM, Mateo Murphy notifications@github.com
|
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:
|
Ivan, how does data get curated or policed? Is it essentially crowdsourced David Berlind On Mon, Nov 21, 2016 at 12:14 PM, Ivan Gammel notifications@github.com
|
This is really needed |
I would be interested in implementing this on our site. |
@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). |
Thanks @andrew. What about subjective information that less easy to verify On Mon, Nov 21, 2016 at 1:05 PM, Andrew Berezovskyi <
|
@IvanGoncharov This type of out of the box, community driven thinking is why i love what i do. Would love to see this implemented. 👍 |
@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. |
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? |
Are there provisions to describe whether the API is publicly consumable or whether it requires authentication and authorization? |
Hi, everybody. I am a junior researcher and I am highly interested in this topic. I know, both concepts are from 2004. But there were people who thought about the same concepts. 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? |
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>
.
|
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. |
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? |
Some other efforts along these lines: 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: There's a lot of interest in this in the science data community! |
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.
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.... |
We at Sprinkle Data, use multiple APIs to extract the data. |
@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? |
@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. |
Just updating the thread here with some progress that has been made on this:
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. |
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! |
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. |
This issue is being tagged as Stale due to inactivity. |
The meaning of iso19115 scope values are quite poorly documented, most relevant guess seems on comment at http://home.badc.rl.ac.uk/lawrence/blog/2008/03/19/the_scope_of_iso19115 I'm suggesting to use the extension type WebAPI for services, in stead of the dataCatalog type, this is the most relevant change, because service is used quite frequently in the scope of inspire. Following this discussion schemaorg/schemaorg#1423 we may actually be able to link WebAPI's to datasets soon. But we could also wait with merging this PR until schema-org has developed this as part of core
Should this also cover a services' privacy policy and acceptable use policy documents? (not just the terms of service) |
Is the 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. |
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:
1.0.0
I want to work on a PR adding
WebAPI
type toschema.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?
The text was updated successfully, but these errors were encountered: