Last edited 2 days ago
by Massimiliano Branca

ShareDoc:Search API: Difference between revisions

No edit summary
Line 1: Line 1:
<div style="border:1px solid #f5c6cb; background:#f8d7da; padding:10px; margin:10px 0;">
<div style="border:1px solid #f5c6cb; background:#f8d7da; padding:10px; margin:10px 0;">
'''Attenzione:''' Le ricerche root <code>/works</code>, <code>/instances</code>,
'''Warning:''' The root searches <code>/works</code>, <code>/instances</code>,
<code>/items</code> e <code>/dates</code> richiedono il ruolo '''svde-editor-base''' e non sono
<code>/items</code> and <code>/dates</code> require the '''svde-editor-base''' role and are not
accessibili con il solo scope <code>svde-resource-read</code>. Un integratore di sola lettura deve
accessible with the <code>svde-resource-read</code> scope alone. A read-only integrator must use
usare la navigazione gerarchica.
hierarchical navigation instead.
</div>
</div>


Line 63: Line 63:
</syntaxhighlight>
</syntaxhighlight>
==<span id="Resource_2" class="mw-headline">Resource</span>==
==<span id="Resource_2" class="mw-headline">Resource</span>==
<div style="border:1px solid #ffeeba; background:#fff3cd; padding:10px; margin:10px 0;">
'''Nota:''' endpoint temporaneamente non disponibile su alcuni ambienti (errore lato server in corso di
risoluzione). Verificare lo stato prima di farne affidamento in un'integrazione.
</div>
A ShareVDE resource is an abstract and high-level concept which maps agents and opuses.
A ShareVDE resource is an abstract and high-level concept which maps agents and opuses.


