Skip to content
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

WebAPI update based on #1423 #2635

Open
wants to merge 10 commits into
base: main
Choose a base branch
from
Open

Conversation

nickevansuk
Copy link

@nickevansuk nickevansuk commented Jul 7, 2020

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
Copy link
Contributor

westurner commented Jul 7, 2020

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

@nickevansuk
Copy link
Author

nickevansuk commented Jul 7, 2020

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
Copy link
Author

nickevansuk commented Jul 8, 2020

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

data/ext/pending/issue-1423.ttl Outdated Show resolved Hide resolved
@westurner
Copy link
Contributor

westurner commented Aug 12, 2020

@nickevansuk
Copy link
Author

nickevansuk commented Aug 12, 2020

@westurner see the documentation included in this PR:

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
Copy link
Contributor

westurner commented Aug 12, 2020

@nickevansuk
Copy link
Author

nickevansuk commented Aug 12, 2020

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...

"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"
}
],

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

@westurner
Copy link
Contributor

westurner commented Aug 12, 2020

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
Copy link
Author

nickevansuk commented Aug 12, 2020

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
Copy link
Contributor

westurner commented Aug 12, 2020

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

@nickevansuk
Copy link
Author

nickevansuk commented Aug 14, 2020

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
Copy link
Author

nickevansuk commented Aug 17, 2020

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

Copy link
Contributor

@danbri danbri left a comment

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?

Copy link
Contributor

@danbri danbri left a comment

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
Copy link
Author

nickevansuk commented Aug 25, 2020

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
Copy link
Author

nickevansuk commented Aug 25, 2020

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

    :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
Copy link
Author

nickevansuk commented Nov 10, 2020

@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
Copy link

github-actions bot commented Feb 15, 2021

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

@github-actions github-actions bot added the no-pr-activity Discuss has gone quiet. Auto-tagging to encourage people to re-engage with the issue (or close it!). label Feb 15, 2021
@nickevansuk
Copy link
Author

nickevansuk commented Feb 15, 2021

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

@MikeRalphson
Copy link

MikeRalphson commented Apr 14, 2021

@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
Copy link
Author

nickevansuk commented Aug 6, 2021

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

@smrgeoinfo
Copy link

smrgeoinfo commented Nov 18, 2021

why is this languishing?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
no-pr-activity Discuss has gone quiet. Auto-tagging to encourage people to re-engage with the issue (or close it!).
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

6 participants