Skip to content

Api example: registration

Jump to bottom
der edited this page Nov 18, 2012 · 7 revisions

Table of contents

In all the examples below a registration action is performed by a POST to the endpoint http://registry/reg1.

We omit prefix declarations simplicity of presentation.

Similarly we omit versioning of register items, showing the register item as it would appear if fetched using _view=with_metadata but no _view=version.

An arbitrary allocated identification number is shown as “xx”.

Simple registration of external entity

Payload

bc.<http://example.com/anentity> a skos:Concept;
skos:prefLabel “an entity”@en;
.

Result

bc.<http://registry/reg1/xx> a reg:RegisterItem;
rdfs:label “an entity”@en;
reg:itemClass skos:Concept;
reg:notation “xx”;
dct:dateSubmitted “2012-11-11T09:40:00Z”^^xsd:dateTime ;
reg:status reg:statusProposed ;
reg:definition <http://registry/reg1/1234:1#entityRef> ;
version:interval [ time:hasBeginning [ time:inXSDDateTime “2012-11-11T09:40:00Z”^^xsd:dateTime ] ];
.
<http://registry/reg1/_xx:1#entityRef> a reg:EntityReference;
reg:entity <http://example.com/anentity> ;
reg:sourceGraph <http://registry/reg1/xx:1#graph> ;
.
<http://registry/reg1/xx:1#graph> {
<http://example.com/anentity> a skos:Concept;
skos:prefLabel “an entity”@en;
.
}

Simple registration of an internal entity with explicit URI

Simple registration with automatic identifier allocation

Registration with an explicit item definition

Internal state of registry

We show a registry state with one register (/reg1) added to the root register and one external entity registered within /reg1.

Note that the act of creating the register, registering an entity, updating the status of the entity would in fact require several steps and so would result in several versions of each resource being created. We omit most of these versions here just for clarity.

Note also that in this example we use bNodes for some nested resources such as intervals. An implementation may choose to use URI resources instead to simplify data management.

# The root register
<http://registry> a reg:Register, version:VersionedThing ;
.
<http://registry:2> a reg:Register, version:Version;
    dct:isVersionOf <http://registry/reg>;
    owl:versionInfo "2";
    rdfs:label "root"@en;
    dct:description "The root register"@en;
    reg:owner      <http://example.com/UKLocation> ;
    reg:manager   <http://example.com/registryManagementLtd> ;
    reg:containedItemClass reg:Register;
    dct:replaces <http://registry:1>;
    version:interval [ time:hasBeginning [ time:inXSDDateTime "2012-11-11T08:00:00Z"^^xsd:dateTime ] ];
.
# A register 
<http://registry/reg1> a reg:Register, version:VersionedThing, skos:Collection ;
    ldp:membershipPredicate skos:member;
.
<http://registry/reg1:1> a reg:Register, version:Version, skos:Collection;
    dct:isVersionOf <http://registery/reg1>;
    owl:versionInfo "1";
    rdfs:label "register 1"@en;
    dct:description "Example register 1"@en;
    reg:owner      <http://example.com/department> ;
    reg:manager   <http://example.com/registryManagementLtd> ;
    reg:containedItemClass skos:Concept;
    ldp:membershipPredicate skos:member;
    version:interval [ time:hasBeginning [ time:inXSDDateTime "2012-11-11T07:00:00Z"^^xsd:dateTime ] ];
.
# item record linking the register to the root register
<http://registry/_reg1> a reg:RegisterItem, version:VersionedThing;
    reg:register <http://registry/reg> ;
    reg:notation "reg1";
    reg:itemClass  reg:Register;