Line 71: Line 77:
|+Request Parameters
|+Request Parameters
!'''Name'''
!'''Name'''
!'''Type'''
! '''Type'''
!'''Description'''
!'''Description'''
!'''Cardinality'''
!'''Cardinality'''
Line 77: Line 83:
|-
|-
|q
|q
| String
|String
|An agent query expressed in [[ShareVDEmembers:APIdoc/Query Languages#SvdeQL|SVDEQL]] or TermsQL (terms)  
|An agent query expressed in [[ShareVDEmembers:APIdoc/Query Languages#SvdeQL|SVDEQL]] or TermsQL (terms)
|1
|1
|N.A.
|N.A.  
|-
|-
|sort
|sort
|String
|String
|A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)
|A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)  
|0...1
|0...1
|N.A.  
|N.A.
|-
|-
|offset
|offset
|Integer
|Integer
|A positive integer indicating the start offset of results (fts mode only)
| A positive integer indicating the start offset of results (fts mode only)
| 0...1
|0...1
|0
|0
|-
|-
|rows
|rows
|Integer
|Integer
|A positive integer indicating the returned page size (fts mode only)
| A positive integer indicating the returned page size (fts mode only)
|0...1
|0...1
|10
|10
|-
|-
| partialMatch  
|partialMatch
|Boolean
|Boolean
| Forces a partial match search (entered query terms are considered optional)
| Forces a partial match search (entered query terms are considered optional)
|0...1
|0...1  
|false
|false
|-
|-
|[[ShareDoc:API documentation#Filters|filter]]
|[[ShareDoc:API documentation#Filters|filter]]  
|String
|String
|A filter clause used for refining search results
|A filter clause used for refining search results
|0...n
|0...n
|N.A.
| N.A.
|}
|}
==<span id="Agent" class="mw-headline">Agent</span>==
==<span id="Agent" class="mw-headline">Agent</span>==
The Agent is an abstract concept which concretely maps people, organisations, conferences, families, jurisdictions, etc., that play a role (or even multiple roles) such as authors, editors, distributors, illustrator, publisher, etc.
The Agent is an abstract concept which concretely maps people, organisations, conferences, families, jurisdictions, etc., that play a role (or even multiple roles) such as authors, editors, distributors, illustrator, publisher, etc.
Line 123: Line 131:
!'''Type'''
!'''Type'''
!'''Description'''
!'''Description'''
! '''Cardinality'''  
!'''Cardinality'''
!'''Default Value'''
!'''Default Value'''
|-
|-
|q
|q
|String
| String  
|An agent query expressed in [[ShareVDEmembers:APIdoc/Query Languages#SvdeQL|SVDEQL]] or TermsQL (terms)
|An agent query expressed in [[ShareVDEmembers:APIdoc/Query Languages#SvdeQL|SVDEQL]] or TermsQL (terms)
|1
| 1
|N.A.
|N.A.
|-
|-
|mode
|mode
| Enum
|Enum
|One among '''fts''' (fulltext search) and '''typeahead'''
|One among '''fts''' (fulltext search) and '''typeahead'''
|0...1
| 0...1
|fts
|fts
|-
|-
|sort
| sort
| String  
|String
|A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)
|A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)
|0...1
|0...1
|N.A.
|N.A.  
|-
|-
|offset
|offset
Line 160: Line 168:
|Enables / disables the fuzzy logic (typeahead mode only)
|Enables / disables the fuzzy logic (typeahead mode only)
|0...1
|0...1
|true  
|true
|-
|-
| edits
|edits
|Integer
|Integer
| Max edit distance in fuzzy logic. Can be 1 or 2 (typeahead mode only)
|Max edit distance in fuzzy logic. Can be 1 or 2 (typeahead mode only)
|0...1
|0...1
|1
|1
Line 187: Line 195:
Returns the opuses of the agent associated with the given identifier.
Returns the opuses of the agent associated with the given identifier.
{| class="wikitable"
{| class="wikitable"
|+Request Parameters
|+ Request Parameters
!'''Name'''
!'''Name'''
!'''Type'''
!'''Type'''
Line 194: Line 202:
!'''Default Value'''
!'''Default Value'''
|-
|-
|offset
| offset  
|Integer
|Integer
|A positive integer indicating the start offset of results (fts mode only)
|A positive integer indicating the start offset of results (fts mode only)
Line 200: Line 208:
|0
|0
|-
|-
|rows  
|rows
|Integer
|Integer
|A positive integer indicating the returned page size (fts mode only)
|A positive integer indicating the returned page size (fts mode only)
|0...1
|0...1
|10
| 10
|-
|-
|sort
|sort
Line 215: Line 223:
|String
|String
|A filter clause used for refining search results
|A filter clause used for refining search results
|0...n
|0...n  
|N.A.
|N.A.
|-
|-
Line 224: Line 232:
|N.A.
|N.A.
|}<span id="Examples_2" class="mw-headline">'''Examples'''</span>
|}<span id="Examples_2" class="mw-headline">'''Examples'''</span>
*[https://sit2-base-svde.atcult.it/agents.json?q=agents%20whose%20name%20contains%20carroll Agents whose names contains carroll]
* [https://sit2-base-svde.atcult.it/agents.json?q=agents%20whose%20name%20contains%20carroll Agents whose names contains carroll]
*[https://sit2-base-svde.atcult.it/agents.json?q=agents%20whose%20name%20contains%20carroll&sort=name%20asc&rows=2&offset=2 A sublist of all agents whose name contains carroll, sorted by name and paged]
*[https://sit2-base-svde.atcult.it/agents.json?q=agents%20whose%20name%20contains%20carroll&sort=name%20asc&rows=2&offset=2 A sublist of all agents whose name contains carroll, sorted by name and paged]
*[https://sit2-base-svde.atcult.it/agents.json?q=carro&mode=typeahead Agents typeahead search using '''carro''']
*[https://sit2-base-svde.atcult.it/agents.json?q=carro&mode=typeahead Agents typeahead search using '''carro''']
*[https://sit2-base-svde.atcult.it/agents.json?q=carto&mode=typeahead&fuzzy=true Agents typeahead search using '''carto''' (fuzzy match)]
*[https://sit2-base-svde.atcult.it/agents.json?q=carto&mode=typeahead&fuzzy=true Agents typeahead search using '''carto''' (fuzzy match)]
* [https://sit2-base-svde.atcult.it/agents.json?q=carto&mode=typeahead&fuzzy=false Agents typeahead search using '''carto''' (no fuzzy)]
*[https://sit2-base-svde.atcult.it/agents.json?q=carto&mode=typeahead&fuzzy=false Agents typeahead search using '''carto''' (no fuzzy)]
*[https://sit2-base-svde.atcult.it/agents/201.json Lewis Carroll]
* [https://sit2-base-svde.atcult.it/agents/201.json Lewis Carroll]  
==<span id="Person" class="mw-headline"><span id="Agent" class="mw-headline">Person</span></span>==
== <span id="Person" class="mw-headline"><span id="Agent" class="mw-headline">Person</span></span>==
A person is an individual or identity established by an individual (either alone or in collaboration with one or more other individuals). It is a concrete subclass of Agent and provides a set of attributes, both datatype and object properties which interconnect the entity to opuses and other bibliographic entities in the Share-VDE domain model.
A person is an individual or identity established by an individual (either alone or in collaboration with one or more other individuals). It is a concrete subclass of Agent and provides a set of attributes, both datatype and object properties which interconnect the entity to opuses and other bibliographic entities in the Share-VDE domain model.


Line 241: Line 249:
!'''Type'''
!'''Type'''
!'''Description'''
!'''Description'''
! '''Cardinality'''  
!'''Cardinality'''
!'''Default Value'''
!'''Default Value'''
|-
|-
|q
|q
|String
|String  
|A people query expressed in [[ShareVDEmembers:APIdoc/Query Languages#SvdeQL|SVDEQL]] or TermsQL (terms)
|A people query expressed in [[ShareVDEmembers:APIdoc/Query Languages#SvdeQL|SVDEQL]] or TermsQL (terms)
|1
|1
Line 251: Line 259:
|-
|-
|mode
|mode
| Enum
|Enum
|One among '''fts''' (fulltext search) and '''typeahead'''
|One among '''fts''' (fulltext search) and '''typeahead'''
|0...1
|0...1  
|fts
|fts
|-
|-
|sort
|sort  
| String  
|String
|A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)
|A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)
|0...1
|0...1
|N.A.
| N.A.
|-
|-
|offset
|offset
|Integer
|Integer
| A positive integer indicating the start offset of results (fts mode only)
|A positive integer indicating the start offset of results (fts mode only)
|0...1
|0...1  
|0
|0
|-
|-
Line 272: Line 280:
|A positive integer indicating the returned page size (fts mode only)
|A positive integer indicating the returned page size (fts mode only)
|0...1
|0...1
|10
| 10
|-
|-
|fuzzy
|fuzzy
Line 281: Line 289:
|-
|-
|edits
|edits
|Integer  
|Integer
|Max edit distance in fuzzy logic. Can be 1 or 2 (typeahead mode only)
|Max edit distance in fuzzy logic. Can be 1 or 2 (typeahead mode only)
|0...1
|0...1
Line 287: Line 295:
|-
|-
|partialMatch
|partialMatch
|Boolean
|Boolean  
|Forces a partial match search (simple search only)
|Forces a partial match search (simple search only)
| 0...1
| 0...1
Line 294: Line 302:
|[[ShareVDEmembers:APIdoc#Filters|filter]]
|[[ShareVDEmembers:APIdoc#Filters|filter]]
|String
|String
|A filter clause used for refining search results
|A filter clause used for refining search results  
|0...n
|0...n  
|N.A.
|N.A.
|}<span id=".2Fpeople.2F.7Bid.7D" class="mw-headline">'''/people/{id}'''</span>
|}<span id=".2Fpeople.2F.7Bid.7D" class="mw-headline">'''/people/{id}'''</span>
Line 305: Line 313:
Returns the opuses of the person associated with the given identifier.
Returns the opuses of the person associated with the given identifier.
{| class="wikitable"
{| class="wikitable"
|+Request Parameters
|+ Request Parameters
!'''Name'''
!'''Name'''
!'''Type'''
!'''Type'''
Line 314: Line 322:
|offset
|offset
|Integer
|Integer
|A positive integer indicating the start offset of results (fts mode only)
|A positive integer indicating the start offset of results (fts mode only)  
|0...1
|0...1  
|0
|0
|-
|-
|rows
| rows
|Integer
|Integer
|A positive integer indicating the returned page size (fts mode only)
|A positive integer indicating the returned page size (fts mode only)
Line 324: Line 332:
|10
|10
|-
|-
|sort
| sort  
|String
|String
| A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)
|A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)
|0...1
|0...1
|N.A.
|N.A.
Line 336: Line 344:
|N.A.
|N.A.
|-
|-
|role
| role
|String
|String
|The relator code used for refining the type of contribution
|The relator code used for refining the type of contribution
Line 350: Line 358:


<span id="Examples_3" class="mw-headline">'''Examples'''</span>
<span id="Examples_3" class="mw-headline">'''Examples'''</span>
*[https://sit2-base-svde.atcult.it/people.json?q=people%20whose%20name%20contains%20carroll People whose names contains carroll]
* [https://sit2-base-svde.atcult.it/people.json?q=people%20whose%20name%20contains%20carroll People whose names contains carroll]
*[https://sit2-base-svde.atcult.it/people.json?q=people%20whose%20name%20contains%20carroll&sort=name%20asc&rows=2&offset=2 A sublist of all people whose name contains carroll, sorted by name and paged]
*[https://sit2-base-svde.atcult.it/people.json?q=people%20whose%20name%20contains%20carroll&sort=name%20asc&rows=2&offset=2 A sublist of all people whose name contains carroll, sorted by name and paged]
*[https://sit2-base-svde.atcult.it/people.json?q=carro&mode=typeahead People typeahead search using '''carro''']
*[https://sit2-base-svde.atcult.it/people.json?q=carro&mode=typeahead People typeahead search using '''carro''']
*[https://sit2-base-svde.atcult.it/people.json?q=carto&mode=typeahead&fuzzy=true People typeahead search using '''carto''' (fuzzy match)]
*[https://sit2-base-svde.atcult.it/people.json?q=carto&mode=typeahead&fuzzy=true People typeahead search using '''carto''' (fuzzy match)]
*[https://sit2-base-svde.atcult.it/people.json?q=carto&mode=typeahead&fuzzy=false People typeahead search using '''carto''' (no fuzzy)]
*[https://sit2-base-svde.atcult.it/people.json?q=carto&mode=typeahead&fuzzy=false People typeahead search using '''carto''' (no fuzzy)]
*[https://sit2-base-svde.atcult.it/people/201.json Lewis Carroll]  
*[https://sit2-base-svde.atcult.it/people/201.json Lewis Carroll]
*[https://sit2-base-svde.atcult.it/people/201/occupations.json Lewis Carroll's occupations]
*[https://sit2-base-svde.atcult.it/people/201/occupations.json Lewis Carroll's occupations]
*[https://sit2-base-svde.atcult.it/people/201/opuses.json Lewis Carroll's opuses]
*[https://sit2-base-svde.atcult.it/people/201/opuses.json Lewis Carroll's opuses]
Line 367: Line 375:
|+Request Parameters
|+Request Parameters
!'''Name'''
!'''Name'''
! '''Type'''  
!'''Type'''
!'''Description'''  
!'''Description'''
!'''Cardinality'''
! '''Cardinality'''
!'''Default Value'''
!'''Default Value'''
|-
|-
Line 379: Line 387:
|-
|-
|mode
|mode
| Enum
|Enum
|One among '''fts''' (fulltext search) and '''typeahead'''
|One among '''fts''' (fulltext search) and '''typeahead'''
|0...1
|0...1  
|fts
|fts
|-
|-
|sort
|sort  
| String  
|String
|A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)
|A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)
|0...1
|0...1
|N.A.
| N.A.
|-
|-
|offset
|offset
|Integer
|Integer
| A positive integer indicating the start offset of results (fts mode only)
|A positive integer indicating the start offset of results (fts mode only)
|0...1
|0...1
|0
|0
Line 402: Line 410:
|10
|10
|-
|-
|fuzzy
|fuzzy  
|Boolean
|Boolean
|Enables / disables the fuzzy logic (typeahead mode only)
|Enables / disables the fuzzy logic (typeahead mode only)
|0...1
|0...1
| true
|true  
|-
|-
|edits
|edits
Line 417: Line 425:
|Boolean
|Boolean
|Forces a partial match search (simple search only)
|Forces a partial match search (simple search only)
| 0...1
|0...1  
|false  
|false
|-
|-
|[[ShareVDEmembers:APIdoc#Filters|filter]]
|[[ShareVDEmembers:APIdoc#Filters|filter]]
Line 443: Line 451:
|Integer
|Integer
|A positive integer indicating the start offset of results (fts mode only)
|A positive integer indicating the start offset of results (fts mode only)
|0...1
| 0...1
|0
|0
|-
|-
|rows
|rows
|Integer
|Integer  
|A positive integer indicating the returned page size (fts mode only)
|A positive integer indicating the returned page size (fts mode only)
|0...1
| 0...1  
|10
|10
|-
|-
Line 461: Line 469:
|String
|String
|A filter clause used for refining search results
|A filter clause used for refining search results
|0...n
|0...n  
|N.A.
|N.A.
|-
|-
Line 467: Line 475:
|String
|String
|The relator code used for refining the type of contribution
|The relator code used for refining the type of contribution
|0...1  
|0...1
|aut
| aut
|}<span id="Examples_4" class="mw-headline">'''Examples'''</span>
|}<span id="Examples_4" class="mw-headline">'''Examples'''</span>
*[https://sit2-base-svde.atcult.it/meetings.json?q=meetings%20whose%20name%20contains%20eaton Meetings whose names contains eaton]
*[https://sit2-base-svde.atcult.it/meetings.json?q=meetings%20whose%20name%20contains%20eaton Meetings whose names contains eaton]
Line 475: Line 483:
*[https://sit2-base-svde.atcult.it/meetings.json?q=iat&mode=typeahead&fuzzy=false Meetings typeahead search using '''iat''' (no fuzzy)]
*[https://sit2-base-svde.atcult.it/meetings.json?q=iat&mode=typeahead&fuzzy=false Meetings typeahead search using '''iat''' (no fuzzy)]
*[https://sit2-base-svde.atcult.it/meetings/3.json Annual J. Lloyd Eaton Conference on Science Fiction and Fantasy Literature]
*[https://sit2-base-svde.atcult.it/meetings/3.json Annual J. Lloyd Eaton Conference on Science Fiction and Fantasy Literature]
==<span id="Organisation" class="mw-headline">Organization</span> ==
==<span id="Organisation" class="mw-headline">Organization</span>==
A corporation or group of persons and/or organisations that acts, or may act, as a unit. It is a concrete subclass of Agent and provides a set of attributes, both datatype and object property which interconnect the entity to opuses and other bibliographic entities in the Share-VDE domain model.
A corporation or group of persons and/or organisations that acts, or may act, as a unit. It is a concrete subclass of Agent and provides a set of attributes, both datatype and object property which interconnect the entity to opuses and other bibliographic entities in the Share-VDE domain model.


Line 485: Line 493:
!'''Name'''
!'''Name'''
!'''Type'''
!'''Type'''
!'''Description'''
!'''Description'''  
!'''Cardinality'''
!'''Cardinality'''
!'''Default Value'''
!'''Default Value'''
|-
|-
|q
|q
|String
|String  
|An organisation query expressed in [[ShareVDEmembers:APIdoc/Query Languages#SvdeQL|SVDEQL]] or TermsQL (terms)
|An organisation query expressed in [[ShareVDEmembers:APIdoc/Query Languages#SvdeQL|SVDEQL]] or TermsQL (terms)
|1
|1
|N.A.
| N.A.
|-
|-
|mode
|mode
| Enum
|Enum
|One among '''fts''' (fulltext search) and '''typeahead'''
|One among '''fts''' (fulltext search) and '''typeahead'''
|0...1
|0...1
Line 502: Line 510:
|-
|-
|sort
|sort
| String  
|String
|A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)
|A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)
|0...1
| 0...1
|N.A.
|N.A.
|-
|-
|offset
|offset
|Integer
|Integer
| A positive integer indicating the start offset of results (fts mode only)
|A positive integer indicating the start offset of results (fts mode only)
|0...1
| 0...1
|0
|0
|-
|-
Line 537: Line 545:
|false
|false
|-
|-
| [[ShareVDEmembers:APIdoc#Filters|filter]]
|[[ShareVDEmembers:APIdoc#Filters|filter]]
|String
|String
|A filter clause used for refining search results
|A filter clause used for refining search results
|0...n
|0...n
|N.A.
|N.A.  
|}<span id=".2Forganisations.2F.7Bid.7D" class="mw-headline">'''/organizations/{id}'''</span>
|}<span id=".2Forganisations.2F.7Bid.7D" class="mw-headline">'''/organizations/{id}'''</span>


Line 553: Line 561:
!'''Name'''
!'''Name'''
!'''Type'''
!'''Type'''
!'''Description'''
! '''Description'''
!'''Cardinality'''
!'''Cardinality'''
!'''Default Value'''
!'''Default Value'''
Line 566: Line 574:
|Integer
|Integer
|A positive integer indicating the returned page size (fts mode only)
|A positive integer indicating the returned page size (fts mode only)
|0...1
|0...1  
|10
| 10
|-
|-
|sort
|sort
|String
|String
|A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)  
|A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)
| 0...1
|0...1  
|N.A.
|N.A.
|-
|-
Line 578: Line 586:
|String
|String
|A filter clause used for refining search results
|A filter clause used for refining search results
|0...n
|0...n  
|N.A.
| N.A.
|-
|-
|role
|role
|String
|String
|The relator code used for refining the type of contribution
| The relator code used for refining the type of contribution
| 0...1
|0...1
| aut
|aut
|}<span id="Examples_5" class="mw-headline">'''Examples'''</span>
|}<span id="Examples_5" class="mw-headline">'''Examples'''</span>
* [https://sit2-base-svde.atcult.it/organisations.json?q=organisations%20whose%20name%20doesn%27t%20contain%20xyz First 10 organisations whose name doesn't contain '''xyz''']
*[https://sit2-base-svde.atcult.it/organisations.json?q=organisations%20whose%20name%20doesn%27t%20contain%20xyz First 10 organisations whose name doesn't contain '''xyz''']
*[https://sit2-base-svde.atcult.it/organisations.json?q=organisations%20whose%20name%20doesn%27t%20contain%20xyz&sort=name%20desc&rows=3&offset=2 A sublist of all organisations whose name doesn't contain '''xyz''', sorted by name and paged]
*[https://sit2-base-svde.atcult.it/organisations.json?q=organisations%20whose%20name%20doesn%27t%20contain%20xyz&sort=name%20desc&rows=3&offset=2 A sublist of all organisations whose name doesn't contain '''xyz''', sorted by name and paged]
*[https://sit2-base-svde.atcult.it/organisations.json?q=intern&mode=typeahead Organisations typeahead search using '''intern''']
*[https://sit2-base-svde.atcult.it/organisations.json?q=intern&mode=typeahead Organisations typeahead search using '''intern''']
*[https://sit2-base-svde.atcult.it/organisations.json?q=intrn&mode=typeahead&fuzzy=true Organisations typeahead search using '''intrn''' (fuzzy match)]  
*[https://sit2-base-svde.atcult.it/organisations.json?q=intrn&mode=typeahead&fuzzy=true Organisations typeahead search using '''intrn''' (fuzzy match)]
*[https://sit2-base-svde.atcult.it/organisations.json?q=intrn&mode=typeahead&fuzzy=false Organisations typeahead search using '''intrn''' (no fuzzy)]
*[https://sit2-base-svde.atcult.it/organisations.json?q=intrn&mode=typeahead&fuzzy=false Organisations typeahead search using '''intrn''' (no fuzzy)]
*[https://sit2-base-svde.atcult.it/organisations/101.json American Library Association (ALA)]
*[https://sit2-base-svde.atcult.it/organisations/101.json American Library Association (ALA)]
Line 604: Line 612:
!'''Type'''
!'''Type'''
!'''Description'''
!'''Description'''
! '''Cardinality'''  
!'''Cardinality'''
!'''Default Value'''
!'''Default Value'''
|-
|-
|q
|q
|String
|String
|A family query expressed in [[ShareVDEmembers:APIdoc/Query Languages#SvdeQL|SVDEQL]] or TermsQL (terms)
|A family query expressed in [[ShareVDEmembers:APIdoc/Query Languages#SvdeQL|SVDEQL]] or TermsQL (terms)  
|1
|1
|N.A.
|N.A.
|-
|-
|mode
|mode
| Enum
|Enum
|One among '''fts''' (fulltext search) and '''typeahead'''
|One among '''fts''' (fulltext search) and '''typeahead'''
|0...1
|0...1
|fts
|fts  
|-
|-
|sort
|sort
| String  
|String
|A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)
|A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)
|0...1
|0...1
Line 627: Line 635:
|offset
|offset
|Integer
|Integer
| A positive integer indicating the start offset of results (fts mode only)
|A positive integer indicating the start offset of results (fts mode only)
|0...1
|0...1
|0
|0
Line 639: Line 647:
|fuzzy
|fuzzy
|Boolean
|Boolean
|Enables / disables the fuzzy logic (typeahead mode only)
|Enables / disables the fuzzy logic (typeahead mode only)  
|0...1
|0...1
| true
|true  
|-
|-
|edits
|edits
|Integer  
|Integer
|Max edit distance in fuzzy logic. Can be 1 or 2 (typeahead mode only)  
|Max edit distance in fuzzy logic. Can be 1 or 2 (typeahead mode only)
|0...1
|0...1
|1
|1
|-
|-
|partialMatch
|partialMatch
|Boolean
| Boolean
|Forces a partial match search (simple search only)
|Forces a partial match search (simple search only)
|0...1
|0...1
Line 670: Line 678:
|+Request Parameters
|+Request Parameters
!'''Name'''
!'''Name'''
!'''Type'''
!'''Type'''  
!'''Description'''
!'''Description'''
!'''Cardinality'''
!'''Cardinality'''
!'''Default Value'''
!'''Default Value'''  
|-
|-
|offset
|offset
Line 691: Line 699:
|A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)
|A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)
|0...1
|0...1
|N.A.  
|N.A.
|-
|-
|[[ShareVDEmembers:APIdoc#Filters|filter]]
|[[ShareVDEmembers:APIdoc#Filters|filter]]
|String
|String
|A filter clause used for refining search results
|A filter clause used for refining search results
|0...n
|0...n  
|N.A.
|N.A.
|-
|-
|role
|role
|String
| String
|The relator code used for refining the type of contribution
| The relator code used for refining the type of contribution
|0...1
|0...1
|aut  
|aut
|}<span id="Examples_6" class="mw-headline">'''Examples'''</span>
|}<span id="Examples_6" class="mw-headline">'''Examples'''</span>
*[https://sit2-base-svde.atcult.it/families.json?q=families%20whose%20name%20doesn%27t%20contain%20xyz First 10 families whose name doesn't contain '''xyz''']
*[https://sit2-base-svde.atcult.it/families.json?q=families%20whose%20name%20doesn%27t%20contain%20xyz First 10 families whose name doesn't contain '''xyz''']
Line 717: Line 725:
Fulltext search across Share-VDE opuses.
Fulltext search across Share-VDE opuses.
{| class="wikitable"
{| class="wikitable"
|+Request Parameters
|+ Request Parameters
!'''Name'''
!'''Name'''
!'''Type'''
!'''Type'''
!'''Description'''  
!'''Description'''
!'''Cardinality'''  
!'''Cardinality'''  
!'''Default Value'''
!'''Default Value'''
Line 732: Line 740:
|sort
|sort
|String
|String
|A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)  
|A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)
|0...1
|0...1
|N.A.
|N.A.
Line 743: Line 751:
|-
|-
|rows
|rows
| Integer
|Integer  
| A positive integer indicating the returned page size (fts mode only)
|A positive integer indicating the returned page size (fts mode only)
|0...1
|0...1
|10
|10
|-
|-
|partialMatch
|partialMatch  
|Boolean
|Boolean
|Forces a partial match search (simple search only)  
|Forces a partial match search (simple search only)
|0...1
|0...1
|false
|false
Line 757: Line 765:
|String
|String
|A filter clause used for refining search results
|A filter clause used for refining search results
|0...n
|0...n  
| N.A.
|N.A.
|}<span id=".2Fopuses.2F.7Bid.7D" class="mw-headline">'''/opuses/{id}'''</span>
|}<span id=".2Fopuses.2F.7Bid.7D" class="mw-headline">'''/opuses/{id}'''</span>


Line 767: Line 775:
Returns the contributors of a given opus.
Returns the contributors of a given opus.
{| class="wikitable"
{| class="wikitable"
|+Request Parameters
|+ Request Parameters
!'''Name'''
!'''Name'''
!'''Type'''
!'''Type'''
Line 774: Line 782:
!'''Default Value'''
!'''Default Value'''
|-
|-
|offset
|offset  
|Integer
|Integer
|A positive integer indicating the start offset of results (fts mode only)
|A positive integer indicating the start offset of results (fts mode only)
|0...1
|0...1
|0
| 0
|-
|-
|rows
|rows
|Integer
|Integer
|A positive integer indicating the returned page size (fts mode only)
|A positive integer indicating the returned page size (fts mode only)
|0...1
|0...1  
|10
|10
|-
|-
Line 790: Line 798:
|A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)
|A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)
|0...1
|0...1
| N.A.
|N.A.
|-
|-
|[[ShareVDEmembers:APIdoc#Filters|filter]]
|[[ShareVDEmembers:APIdoc#Filters|filter]]
|String
|String
|A filter clause used for refining search results
|A filter clause used for refining search results  
|0...n
|0...n
|N.A.
|N.A.  
|-
|-
| role  
|role
|String  
|String
|The relator code used for refining the type of contribution
|The relator code used for refining the type of contribution
|0...1
|0...1
Line 820: Line 828:
|offset
|offset
|Integer
|Integer
| A positive integer indicating the start offset of results (fts mode only)
|A positive integer indicating the start offset of results (fts mode only)
|0...1
|0...1
|0
|0
Line 826: Line 834:
|rows
|rows
|Integer
|Integer
|A positive integer indicating the returned page size (fts mode only)  
|A positive integer indicating the returned page size (fts mode only)
| 0...1
|0...1
|10  
|10
|-
|-
|sort
|sort
|String
|String
|A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)
|A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)  
|0...1
|0...1
|N.A.
| N.A.
|-
|-
|[[ShareVDEmembers:APIdoc#Filters|filter]]
|[[ShareVDEmembers:APIdoc#Filters|filter]]
Line 852: Line 860:
!'''Name'''
!'''Name'''
!'''Type'''
!'''Type'''
!'''Description'''
! '''Description'''
!'''Cardinality'''
!'''Cardinality'''
!'''Default Value'''
!'''Default Value'''
Line 858: Line 866:
|offset
|offset
|Integer
|Integer
| A positive integer indicating the start offset of results (fts mode only)
|A positive integer indicating the start offset of results (fts mode only)
|0...1
| 0...1
|0
|0
|-
|-
|rows
|rows  
|Integer
|Integer
|A positive integer indicating the returned page size (fts mode only)
|A positive integer indicating the returned page size (fts mode only)
Line 875: Line 883:
|-
|-
|[[ShareVDEmembers:APIdoc#Filters|filter]]
|[[ShareVDEmembers:APIdoc#Filters|filter]]
| String
|String
|A filter clause used for refining search results
|A filter clause used for refining search results
|0...n
|0...n
Line 889: Line 897:
|+Request Parameters
|+Request Parameters
!'''Name'''
!'''Name'''
!'''Type'''
!'''Type'''  
!'''Description'''
!'''Description'''
!'''Cardinality'''
!'''Cardinality'''
Line 896: Line 904:
|offset
|offset
|Integer
|Integer
| A positive integer indicating the start offset of results (fts mode only)
|A positive integer indicating the start offset of results (fts mode only)
|0...1
|0...1
|0
|0
Line 903: Line 911:
|Integer
|Integer
|A positive integer indicating the returned page size (fts mode only)
|A positive integer indicating the returned page size (fts mode only)
| 0...1
|0...1
|10
|10
|-
|-
Line 930: Line 938:
!'''Description'''
!'''Description'''
!'''Cardinality'''
!'''Cardinality'''
!'''Default Value'''
!'''Default Value'''  
|-
|-
|offset
|offset
|Integer
|Integer
| A positive integer indicating the start offset of results (fts mode only)
|A positive integer indicating the start offset of results (fts mode only)  
|0...1
|0...1
|0
|0
|-
|-
|rows
|rows
|Integer
|Integer  
| A positive integer indicating the returned page size (fts mode only)
|A positive integer indicating the returned page size (fts mode only)
|0...1
|0...1
|10
|10
Line 952: Line 960:
|[[ShareVDEmembers:APIdoc#Filters|filter]]
|[[ShareVDEmembers:APIdoc#Filters|filter]]
|String
|String
|A filter clause used for refining search results  
|A filter clause used for refining search results
|0...n  
|0...n
|N.A.
|N.A.
|}<span id=".2Fopuses.2F.7Bid.7D.2Fworks.2F.7BworkId.7D.2Finstances.2F.7BinstanceId.7D.2Fitems.2F.7BitemId.7D" class="mw-headline">'''/opuses/{id}/works/{workId}/instances/{instanceId}/items/{itemId}'''</span>
|}<span id=".2Fopuses.2F.7Bid.7D.2Fworks.2F.7BworkId.7D.2Finstances.2F.7BinstanceId.7D.2Fitems.2F.7BitemId.7D" class="mw-headline">'''/opuses/{id}/works/{workId}/instances/{instanceId}/items/{itemId}'''</span>
Line 961: Line 969:
<span id="Examples_7" class="mw-headline">'''Examples'''</span>
<span id="Examples_7" class="mw-headline">'''Examples'''</span>


Note that since the exact type of the agent cannot be known in advance, the request makes use of the ...on <type> construct.
Note that since the exact type of the agent cannot be known in advance, the request makes use of the ...on <type> construct.  
*[https://sit2-base-svde.atcult.it/opuses.json?q=opuses%20whose%20title%20contains%20alice Opuses whose title contains alice]
*[https://sit2-base-svde.atcult.it/opuses.json?q=opuses%20whose%20title%20contains%20alice Opuses whose title contains alice]
*[https://sit2-base-svde.atcult.it/opuses/401.json Alice in Wonderland (Opus)]
*[https://sit2-base-svde.atcult.it/opuses/401.json Alice in Wonderland (Opus)]  
*[https://sit2-base-svde.atcult.it/opuses/401/contributors.json Contributors of Alice in Wonderland]
*[https://sit2-base-svde.atcult.it/opuses/401/contributors.json Contributors of Alice in Wonderland]  
*[https://sit2-base-svde.atcult.it/opuses/401/contributors.json?role=aut Authors of Alice in Wonderland]
*[https://sit2-base-svde.atcult.it/opuses/401/contributors.json?role=aut Authors of Alice in Wonderland]
*[https://sit2-base-svde.atcult.it/opuses/401/works.json Alice in Wonderland (Works)]
*[https://sit2-base-svde.atcult.it/opuses/401/works.json Alice in Wonderland (Works)]
*[https://sit2-base-svde.atcult.it/opuses/401/works/401-1/instances.json Alice in Wonderland (Instances of a Work)]
*[https://sit2-base-svde.atcult.it/opuses/401/works/401-1/instances.json Alice in Wonderland (Instances of a Work)]
* [https://sit2-base-svde.atcult.it/opuses/401/works/401-1/instances/I0001.json Alice in Wonderland (an Instance)]  
*[https://sit2-base-svde.atcult.it/opuses/401/works/401-1/instances/I0001.json Alice in Wonderland (an Instance)]
*[https://sit2-base-svde.atcult.it/opuses/401/works/401-1/instances/I0001/items.json Alice in Wonderland (items of the instance above)]
*[https://sit2-base-svde.atcult.it/opuses/401/works/401-1/instances/I0001/items.json Alice in Wonderland (items of the instance above)]
*[https://sit2-base-svde.atcult.it/opuses/401/works/401-1/instances/I0001/items/501.json Alice in Wonderland (an item from the list above)]
*[https://sit2-base-svde.atcult.it/opuses/401/works/401-1/instances/I0001/items/501.json Alice in Wonderland (an item from the list above)]
Line 984: Line 992:
|+Request Parameters
|+Request Parameters
!'''Name'''
!'''Name'''
!'''Type'''
!'''Type'''  
!'''Description'''
!'''Description'''
!'''Cardinality'''
!'''Cardinality'''
!'''Default Value'''
!'''Default Value'''  
|-
|-
|offset
|offset
|Integer
|Integer
|A positive integer indicating the start offset of results (fts mode only)
|A positive integer indicating the start offset of results (fts mode only)
|0...1
| 0...1
|0
|0
|-
|-
|rows
|rows  
|Integer
|Integer
|A positive integer indicating the returned page size (fts mode only)
|A positive integer indicating the returned page size (fts mode only)  
|0...1
|0...1  
|10
|10
|-
|-
Line 1,009: Line 1,017:
|[[ShareVDEmembers:APIdoc#Filters|filter]]
|[[ShareVDEmembers:APIdoc#Filters|filter]]
|String
|String
|A filter clause used for refining search results  
|A filter clause used for refining search results
|0...n
|0...n
|N.A.
|N.A.
|-
|-
| role
|role
|String
|String
|The relator code used for refining the type of contribution
|The relator code used for refining the type of contribution
Line 1,026: Line 1,034:
Returns the instances of a work.
Returns the instances of a work.
{| class="wikitable"
{| class="wikitable"
|+Request Parameters
|+ Request Parameters
!'''Name'''
!'''Name'''
!'''Type'''
!'''Type'''
!'''Description'''
!'''Description'''
!'''Cardinality'''
!'''Cardinality'''  
!'''Default Value'''
!'''Default Value'''
|-
|-
|offset
|offset
|Integer
|Integer
| A positive integer indicating the start offset of results (fts mode only)
|A positive integer indicating the start offset of results (fts mode only)  
|0...1
|0...1
|0
|0
|-
|-
|rows
| rows
|Integer
|Integer
|A positive integer indicating the returned page size (fts mode only)
|A positive integer indicating the returned page size (fts mode only)
Line 1,054: Line 1,062:
|String
|String
|A filter clause used for refining search results
|A filter clause used for refining search results
| 0...n
|0...n
|N.A.
|N.A.
|}<span id=".2Fworks.2F.7BworkId.7D.2Finstances.2F.7BinstanceId.7D" class="mw-headline">'''/works/{workId}/instances/{instanceId}'''</span>
|}<span id=".2Fworks.2F.7BworkId.7D.2Finstances.2F.7BinstanceId.7D" class="mw-headline">'''/works/{workId}/instances/{instanceId}'''</span>
Line 1,071: Line 1,079:
!'''Default Value'''
!'''Default Value'''
|-
|-
|offset
| offset
|Integer
|Integer
| A positive integer indicating the start offset of results (fts mode only)
|A positive integer indicating the start offset of results (fts mode only)
|0...1
|0...1
| 0
|0
|-
|-
|rows
|rows
|Integer
|Integer
|A positive integer indicating the returned page size (fts mode only)
|A positive integer indicating the returned page size (fts mode only)
|0...1  
|0...1
|10
|10
|-
|-
|sort
|sort
|String
|String
| A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)
|A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)
| 0...1
|0...1
|N.A.  
|N.A.
|-
|-
| [[ShareVDEmembers:APIdoc#Filters|filter]]
|[[ShareVDEmembers:APIdoc#Filters|filter]]
|String
|String
|A filter clause used for refining search results
|A filter clause used for refining search results
Line 1,100: Line 1,108:
<span id="Examples_8" class="mw-headline">'''Examples'''</span>
<span id="Examples_8" class="mw-headline">'''Examples'''</span>


Note that since the exact type of the agent cannot be known in advance, the request makes use of the ...on <type> construct.
Note that since the exact type of the agent cannot be known in advance, the request makes use of the ...on <type> construct.  
*[https://sit2-base-svde.atcult.it/works/401-1/instances.json Alice in Wonderland (Instances of a Work)]
*[https://sit2-base-svde.atcult.it/works/401-1/instances.json Alice in Wonderland (Instances of a Work)]
*[https://sit2-base-svde.atcult.it/works/401-1/instances/I0001.json Alice in Wonderland (an Instance)]
*[https://sit2-base-svde.atcult.it/works/401-1/instances/I0001.json Alice in Wonderland (an Instance)]
*[https://sit2-base-svde.atcult.it/works/401-1/instances/I0001/items.json Alice in Wonderland (items of the instance above)]
*[https://sit2-base-svde.atcult.it/works/401-1/instances/I0001/items.json Alice in Wonderland (items of the instance above)]
*[https://sit2-base-svde.atcult.it/works/401-1/instances/I0001/items/501.json Alice in Wonderland (an item from the list above)]
*[https://sit2-base-svde.atcult.it/works/401-1/instances/I0001/items/501.json Alice in Wonderland (an item from the list above)]  
==<span id="Instance" class="mw-headline">Instance</span>==
==<span id="Instance" class="mw-headline">Instance</span>==
A Work may have one or more individual, material embodiments, for example, a particular published form. These are Instances of the Work. An Instance reflects information such as its publisher, place and date of publication, and format<sup class="reference" id="cite_ref-:1_2-1">[[ShareVDEmembers:APIdoc/RESTFul API#cite%20note-%3A1-2|[2]]]</sup>.
A Work may have one or more individual, material embodiments, for example, a particular published form. These are Instances of the Work. An Instance reflects information such as its publisher, place and date of publication, and format<sup class="reference" id="cite_ref-:1_2-1">[[ShareVDEmembers:APIdoc/RESTFul API#cite%20note-%3A1-2|[2]]]</sup>.
Line 1,149: Line 1,157:
|offset
|offset
|Integer
|Integer
| A positive integer indicating the start offset of results (fts mode only)
|A positive integer indicating the start offset of results (fts mode only)
|0...1
|0...1
|0
| 0
|-
|-
|rows
|rows
Line 1,157: Line 1,165:
|A positive integer indicating the returned page size (fts mode only)
|A positive integer indicating the returned page size (fts mode only)
|0...1
|0...1
|10  
|10
|-
|-
|sort
|sort
Line 1,167: Line 1,175:
|[[ShareVDEmembers:APIdoc#Filters|filter]]
|[[ShareVDEmembers:APIdoc#Filters|filter]]
|String
|String
|A filter clause used for refining search results
|A filter clause used for refining search results  
|0...n
|0...n  
|N.A.
| N.A.
|}<span id=".2Finstances.2F.7BinstanceId.7D.2Fitems.2F.7BitemId.7D" class="mw-headline">'''/instances/{instanceId}/items/{itemId}'''</span>
|}<span id=".2Finstances.2F.7BinstanceId.7D.2Fitems.2F.7BitemId.7D" class="mw-headline">'''/instances/{instanceId}/items/{itemId}'''</span>


Line 1,187: Line 1,195:
Returns a specific item.
Returns a specific item.


<span id="Examples_10" class="mw-headline">'''Examples'''</span>
<span id="Examples_10" class="mw-headline">'''Examples'''</span>  
*[https://sit2-base-svde.atcult.it/items/501.json An item, literal attributes and an object properties (availability)]
*[https://sit2-base-svde.atcult.it/items/501.json An item, literal attributes and an object properties (availability)]
== <span id="Publication" class="mw-headline">Publication</span>==
==<span id="Publication" class="mw-headline">Publication</span>==
A publication is a logical entity which wraps together an instance (including the items) plus the parent Work. Being the instance the central entity, its local identifier is used also for denoting the corresponding publication identity (and URI)
A publication is a logical entity which wraps together an instance (including the items) plus the parent Work. Being the instance the central entity, its local identifier is used also for denoting the corresponding publication identity (and URI)


Line 1,220: Line 1,228:
|String
|String
|A publication query expressed in [[ShareVDEmembers:APIdoc/Query Languages#SvdeQL|SVDEQL]]
|A publication query expressed in [[ShareVDEmembers:APIdoc/Query Languages#SvdeQL|SVDEQL]]
| 1
|1
|N.A.
|N.A.
|-
|-
|sort
|sort
|String
|String
|A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)
|A valid [[ShareVDEmembers:APIdoc#Sort|sort]] clause (fts mode only)
|0...1
|0...1
|N.A.
| N.A.
|-
|-
|offset  
| offset
|Integer
|Integer
|A positive integer indicating the start offset of results (fts mode only)
|A positive integer indicating the start offset of results (fts mode only)
|0...1
|0...1
Line 1,237: Line 1,247:
|rows
|rows
|Integer
|Integer
|A positive integer indicating the returned page size (fts mode only)  
|A positive integer indicating the returned page size (fts mode only)
|0...1
|0...1
| 10
|10
|-
|-
| [[ShareVDEmembers:APIdoc#Filters|filter]]
|[[ShareVDEmembers:APIdoc#Filters|filter]]
| String
|String  
|A filter clause used for refining search results
|A filter clause used for refining search results
|0...n
|0...n
| N.A.
|N.A.
|}<span id=".2Fpublications.2F.7Bid.7D" class="mw-headline">/publications/{id}</span>
|}<span id=".2Fpublications.2F.7Bid.7D" class="mw-headline">/publications/{id}</span>


Returns the publication associated with the given identifier.
Returns the publication associated with the given identifier.
==<span id="Controlled_Vocabulary_Entities" class="mw-headline">Controlled Vocabulary Entities</span> ==
==<span id="Controlled_Vocabulary_Entities" class="mw-headline">Controlled Vocabulary Entities</span>==
Other than the entities described above, referred as "core entities", the Share-VDE domain model includes some other entities that are gathered from external sources, assigned a Share-VDE URI and linked to core entities.
Other than the entities described above, referred as "core entities", the Share-VDE domain model includes some other entities that are gathered from external sources, assigned a Share-VDE URI and linked to core entities.


Line 1,289: Line 1,299:
*Language
*Language
*Agent Type
*Agent Type
* Genre
*Genre
* Occupation
* Occupation
*Availability
*Availability
Line 1,308: Line 1,318:
!'''Type'''
!'''Type'''
!'''Description'''
!'''Description'''
!'''Cardinality'''
! '''Cardinality'''
!'''Default Value'''
!'''Default Value'''
|-
|-
| q
|q
|String
|String
|A typeahead query expressed in TermsQL (terms)  
|A typeahead query expressed in TermsQL (terms)
|1
|1
|N.A.
|N.A.
|-
|-
|fuzzy
|fuzzy
|Boolean
| Boolean
|Enables / disables the fuzzy logic (typeahead mode only)  
|Enables / disables the fuzzy logic (typeahead mode only)
|0...1
| 0...1
|true
|true  
|-
|-
|edits
|edits

Revision as of 10:12, 3 July 2026

Warning: The root searches /works, /instances, /items and /dates require the svde-editor-base role and are not accessible with the svde-resource-read scope alone. A read-only integrator must use hierarchical navigation instead.

Stats

The /stats endpoint returns high-level aggregations about the whole knowledge base. There's an "extended" boolean parameter which drives the response format, specifically:

When it is set to false, the response is very concise, see the following example:

{
  "item": 137,
  "agent": {
    "person": 54,
    "organization": 16,
    "family": 16,
    "meeting": 9
  },
  "instance": 146,
  "opus": 120,
  "work": 138,
  "subject": 103
}

The response returns the counts for each entity type. The "agent" is actually a group that contains the agent types counts. It is possible to set a request parameter called "provenance" that will cause the response to return only provenance-specific values. The response in this case has exactly the same shape but counts refer only to the requested provenance. In case the extended parameter is set to true, then the response is more articulated because counts are broken by provenance:

  "https://svde.org/agents/NLF": {
    "item": 3,
    "agent": {
      "person": 4,
      "organization": 2,
      "family": 1
    },
    "instance": 4,
    "work": 5,
    "opus": 3,
    "totalCount": 22
  },
  "https://svde.org/agents/NYU": {
    "item": 7,
    "agent": {
      "person": 4,
      "organization": 1,
      "family": 3,
      "meeting": 2
    },
    "instance": 7,
    "work": 8,
    "opus": 8,
    "totalCount": 40
  },
  "https://svde.org/agents/NORTHWESTERN": {
    "agent": {
      "person": 1,
      "meeting": 1
    },
    "instance": 1,
    "work": 2,
    "opus": 2,
    "totalCount": 7
  },
  ...

Resource

Nota: endpoint temporaneamente non disponibile su alcuni ambienti (errore lato server in corso di risoluzione). Verificare lo stato prima di farne affidamento in un'integrazione.

A ShareVDE resource is an abstract and high-level concept which maps agents and opuses.

/resources

Simple search across Share-VDE resources.

Request Parameters
Name Type Description Cardinality Default Value
q String An agent query expressed in SVDEQL or TermsQL (terms) 1 N.A.
sort String A valid sort clause (fts mode only) 0...1 N.A.
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
partialMatch Boolean Forces a partial match search (entered query terms are considered optional) 0...1 false
filter String A filter clause used for refining search results 0...n N.A.


Agent

The Agent is an abstract concept which concretely maps people, organisations, conferences, families, jurisdictions, etc., that play a role (or even multiple roles) such as authors, editors, distributors, illustrator, publisher, etc.

/agents

Fulltext or Typeahead search across Share-VDE agents.

Request Parameters
Name Type Description Cardinality Default Value
q String An agent query expressed in SVDEQL or TermsQL (terms) 1 N.A.
mode Enum One among fts (fulltext search) and typeahead 0...1 fts
sort String A valid sort clause (fts mode only) 0...1 N.A.
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
fuzzy Boolean Enables / disables the fuzzy logic (typeahead mode only) 0...1 true
edits Integer Max edit distance in fuzzy logic. Can be 1 or 2 (typeahead mode only) 0...1 1
partialMatch Forces a partial match search (simple search only) 0...1 false
filter String A filter clause used for refining search results 0...n N.A.

/agents/{agentId}

Returns the agent associated with the given identifier.

/agents/{agentId}/opuses

Returns the opuses of the agent associated with the given identifier.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.
role String The relator code used for refining the type of contribution 0...1 N.A.

Examples

Person

A person is an individual or identity established by an individual (either alone or in collaboration with one or more other individuals). It is a concrete subclass of Agent and provides a set of attributes, both datatype and object properties which interconnect the entity to opuses and other bibliographic entities in the Share-VDE domain model.

/people

Fulltext or Typeahead search across Share-VDE people.

Request Parameters
Name Type Description Cardinality Default Value
q String A people query expressed in SVDEQL or TermsQL (terms) 1 N.A.
mode Enum One among fts (fulltext search) and typeahead 0...1 fts
sort String A valid sort clause (fts mode only) 0...1 N.A.
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
fuzzy Boolean Enables / disables the fuzzy logic (typeahead mode only) 0...1 true
edits Integer Max edit distance in fuzzy logic. Can be 1 or 2 (typeahead mode only) 0...1 1
partialMatch Boolean Forces a partial match search (simple search only) 0...1 false
filter String A filter clause used for refining search results 0...n N.A.

/people/{id}

Returns the agent associated with the given identifier.

/people/{id}/opuses

Returns the opuses of the person associated with the given identifier.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.
role String The relator code used for refining the type of contribution 0...1 aut

/people/{id}/occupations

Returns the occupations of the person associated with the given identifier.

/people/{id}/occupations/{occupationId}

Returns the occupation (related with a specific person) associated with the given identifier.

Examples

Meeting

Gathering of individuals or representatives of various bodies for the purpose of discussing and/or acting on topics of common interest. It is a concrete subclass of Agent and provides a set of attributes, both datatype and object property which interconnect the entity to opuses and other bibliographic entities in the Share-VDE domain model.

/meetings

Fulltext or Typeahead search across Share-VDE meetings.

Request Parameters
Name Type Description Cardinality Default Value
q String A meeting query expressed in SVDEQL or TermsQL (terms) 1 N.A.
mode Enum One among fts (fulltext search) and typeahead 0...1 fts
sort String A valid sort clause (fts mode only) 0...1 N.A.
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
fuzzy Boolean Enables / disables the fuzzy logic (typeahead mode only) 0...1 true
edits Integer Max edit distance in fuzzy logic. Can be 1 or 2 (typeahead mode only) 0...1 1
partialMatch Boolean Forces a partial match search (simple search only) 0...1 false
filter String A filter clause used for refining search results 0...n N.A.

/meetings/{id}

Returns the meeting associated with the given identifier.

/meetings/{id}/opuses

Returns the opuses of the meeting associated with the given identifier.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.
role String The relator code used for refining the type of contribution 0...1 aut

Examples

Organization

A corporation or group of persons and/or organisations that acts, or may act, as a unit. It is a concrete subclass of Agent and provides a set of attributes, both datatype and object property which interconnect the entity to opuses and other bibliographic entities in the Share-VDE domain model.

/organizations

Fulltext or Typeahead search across Share-VDE organisations.

Request Parameters
Name Type Description Cardinality Default Value
q String An organisation query expressed in SVDEQL or TermsQL (terms) 1 N.A.
mode Enum One among fts (fulltext search) and typeahead 0...1 fts
sort String A valid sort clause (fts mode only) 0...1 N.A.
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
fuzzy Boolean Enables / disables the fuzzy logic (typeahead mode only) 0...1 true
edits Integer Max edit distance in fuzzy logic. Can be 1 or 2 (typeahead mode only) 0...1 1
partialMatch Boolean Forces a partial match search (simple search only) 0...1 false
filter String A filter clause used for refining search results 0...n N.A.

/organizations/{id}

Returns the organisation associated with the given identifier.

/organizations/{id}/opuses

Returns the opuses of the organisation associated with the given identifier.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.
role String The relator code used for refining the type of contribution 0...1 aut

Examples

Family

Two or more persons related by birth, marriage, adoption, civil union, or similar legal status, or who otherwise present themselves as a family. It is a concrete subclass of Agent and provides a set of attributes, both datatype and object property which interconnect the entity to opuses and other bibliographic entities in the Share-VDE domain model.

/families

Fulltext or Typeahead search across Share-VDE families.

Request Parameters
Name Type Description Cardinality Default Value
q String A family query expressed in SVDEQL or TermsQL (terms) 1 N.A.
mode Enum One among fts (fulltext search) and typeahead 0...1 fts
sort String A valid sort clause (fts mode only) 0...1 N.A.
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
fuzzy Boolean Enables / disables the fuzzy logic (typeahead mode only) 0...1 true
edits Integer Max edit distance in fuzzy logic. Can be 1 or 2 (typeahead mode only) 0...1 1
partialMatch Boolean Forces a partial match search (simple search only) 0...1 false
filter String A filter clause used for refining search results 0...n N.A.

/families/{id}

Returns the family associated with the given identifier.

/families/{id}/opuses

Returns the opuses of the family associated with the given identifier.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.
role String The relator code used for refining the type of contribution 0...1 aut

Examples

Opus

The highest level of abstraction, a Work, in the BIBFRAME context, reflects the conceptual essence of the cataloged resource: authors, languages, and what it is about[2].

/opuses

Fulltext search across Share-VDE opuses.

Request Parameters
Name Type Description Cardinality Default Value
q String An opus query expressed in SVDEQL 1 N.A.
sort String A valid sort clause (fts mode only) 0...1 N.A.
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
partialMatch Boolean Forces a partial match search (simple search only) 0...1 false
filter String A filter clause used for refining search results 0...n N.A.

/opuses/{id}

Returns the opus associated with the given identifier.

/opuses/{id}/contributors

Returns the contributors of a given opus.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.
role String The relator code used for refining the type of contribution 0...1 aut

/opuses/{id}/contributors/{contributorId}

Returns the contributor of a given opus.

/opuses/{id}/publications

Returns the publications of a given opus.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.

/opuses/{id}/publications/{publicationId}

Returns a specific publication of a given opus.

/opuses/{id}/works

Returns the works of a given opus.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.

/opuses/{id}/works/{workId}

Returns a specific work of a given opus.

/opuses/{id}/works/{workId}/instances

Returns the instances of a work of a given opus.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.

/opuses/{id}/works/{workId}/instances/{instanceId}

Returns a specific work of a given opus.

/opuses/{id}/works/{workId}/instances/{instanceId}/items

Returns the items of an instance of a work of a given opus.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.

/opuses/{id}/works/{workId}/instances/{instanceId}/items/{itemId}

Returns a specific item.

Examples

Note that since the exact type of the agent cannot be known in advance, the request makes use of the ...on <type> construct.

Work

An intermediate level of abstraction which reflects an expression of a given Opus.

/works/{id}

Returns the work associated with the given identifier.

/works/{id}/contributors

Returns the contributors of a given work.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.
role String The relator code used for refining the type of contribution 0...1 aut

/works/{id}/contributors/{contributorId}

Returns the contributor of a given work.

/works/{workId}/instances

Returns the instances of a work.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.

/works/{workId}/instances/{instanceId}

Returns a specific work.

/works/{workId}/instances/{instanceId}/items

Returns the items of an instance of a work.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.

/works/{workId}/instance/{instanceId}/items/{itemId}

Returns a specific item.

Examples

Note that since the exact type of the agent cannot be known in advance, the request makes use of the ...on <type> construct.

Instance

A Work may have one or more individual, material embodiments, for example, a particular published form. These are Instances of the Work. An Instance reflects information such as its publisher, place and date of publication, and format[2].

/instance/{instanceId}

Returns a specific instance. The Instance entity provides a connection to the bibliographic records that contributed to its definition. Specifically, when at least one of those connections is available, the instance resource representation will contain an additional set of links under the "opac" category. Each link provides the URL and the owning provenance (code). Here's an example: 

{
  "preferredHeading": "Lewis Carroll's Alice's adventures in Wonderland",
  ...
  "_links": {
    "self": {
      "href": "https://svde.org/instances/I0001"
    },
    "opac": [
        {
            "type": "STANFORD"
            "href": "https://searchworks.stanford.edu/view/9386906"
        }, 
        ... (other opacs)
    },
    "format": {
      "href": "https://svde.org/formats/nc"
    },
    "publicationPlace": {
      "href": "https://svde.org/places/4930956"
    },
    "items": {
      "href": "https://svde.org/instances/I0001/items"
    }
  }
}

/instances/{instanceId}/items

Returns the items of an instance.

Request Parameters
Name Type Description Cardinality Default Value
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
sort String A valid sort clause (fts mode only) 0...1 N.A.
filter String A filter clause used for refining search results 0...n N.A.

/instances/{instanceId}/items/{itemId}

Returns a specific item.

Examples

Note that since the exact type of the agent cannot be known in advance, the request makes use of the ...on <type> construct.

Item

An item is an actual copy (physical or electronic) of an Instance. It reflects information such as its location (physical or virtual), shelf mark, and barcode[2].

/items/{itemId}

Returns a specific item.

Examples

Publication

A publication is a logical entity which wraps together an instance (including the items) plus the parent Work. Being the instance the central entity, its local identifier is used also for denoting the corresponding publication identity (and URI)

The representation is therefore very simple as it consists of the following: 

{
  "_links": {
    "self": {
      "href": "https://share.vde.org/publications/I0003"
    },
    "instance": {
      "href": "https://share.vde.org/instances/I0003"
    },
    "work": {
      "href": "https://share.vde.org/works/401-2"
    }
  }
}

/publications

Fulltext search across Share-VDE publications.

Request Parameters
Name Type Description Cardinality Default Value
q String A publication query expressed in SVDEQL 1 N.A.
sort String A valid sort clause (fts mode only) 0...1 N.A.
offset Integer A positive integer indicating the start offset of results (fts mode only) 0...1 0
rows Integer A positive integer indicating the returned page size (fts mode only) 0...1 10
filter String A filter clause used for refining search results 0...n N.A.

/publications/{id}

Returns the publication associated with the given identifier.

Controlled Vocabulary Entities

Other than the entities described above, referred as "core entities", the Share-VDE domain model includes some other entities that are gathered from external sources, assigned a Share-VDE URI and linked to core entities.


IMPORTANT: at time of writing the controlled vocabulary entities do not provide any content negotiation capability. That means the available endpoints always returns JSON according to HATEOAS specs.


"format" typeahead search results: 

  "_embedded": {
    "otherLanguages": [
      {
        "language": "fra",
        "preferredHeading": "<b>Bo</b>bine de bande informatique",
        "uri": "https://svde.org/formats/ch"
      },
      {
        "language": "ita",
        "preferredHeading": "<b>Bo</b>bina di nastro per computer",
        "uri": "https://svde.org/formats/ch"
      },
      ...

A single format 

{
  "preferredHeading": "Computer tape reel",
  "comingFromSolr": true,
  "_links": {
    "self": [
      {
        "href": "http://id.loc.gov/vocabulary/carriers/ch",
        "type": "other"
      },
      {
        "href": "http://sit2-base-svde.atcult.it/formats/ch"
      }
    ]
  }
}

The list includes:

  • Format
  • Role
  • Language
  • Agent Type
  • Genre
  • Occupation
  • Availability
  • Form
  • Place
  • OpusType
  • PublicationType

Each entity of this type provide two endpoints: a collection, which provides in turn typeahead search capabilities, and a single resource endpoint.

/{resourceType}

Typeahead search across Share-VDE controlled vocabulary entity.Note that the URI uses the plural form (e.g. /languages, /occupations, /forms)

Request Parameters
Name Type Description Cardinality Default Value
q String A typeahead query expressed in TermsQL (terms) 1 N.A.
fuzzy Boolean Enables / disables the fuzzy logic (typeahead mode only) 0...1 true
edits Integer Max edit distance in fuzzy logic. Can be 1 or 2 (typeahead mode only) 0...1 1

/resourceType/{id}

Returns the controlled vocabulary entity associated with the given identifier. Note that the URI uses the plural form (e.g. /languages, /occupations, /forms)

---------------

  1. Jump up↑ https://en.wikipedia.org/wiki/Representational_state_transfer
  2. ↑ Jump up to:2.0 2.1 2.2 https://www.loc.gov/bibframe/docs/bibframe2-model.html
Retrieved from "https://wiki.share-vde.org/w/index.php?title=ShareDoc:Search_API&oldid=3221"