WebAPI update based on #1423

[nickevansuk]

As requested by @danbri in #1423 (comment), and in consultation with @MikeRalphson as per discussion in webapi-discovery/rfcs#6, this PR implements the latest recommendations from the W3C WebAPI Discovery Community Group.

See https://webapi-discovery.github.io/rfcs/rfc0001.html for the rationale behind these proposed changes.

[westurner]

Is the context still just http:// or does https:// work as well?

[nickevansuk]

Thanks for your feedback - https:// works too (see FAQ).

We went with https here based on the intention for schema.org to move towards it (see https://twitter.com/AlanBleiweiss/status/1221906673545043971 through to https://twitter.com/danbri/status/1222043362506747904), and that a pass would be made over the examples to align them (see same thread https://twitter.com/danbri/status/1222226001326944258). Can easily change if the intention is to keep everything http until such a pass is made?

[nickevansuk]

Looking at #2597, the https change now looks imminent - so perhaps good to stick with this in here?

[westurner]

When is something appropriate for endpointDescription and/or conformsTo?

…

On Wed, Aug 12, 2020, 6:24 AM Nick Evans ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In data/ext/pending/issue-1423.ttl <#2635 (comment)>: > + :category "issue-1423" ; + :domainIncludes :WebAPI ; + :isPartOf <http://pending.schema.org> ; + :rangeIncludes :EntryPoint, + :URL ; + :source <#1423> ; + rdfs:comment "The root location or primary endpoint of the API." . + +:conformsTo a rdf:Property ; + rdfs:label "conformsTo" ; + :category "issue-1423" ; + :domainIncludes :WebAPI ; + :isPartOf <http://pending.schema.org> ; + :rangeIncludes :URL ; + :source <#1423> ; + rdfs:comment "The URL reference of an established standard to which the described API conforms, for example `https://jsonapi.org/format/1.0/` <https://jsonapi.org/format/1.0/>, `https://grpc.io/` <https://grpc.io/>, or `http://www.hydra-cg.com/spec/latest/core/` <http://www.hydra-cg.com/spec/latest/core/>." . The idea with these examples is to show the breadth of conformsTo - it is not limited to just API specifications, but indeed any applicable standard or specification. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#2635 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAMNS2FQEEGYKLAFVGOPFDSAJUVLANCNFSM4OS5RCWQ> .

[nickevansuk]

@westurner see the documentation included in this PR:

schemaorg/data/ext/pending/issue-1423.ttl

Line 41 in c0dabcd

The [[endpointDescription]] property gives specific details of the actual endpoint instances, while the [[conformsTo]] property is used to indicate the general standard or specification that the endpoints implement.

Also see notes here for the derivation: https://webapi-discovery.github.io/rfcs/rfc0001.html#new-property-endpointdescription

This distinction is taken verbatim straight out of DCAT v2, see https://www.w3.org/TR/vocab-dcat-2/#Property:data_service_endpoint_description

[westurner]

Is there already an example (edit: in the schrma.org spec) where both are specified?

…

On Wed, Aug 12, 2020, 11:45 AM Nick Evans ***@***.***> wrote: @westurner <https://github.com/westurner> see the documentation included in this PR: https://github.com/schemaorg/schemaorg/blob/c0dabcdf099622e4b93375e06c8900e6ca96303f/data/ext/pending/issue-1423.ttl#L41 Also see notes here for the derivation: https://webapi-discovery.github.io/rfcs/rfc0001.html#new-property-endpointdescription This distinction is taken verbatim straight out of DCAT v2, see https://www.w3.org/TR/vocab-dcat-2/#Property:data_service_endpoint_description — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#2635 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAMNS7X6CUKWK4Z5SNHWYDSAK2KZANCNFSM4OS5RCWQ> .

[nickevansuk]

Yep, the main comprehensive example covers both, though in fairness the example data is not accurate (i.e. the Google Knowledge Graph Search API does not comply with JSON:API, or any specific wider standard/spec that I could identify?). We'd likely have to use a different API in the example if we wanted it to include accurate data...

schemaorg/data/ext/pending/issue-1423-examples.txt

Lines 58 to 69 in c0dabcd

	"endpointDescription": [
	{
	"@type": "CreativeWork",
	"encodingFormat": "application/json",
	"url": "https://kgsearch.googleapis.com/$discovery/rest?version=v1"
	},
	{
	"@type": "CreativeWork",
	"encodingFormat": "application/vnd.oai.openapi+json;version=3.0",
	"url": "https://api.apis.guru/v2/specs/googleapis.com/kgsearch/v1/openapi.json"
	}
	],

schemaorg/data/ext/pending/issue-1423-examples.txt

Lines 104 to 106 in c0dabcd

	"conformsTo": [
	"https://jsonapi.org/format/1.0/"
	],

[westurner]

While I'm sure it's not possible to satisfy every combination, it may be most helpful to include examples of at least these relatively common and/or linked data APIs:

• REST
• SPARQL
• GraphQL
• LDP

If there aren't Enumerations of the common specs, there's not likely to be any consistency in how people cite which version of the specs the API implements; so examples to copy/paste might make adoption easier and more likely

[nickevansuk]

Sure @westurner, this sounds like a good addition - either in this PR or a subsiquent PR to improve example coverage.

REST is already covered, however would you be able to create some examples for SPARQL, GraphQL, and LDP? It sounds like if we don't have time to do this right now it could easily go into a subsequent PR, as the comprehensive example we have already gives people a pretty solid steer, so no rush here, but agreed more examples are always good.

[westurner]

I'll add this to my queue. I agree that this can be done later

[nickevansuk]

Note the gRPC and Hydra examples have been removed from conformsTo, and gRPC added to the examples for apiTransport, as per #2635 (comment). See commit for details.

[nickevansuk]

Additionally have simplified references to documentation and endpointDescription in 33b33fe, as per #2635 (comment)

[danbri]

Why is the property called 'endpointUrl'? isn't it just a property whose value is the endpoint (an 'EntryPoint') that might have an 'url' property of its own?

[danbri]

On the /conformsTo comment - see also #1516 for the case to add it more generally than just for APIs. Replace mention of API with "to which the thing described conforms. Broadly equivalent to Dublin Core's "conformsTo" property - https://www.dublincore.org/specifications/dublin-core/dcmi-terms/#http://purl.org/dc/terms/conformsTo. We should set domainIncludes to at least /CreativeWork, possibly wider later.

[nickevansuk]

Replace mention of API with "to which the thing described conforms. Broadly equivalent to Dublin Core's "conformsTo" property - https://www.dublincore.org/specifications/dublin-core/dcmi-terms/#http://purl.org/dc/terms/conformsTo.

Included in commit c90261b. @danbri is that what you meant, or shall we remove the reference to Dublin Core from the description?

[nickevansuk]

Why is the property called 'endpointUrl'? isn't it just a property whose value is the endpoint (an 'EntryPoint') that might have an 'url' property of its own?

So there are a few reasons for this:

1. The naming of the property follows from DCAT v2's dcat:endpointURL

2. The inclusion of both EntryPoint and URL in the range mirrors the existing range of the documentation property and the use of the target property within the Actions document, to allow for simple usage
   

   schemaorg/data/ext/pending/issue-1423.ttl

   Lines 53 to 54 in c90261b

   	:rangeIncludes :EntryPoint,
   	:URL ;

3. The "endpoint" itself is described by machine-readable documentation referenced by the endpointDescription property. Part of the intention of the name endpointUrl is to avoid confusion around this property potentially being misused as a replacement for complete machine-readable documentation. It is strictly "The root location or primary endpoint of the API", potentially covering multiple environments, rather than attempting to compete with OpenAPI etc.

Alternative names include:

• endpointPrimaryUrl
• endpointBaseUrl

However depending on the API, the value could represent the base URL or primary endpoint... hence endpointUrl...

@danbri interested in your thoughts?

[nickevansuk]

@danbri I've removed references to endpointUrl from this PR given your feedback above, and the risks around it being misunderstood if named e.g. endpoint. We can easily include this in a future PR after further discussion.

It appears we have consensus on everything else.

[github-actions]

This pull request is being tagged as Stale due to inactivity.

[nickevansuk]

@danbri just nudging this, seems like it's just a case of you confirming you're happy with the above? #2635 (comment)

[MikeRalphson]

@danbri also popping in to ask if there's anything we can do to get this moving again? Very keen to get WebAPI out of Pending, and to adopt at least a subset of the proposed extension.

[nickevansuk]

Another nudge on this @danbri - what are the next steps here?

[smrgeoinfo]

why is this languishing?

[gmackenz]

The Knowledge Graph Search API (https://kgsearch.googleapis.com) no longer exists. It was shut down as an external API a few years ago. This WebAPI change needs to be reworked with another example. If you want to stick with Google, I suggest the YouTube API (https://developers.google.com/youtube/v3)