.
<http://registry/_reg1:2> a reg:RegisterItem, version:Version;
    dct:isVersionOf <http://registry/reg1>;
    owl:versionInfo "2";
    rdfs:label "register 1"@en;
    dct:description "Example register 1"@en;
    dct:dateSubmitted "2012-11-11T09:00:00Z"^^xsd:dateTime ;
    dct:dateAccepted  "2012-11-11T09:10:00Z"^^xsd:dateTime ;
    reg:status  reg:statusValid ;
    reg:definition <http://registry/reg1#entityRef> ;
    dct:replaces <http://registry/reg1:1> ;
    version:interval [ time:hasBeginning [ time:inXSDDateTime "2012-11-11T09:00:00Z"^^xsd:dateTime ] ];
.
<http://registry/reg1#entityRef> a reg:EntityReference;
    reg:entity <http://registry/reg1> ;
.
# A single external entry registered in register /reg1 
<http://registry/reg1/_myconcept> a reg:RegisterItem, version:VersionedThing;
    reg:register <http://registry/reg1> ;
    reg:notation "myconcept";
    reg:itemClass  skos:Concept;
.
<http://registry/reg1/_myconcept:0> a reg:RegisterItem, version:Version;
    dct:isVersionOf <http://registry/reg1/_myconcept>;
    owl:versionInfo "0";
    rdfs:label "My concept"@en;
    dct:description "An externally defined entity"@en;
    dct:dateSubmitted "2012-11-11T09:20:00Z"^^xsd:dateTime ;
    dct:dateAccepted  "2012-11-11T09:20:00Z"^^xsd:dateTime ;
    reg:status  reg:statusValid ;
    reg:definition <http://registry/reg1/_myconcept:v0#entityRef> ;
    version:interval [ 
        time:hasBeginning [ time:inXSDDateTime "2012-11-11T09:20:00Z"^^xsd:dateTime ] 
        time:hasEnd       [ time:inXSDDateTime "2012-11-11T09:40:00Z"^^xsd:dateTime ] 
    ];
.
<http://registry/reg1/_myconcept:0#entityRef> a reg:EntityReference;
    reg:entity <http://example.com/mywebsite/myconcept> ;
    reg:sourceGraph <http://registry/reg1/_myconcept:0#graph> ;
.
# The named graph containing the stored copy of the external item
<http://registry/reg1/_myconcept:0#graph> {
    <http://example.com/mywebsite/myconcept> a skos:Concept;
        rdfs:label "My concept"@en;
        dct:description "An externally defined entity"@en;
    .    
}
# An updated version of the entry
<http://registry/reg1/_myconcept:1> a reg:RegisterItem, version:Version;
    dct:isVersionOf <http://registry/reg1/_myconcept>;
    owl:versionInfo "1";
    dct:replaces <http://registry/reg1/_myconcept:0>;
    rdfs:label "My shiny concept"@en;
    dct:description "An externally defined entity"@en;
    dct:dateSubmitted "2012-11-11T09:40:00Z"^^xsd:dateTime ;
    dct:dateAccepted  "2012-11-11T09:40:00Z"^^xsd:dateTime ;
    reg:status  reg:statusValid ;
    reg:definition <http://registry/reg1/_myconcept:1#entityRef> ;
    version:interval [ time:hasBeginning [ time:inXSDDateTime "2012-11-11T09:40:00Z"^^xsd:dateTime ] ];
.
<http://registry/reg1/_myconcept:1#entityRef> a reg:EntityReference;
    reg:entity <http://example.com/mywebsite/myconcept> ;
    reg:sourceGraph <http://registry/reg1/_myconcept:1#graph> ;
.
# The named graph containing the stored copy of the external item
<http://registry/reg1/_myconcept:1#graph> {
    <http://example.com/mywebsite/myconcept> a skos:Concept;
        rdfs:label "My shiny concept"@en;
        dct:description "An externally defined entity"@en;
    .    
}

Result of a read operation on the root register

GET http://registry/reg

Results in returned payload:

<http://registry> a reg:Register ;
    owl:versionInfo "2";
    rdfs:label "root"@en;
    dct:description "The root register"@en;
    reg:owner     <http://example.com/UKLocation> ;
    reg:manager   <http://example.com/registryManagementLtd> ;
    reg:containedItemClass reg:Register;
    rdfs:member   <http://registry/reg1> ;
