Default Endpoint Structure

[recalcitrantsupplant]

Note: the endpoint structure is configurable, so for more complex or custom deployments the best answer should be "specify the endpoints exactly as you wish in Prez, yes this will require some minor code changes".

This discussion is to answer the question "what are sensible defaults for Prez endpoints structure out of the box."

The current endpoints are:
/catalogs/{catalogue_id}/collections/{collection_id}/items/{item_id}

This was drafted as a way to have a common set of endpoints for catalogs/spatial data/vocabularies. If we are going to change it now is the best time.

This diagram shows the target classes for each endpoint.

block-beta
    columns 6
            block:group1:2
                columns 2
                a["/catalogs"] b["/{catalog_id}"]
            end
            block:group2:2
                columns 2
                c["/collections"] d["/{collection_id}"]
            end
            block:group3:2
                columns 2
                e["/items"] f["/{item_id}"]
            end
        space space space space space space 
            block:group4:2
                columns 2
                g["dcat:Catalog"]
            end
            block:group5:2
                columns 2
                h["geo:FeatureCollection\ndcat:Resource\nskos:ConceptScheme\nskos:Collection"]
            end
            block:group6:2
                columns 2
                i["geo:Feature\nrdf:Resource\nskos:Concept"]
            end
group1-- "sh:targetClass" -->group4
group2-- "sh:targetClass" -->group5
group3-- "sh:targetClass" -->group6

Loading

@nicholascar @ashleysommer @edmondchuc

[ashleysommer]

My only concern here is that it essentially forces a skos:ConceptScheme to be a member of of a dcat:Catalog if we want to be able to display it in Prez. Is this reasonable?

[recalcitrantsupplant]

I agree that's a drawback.

Would implementing a second set of endpoints (in addition to the above) solve the issue? (The UI could then use either set of endpoints to render things).
I suspect the below may be required anyway for compliance with OGC Features - it does not say anything about collections needing to belong to catalogs - my reading of the spec is /collections would list all collections unless otherwise filtered.

block-beta
    columns 4
            block:group2:2
                columns 2
                c["/collections"] d["/{collection_id}"]
            end
            block:group3:2
                columns 2
                e["/items"] f["/{item_id}"]
            end
        space space space space
            block:group5:2
                columns 2
                h["geo:FeatureCollection\ndcat:Resource\nskos:ConceptScheme\nskos:Collection"]
            end
            block:group6:2
                columns 2
                i["geo:Feature\nrdf:Resource\nskos:Concept"]
            end
group2-- "sh:targetClass" -->group5
group3-- "sh:targetClass" -->group6

Loading

[ashleysommer]

Yep, I was just looking through the OGC Terminology API proposal slides, and indeed it seems like we will need both kinds:
/collections/{collId}/items/{itemId}
and
/catalogs/{catId}/collections/{collId}/items/{itemId}

The terminology API proposal even lists a potential third one specifcally for SKOS resources:
/catalogs/{catId}/conceptschemes/{csId}/items/{itemId}

[recalcitrantsupplant]

@nicholascar @ashleysommer
This is the current set of endpoints/relations in V4.
Can I please get feedback on what to do with the "vanilla" SpacePrez endpoint - should it be removed or does it need one more level added. Should there be another Catalog centric set of endpoints?

Endpoints Hierarchy

Listing Endpoints

Endpoint	OGC Features	What was previously SpacePrez	VocPrez Route 1	VocPrez Route 2
/catalogs	dcat:Catalog	dcat:Catalog	dcat:Catalog	dcat:Catalog
	dcterms:hasPart ⬇	dcterms:hasPart ⬇	dcterms:hasPart ⬇	dcterms:hasPart ⬇
/catalogs/{catalogId}/collections	dcat:Dataset	dcat:Dataset	skos:ConceptScheme	skos:Collection
	(skipped)	dcterms:hasPart ⬇	skos:inScheme ⬆	skos:member ⬇
/catalogs/{catalogId}/collections/{recordsCollectionId}/items	(skipped)	geo:FeatureCollection	skos:Concept	skos:Concept
	void:inDataset ⬆
{ROOT}/features/collections	geo:FeatureCollection
	rdfs:member ⬇
{ROOT}/features/collections/{collectionId}/items	geo:Feature

ROOT = /catalogs/{catalogId}/collections/{recordsCollectionId}

Object Endpoints

Endpoint
/catalogs/{catalogId}
/catalogs/{catalogId}/collections/{recordsCollectionId}
/catalogs/{catalogId}/collections/{recordsCollectionId}/items/{itemId}
{ROOT}/features/collections/{collectionId}
{ROOT}/features/collections/{collectionId}/items/{featureId}

Note: all resolved from curie -> iri

Hierarchical Endpoints

Endpoint	Parent / Child	Grandparent / Grandchild
/concept-hierarchy/{parent_curie}/top-concepts	skos:hasTopConcept / skos:topConceptOf	skos:narrower / skos:broader
/concept-hierarchy/{parent_curie}/narrowers	skos:narrower / skos:broader	skos:narrower / skos:broader

[nicholascar]

Let's try and test out the theory about by indicating what the endpoints for a series of known scenarios might look like:

1. BDR Top-level catalogues
2. BDR Vocabularies
3. A single BDR Vocabulary
4. BDR Datasets - main list (17k+)
5. The MERIT virtual dataset metadata endpoing
6. The MERIT virtual dataset occurrences Features API
7. A single dataset occurrences Features API
8. A single dataset all classes Features API
9. BDR Sites Features API
10. IDN Indigenous Studies Unit catalogue
11. IDN Indigenous Studies Unit single dataset endpoing
12. IDN Indigenous Studies Unit catalogue single spatial dataset Features API all classes
13. IDN Indigenous Studies Unit catalogue single spatial dataset Features API single classes
14. GSSA's Top-level catalogues (they only have vocabs)
15. GSSA's Top-level catalogues if they were to add spatial datasets

[recalcitrantsupplant]

See https://docs.google.com/spreadsheets/d/1xko043nk146rZ5lYXLw0ru0HzBO5D4m6JN6HHVMhlMw/edit?usp=sharing