cardinality of webservice should be (0,n), right?

[gbinal]

It's currently listed as (0,1), but I think it should be (0,n) since there can be multiple endpoints for an API, right?

[haleyvandyck]

CC @MarinaMartin @seanherron who were involved last time we had the cardinality conversation....

[seanherron]

I believe my intent here was that the webservice should contain the highest level endpoint (eg. something like api.agency.com/schema if that exists). In the absence of a API outline, it should point to the most-inclusive URL. If an agency has api.agency.gov/locations, api.agency.gov/people, api.agency.gov/services, the endpoint should be api.agency.gov.

[mhogeweg]

hmmm. what if there is no highest level endpoint, but just 2 different API to the same dataset? one SOAP (register the WSDL in the record), one REST?

[cew821]

I also think a common pattern is that there is a landing page for developers describing how to get access to the API, how to use it, etc. This is not the same (usually) URI as the actual API. I've been a bit confused about whether to include a link like that as a webService URL or something else. But in general, as a developer, I would think getting a link to the developer docs / signups would be more helpful than getting the link to a top-level endpoint.

[seanherron]

@cew821 I think the intent is for the API landing page or documentation to be listed as a reference, but I agree that just an endpoint probably isn't very useful to most developers (though it does allow us to perhaps collect some meta information on how agencies are structuring endpoints).

[cew821]

Yeah, I suppose that's what is intended but practically it seems way more useful to call out an API landing page in some special way rather than just have it appear as one of many "references" to a given datasets. So for most of the datasets in our catalog, the webService url points to the API landing page.

[mhogeweg]

from an application development perspective, it is preferred to actually get the service API rather than API landing pages from a DCAT file. the API landing page is not guaranteed to be structured such that a client app can find the API reference there.

[gbinal]

what if there is no highest level endpoint, but just 2 different API to the same dataset? one SOAP (register the WSDL in the record), one REST?

I think that gets to my point. Another situation would be if the same API had http://www.agency.gov/api.json and http://www.agency.gov/api.xml as endpoints. Setting aside the wider questions here, it looks like changing the cardinality of from (0,1) to (0,n) seems solid. I'm addressing in issue #261.

[mhogeweg]

👍

[philipashlock]

reopening seeing how this is unresolved per #261

[philipashlock]

It's too late to change this for the current spec and I don't think this is the right approach anyway. I'd suggest we close this ticket as "won't fix" but continue the discussion on how the use of webService could be improved in a future version of the spec with #291

[gbinal]

It definitely seems there's an openness to having more than one API, but this issue is definitely subsumed by #291. I recommend that the conversation take place there instead.