.
<http://registry/reg1> a reg:Register, skos:Collection ;
    ldp:membershipPredicate skos:member;
    owl:versionInfo "1";
    rdfs:label "register 1"@en;
    dct:description "Example register 1"@en;
    reg:owner      <http://example.com/department> ;
    reg:manager    <http://example.com/registryManagementLtd> ;
    reg:containedItemClass skos:Concept;
    ldp:membershipPredicate skos:member;
.

Note: The VersionedThing and Version resources have been merged together for ease of consumption.

Note: The RegisterItem metadata has been omitted and instead a direct membership predicate asserted from the register (the root register in this case) to the entity in the definition of the registered item (in this case http://registry/reg1).

Note: Since no explicit ldp:membershipPredicate is defined for the root register the default of rdfs:member is used to relate the container to its entries.

Result of read operation on register /reg1

GET http://registry/reg1

Results in returned payload:

<http://registry/reg1> a reg:Register, skos:Collection ;
    ldp:membershipPredicate skos:member;
    owl:versionInfo "1";
    rdfs:label "register 1"@en;
    dct:description "Example register 1"@en;
    reg:owner     <http://example.com/department> ;
    reg:manager   <http://example.com/registryManagementLtd> ;
    reg:containedItemClass skos:Concept;
    ldp:membershipPredicate skos:member;
    skos:member   <http://example.com/mywebsite/myconcept>;
.
<http://example.com/mywebsite/myconcept>  a skos:Concept;
    rdfs:label "My shiny concept"@en;
    dct:description "An externally defined entity"@en;
.

Note: In this case there is an explicit declaration of ldp:membershipPredicate which is used to list the contents of the register.

Note: Only the latest version information has been returned.

Note: The stored description of the relevant version of the registered entity has been retrieved from its named graph and included in the return result.

Just read the metadata for /reg1

GET http://registry/reg1?non-member-properties

Results in returned payload:

<http://registry/reg1> a reg:Register, skos:Collection ;
    ldp:membershipPredicate skos:member;
    owl:versionInfo "1";
    rdfs:label "register 1"@en;
    dct:description "Example register 1"@en;
    reg:owner     <http://example.com/department> ;
    reg:manager   <http://example.com/registryManagementLtd> ;
    reg:containedItemClass skos:Concept;
    ldp:membershipPredicate skos:member;
    skos:member   <http://example.com/mywebsite/myconcept>;
.

Read the full item metadata for /reg1

GET http://registry/reg1?_view=with_metadata

Results in returned payload:

<http://registry/reg1> a reg:Register, skos:Collection ;
    owl:versionInfo "1";
    rdfs:label "register 1"@en;
    dct:description "Example register 1"@en;
    reg:owner      <http://example.com/department> ;
    reg:manager   <http://example.com/registryManagementLtd> ;
    reg:containedItemClass skos:Concept;
    ldp:membershipPredicate skos:member;
.
<http://registry/reg1/_myconcept> a reg:RegisterItem;
    reg:register <http://registry/reg1> ;
    reg:notation "myconcept";
    reg:itemClass  skos:Concept;
    owl:versionInfo "1";
    rdfs:label "My shiny concept"@en;
    dct:description "An externally defined entity"@en;
    dct:dateSubmitted "2012-11-11T09:40:00Z"^^xsd:dateTime ;
    dct:dateAccepted  "2012-11-11T09:40:00Z"^^xsd:dateTime ;
    reg:status  reg:statusValid ;
    reg:definition <http://registry/reg1/_myconcept:1#entityRef> ;
.
<http://registry/reg1/_myconcept:1#entityRef> a reg:EntityReference;
    reg:entity <http://example.com/mywebsite/myconcept> ;
    reg:sourceGraph <http://registry/reg1/_myconcept:1#graph> ;
.
<http://example.com/mywebsite/myconcept> a skos:Concept;
    rdfs:label "My shiny concept"@en;
    dct:description "An externally defined entity"@en;
.

Note: The relevant version of the regsitered entity itself has been retrieved from its named graph and included in the response payload.

Paged listing of /reg1

GET http://registry/reg1?firstPage

Results in returned payload:

<http://registry/reg1> a reg:Register, skos:Collection ;
    ldp:membershipPredicate skos:member;
    owl:versionInfo "1";
    rdfs:label "register 1"@en;
    dct:description "Example register 1"@en;
    reg:owner     <http://example.com/department> ;
    reg:manager   <http://example.com/registryManagementLtd> ;
    reg:containedItemClass skos:Concept;
    ldp:membershipPredicate skos:member;
    skos:member   <http://example.com/mywebsite/myconcept>;
.
<http://registry/reg1?firstPage> a ldp:Page;
    ldp:pageOf <http://registry/reg1>;
    # ldp:nextPage omited because there isn't one, pattern would be <http://registry/reg1?_page=1>;
    lda:items ( <http://example.com/mywebsite/myconcept> ) ;
    .
<http://example.com/mywebsite/myconcept>  a skos:Concept;
    rdfs:label "My shiny concept"@en;
    dct:description "An externally defined entity"@en;
.

Note: The page includes an ordered list of the entries on that page.

Return the full metadata and version information for /reg1

GET http://registry/reg/reg1?_view=version,with_metadata

Results in returned payload:

<http://registry/reg1> a reg:Register, version:VersionedThing, skos:Collection ;
    ldp:membershipPredicate skos:member;
    version:currentVersion <http://registry/reg1:1>;
.
<http://registry/reg1:1> a reg:Register, version:Version, skos:Collection;
    dct:isVersionOf <http://registery/reg1>;
    owl:versionInfo "1";
    rdfs:label "register 1"@en;
    dct:description "Example register 1"@en;
    reg:owner      <http://example.com/department> ;
    reg:manager   <http://example.com/registryManagementLtd> ;
    reg:containedItemClass skos:Concept;
    ldp:membershipPredicate skos:member;
    version:interval [ time:hasBeginning [ time:inXSDDateTime "2012-11-11T07:00:00Z"^^xsd:dateTime ] ];
.
<http://registry/reg1/_myconcept> a reg:RegisterItem, version:VersionedThing;
    reg:register <http://registry/reg1> ;
    reg:notation "myconcept";
    reg:itemClass  skos:Concept;
    version:currentVersion <http://registry/reg1/_myconcept:1>;
.
<http://registry/reg1/_myconcept:1> a reg:RegisterItem, version:Version;
    dct:isVersionOf <http://registry/reg1/_myconcept>;
    owl:versionInfo "1";
    dct:replaces <http://registry/reg1/_myconcept:0>;
    rdfs:label "My shiny concept"@en;
    dct:description "An externally defined entity"@en;
    dct:dateSubmitted "2012-11-11T09:40:00Z"^^xsd:dateTime ;
    dct:dateAccepted  "2012-11-11T09:40:00Z"^^xsd:dateTime ;
    reg:status  reg:statusValid ;
    reg:definition <http://registry/reg1/_myconcept:1#entityRef> ;
    version:interval [ time:hasBeginning [ time:inXSDDateTime "2012-11-11T09:40:00Z"^^xsd:dateTime ] ];
.
<http://registry/reg1/_myconcept:1#entityRef> a reg:EntityReference;
    reg:entity <http://example.com/mywebsite/myconcept> ;
    reg:sourceGraph <http://registry/reg1/_myconcept:1#graph> ;
.
<http://example.com/mywebsite/myconcept> a skos:Concept;
    rdfs:label "My shiny concept"@en;
    dct:description "An externally defined entity"@en;
.

Note: Returns only the current version and includes an inferred version:currentVersion link.

Note: It is possible to use the dct:replaces link to find the URI of a previous version of any resource and then retrieve that, and so walk back up the version graph.

Clone this wiki locally