How to describe distribution via WebAPI

[smrgeoinfo]

https://github.com/schemaorg/schemaorg/issues/1423

please check it out

[rduerr]

Agreed absolutely important and your comments were apropos....

[smrgeoinfo]

also link to #78, https://github.com/schemaorg/schemaorg/issues/2360, https://github.com/schemaorg/schemaorg/issues/2340, https://github.com/schemaorg/schemaorg/issues/2342

p419dcatservices readme Accessing Data through a Service Endpoint

[smrgeoinfo]

Last chance! there's a schema.org pull request in with a proposal https://github.com/schemaorg/schemaorg/pull/2635

here's the proposal https://webapi-discovery.github.io/rfcs/rfc0001.html

[smrgeoinfo]

Apparently schema.org hasn't moved ahead on schemaorg/schemaorg#2635. In the mean time Web of Things (WoT) Thing Description 1.1 W3C First Public Working Draft 24 November 2020 is out for comments. From the point of view of a web client, a software agent invoked by WebAPI is no different from a physical 'Thing' actuated via a web request. The WoT handling of actions is really pretty good and should work equally for interacting with any agent on the web. Looks to me like a good path forward for machine actionable descriptions of webAPIs, but its not Schema.org...

[smrgeoinfo]

The current dataset.md guidance for Accessing Data through a Service Endpoint recommends documented service access via the potentialAction property on a dataset. I suggest it would be clearer if the potentialAction was nested in a distribution/DataDownload element, something like this:

"distribution":
{            "@type": [ "DataDownload", "WebAPI"],
            "name": "Argovis WebAPI",
            "serviceType": "Argovis API",
            "documentation": "https://argovis.colorado.edu/api-docs/#/",
            "description": "Access Argo profiles via API, i.e. temperature, salinity, and biogeochemical data by location. Argo metadata, float trajectory forecasts, gridded fields, weather events are also available through API",
            "potentialAction": {
                "@type": "SearchAction",
                "target": {
                    "@type": "EntryPoint",
                    "urlTemplate": "https://argovis.colorado.edu/selection/profiles?startDate={start}&endDate={end}&shape={shape}&presRange={presRange}",
                    "description": "download profiles within a bounding box for specified start/end dates",
                    "httpMethod": ["GET"]         },
                "query-input": [
                    {   "@type": "PropertyValueSpecification",
                        "valueName": "shape",
                        "description": "list of lists containing [lon, lat] coordinates that define a polygon; first and last coordinate pair should be the same point. example: shape = [[[-144.84375,36.031332],[-136.038755,36.210925],[-127.265625,35.746512],[-128.144531,22.755921],[-136.543795,24.835311],[-145.195313,26.431228],[-144.84375,36.031332]]]",
                        "valueRequired": true            },
                    {  "@type": "PropertyValueSpecification",
                        "valueName": "start",
                        "description": "string formatted as 'YYYY-MM-DD'",
                        "valueRequired": true             },
                    {   "@type": "PropertyValueSpecification",
                        "valueName": "end",
                        "description": "string formatted as 'YYYY-MM-DD'",
                        "valueRequired": true                },
                    {   "@type": "PropertyValueSpecification",
                        "valueName": "presRange",
                        "description": "a string of a list formatted as '[minimum pres,maximum pres]' (no spaces)",
                        "valueRequired": false,
                        "defaultValue": "None"                } 
                 ],
                "result":{
                    "@type":"Dataset",
                    "encodingFormat":"application/json"
                }            }        },

Typing as both DataDownload and WebAPI allows inclusion of the serviceType and documentation links, with the documentation link pointing to something like an OpenAPI/swagger document that self-describes the service. Automated clients can identify an WebAPI access (like a dcat:accessService/dcat:DataService) and connect with this information.