This is the application programming interface (API) to the digital library of the Asian Legacy Library (ALL).
\nThe digital library manages 4 different resources Works, Persons, Subjects, and Items. Here an Item refers to a digital asset such as a scan image group, an input text transliteration or a translation. The Item has metadata which will be found in its related Work, Person, and / or Subject record. More to follow...
\nHere is a link to the data model.
\nThe API follows the REST protocol. There is an input URL with parameters as specified below. The output of the API is JSON.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"10868360","collectionId":"d177cc8e-a0d6-452c-b1b2-abc1ad483854","publishedId":"TVeiCqJo","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"122f43","highlight":"bbcc00"},"publishDate":"2021-10-11T18:44:14.000Z"},"item":[{"name":"Get Resource","event":[{"listen":"test","script":{"id":"9efa40e7-7a93-4223-9526-cb37fbb34f8a","exec":[""],"type":"text/javascript"}}],"id":"7bf9d2b8-ad18-4e8a-a619-50e24124632a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"Accept","value":"application/json","description":"Default response is JSON
\n","type":"text"}],"url":"https://api.asianlegacylibrary.org/resources/:UID?include_data=false&include_citation=false&include_related=false","description":"The /resource/:UID endpoint returns a specified resource using the UID path parameter. The UID is the universal identifier of the digital asset.
< _Optional_ >
\nA boolean flag to include or exclude the text content of our digital assets such as input texts and translations. Defaults to false.
\nNote that the payload of metadata is small (kb), whereas the text field of a digital asset can be large (mb).
\nThe text data is returned in a field called bibframe:datasource, _source[all:items][bibframe:datasource]. This refers to the fact that it is the text data of the digital asset (called an item) related to the work.
< _Optional_ >
\nBoolean value to return a new object called citation with all fields required to build a proper citation for footnoting.
Currently only the fields are returned and not a formatted string specific to any citation standard. This will evolve to be more sophisticated in the future.
\n","type":"text/plain"},"key":"include_citation","value":"false"},{"description":{"content":"< _Optional_ >
\nBoolean value to return other works found in all:relatedworks
String value of the unique resource identifier.
\n","type":"text/plain"},"type":"any","value":"W.95015a","key":"UID"}]}},"response":[],"_postman_id":"7bf9d2b8-ad18-4e8a-a619-50e24124632a"},{"name":"Search for Resources","id":"51c73c81-c3db-4376-a84e-8d435c9a8342","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.asianlegacylibrary.org/resources?q=logic&filter=author:losang&search_fields=title,subject&highlights=false&page=1&page_size=20&include_aggs=source","description":"The /resources endpoint returns a listing of resources. The endpoint can be used to search by terms or phrases, and / or to filter the resources by categories.
The endpoint executes a search in the metadata and / or within the digital asset itself, as directed by the parameters.
\n","urlObject":{"path":["resources"],"host":["https://api.asianlegacylibrary.org"],"query":[{"description":{"content":"< _Optional_, though one of __class__ or __q__ must be provided >
\nIf the parameter is not provided then class must be provided and the response will include a listing of records of the specified class.
\nA search query, either a term or a phrase. See below and the examples for more complex boolean and proximity queries.
\nPROXIMITY \nthis near that ---------------------------
\nCurrently the proximity search can only be done in isolation, if you use it with booleans AND / OR / NOT you get some weird results, especially with the highlighting. Elasticsearch DSL seems to be constantly updating how proximity search is done so that maybe it'll fix this limitation...
\nThe general structure for the proximity call is: near(this:that)~lines away from each other. With the option to make the ordering specific to the order in which you write the terms/phrases.
The example near(bodhisattva:virtue)~1^ breaks down as follows => the term bodhisattva within 1 line of the term virtue (in that order). The ^ specifies ordering, omit it if order doesn't matter.
The default lines away from is 4, a line is approximated to have 120 characters. If you set the lines away from to be 0 then it will only match terms right next to each other. The maximum lines away from is 10.
\nAND \nthis and that, all of these terms ---------------------------
\nThe AND means the result must contain all the terms. To create an AND boolean query you simply give the API a comma separated list of terms. The list can be a single term or a phrase.
\nThe example vows of a bodhisattva, virtue breaks down as follows => the phrase vows of a bodhisattva and the term virtue must both exist in the document.
NOT\nnot this ---------------------------
\nThe NOT means the result must not contain the term or phrase. To use with a single term you can simple negate the term with a dash. Whereas if you want to negate a phrase you must surround the phrase in parentheses.
\nYou can use it like the AND boolean, in the sense that you can chain them together because multiple NOT's means not this AND not that
\nThe example great, -(vows of a bodhisattva), -virtue breaks down as follows => The term great must be there but not the phrase vows of a bodhisattva or the term virtue.
OR \nthis or that, any of these terms ---------------------------
\nThe OR means the result can contain any one of these terms, it is the most open ended.
\nYou can add an OR between groups of terms, which is where the idea of a block comes from, this block of terms OR this block of terms
\nIf it's more than a single term and there is a block of terms then it must be surrounded by parentheses.
\nThe example (great and morality) or vows breaks down as follows => The document must have either the terms great and morality OR just the term vows.
< _Optional_ >
\nFilter search by category. You can add multiple filters. You can also add multiple types within the same category with OR. For example, you can filter `assettype:(scans or translations).
\nThe keyword exists can be used to filter out results that do not have values for the category.
You can also use the - dash to negate the filter, it then becomes a 'does not exist' or 'does not include' filter. For example, author:exists vs author:-exists or author:choney vs author:-choney. The structure of the filter is category:(-)term|exists
Available categories include:
\n< _Optional_ >
\nA comma separated list of fields to include in the search. Does nothing if q parameter is not provided. Defaults to all fields.
\nPossible values in bold below:
\n<_Optional_>\nReturn HTML formatted results with <em> tags surrounding found terms in text.\nDefaults to false
Returns a new object outside of the _source object, called highlight. Specifically, to be used by front end display.
Page offset, each page returns $page_size results, defaults to 1
Number of results to return per page, defaults to 10
< _Optional_ >
\nA comma separated list of aggregations for the returned search results. Provides an overview of all results returned under a new object called aggregations.
For instance, you can request source aggregations with your results, and this will return the total number of current results from each of our source libraries.
\nSince the search results returned to the client are paginated it is quite possible that the client will not have a complete dataset from which to run it's own summarization.
\nMISSING VALUES: If there is no associated category for a record then it is considered missing as opposed to N/A or null. A separate object is passed back named _'{category}missingvalues' with the number of returned documents without that category specification.
\nCurrently it is possible to get aggregations for:
\nThe /resources/summarize endpoint returns three objects:
The metadata field on which to aggregate and summarize.
\nCurrently it is possible to get aggregations for:
\nThe maximum number of returned results per page.
\n","type":"text/plain"},"key":"page_size","value":"50"},{"description":{"content":"When sorting summaries you can sort by either the aggregation key which is the category term itself or by 'doc_count' which is the number of documents categorized by that term.
\nYou can specify the direction of the sort as well with the standard asc and desc flags. Default is asc.
\nSeparate the sort type and sort direction by :, so that the call looks something like count:desc or key:asc, etc.
Return the ACIP subject tree in either Tibetan or English. To specify language use the language parameter with ISO language codes, bo for Tibetan and en for English.
\nThe returned numbers with each branch/leaf are the current number of docs in the library under that subject.
\nTo reconstruct the subject path, join each leaf together with '/'
\n","urlObject":{"path":["resources","subjecttree"],"host":["https://api.asianlegacylibrary.org"],"query":[{"description":{"content":"< _Optional_ >
\nDefault language is bo (ISO 639-1 Code for Standard Tibetan)
\nbo: returns Tibetan subject tree in ACIP transliteration (Roman characters).
\nen: returns English subject tree.\n
\n","type":"text/plain"},"key":"language","value":"bo"}],"variable":[]}},"response":[],"_postman_id":"0c146aa1-7db8-4707-83a1-c67253fd1a23"},{"name":"Download Resource","id":"e25429f1-cb06-4f7d-a18a-ebcb5576ded1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.asianlegacylibrary.org/resources/download/:UID?format=txt&force_download=false","description":"Downloads resource data.
\nReturns either HTML with download links, or if the 'force_download' parameter is set to true then it will return the data itself.
\nThere are currently two formats available, JSON and txt. The txt option is only available on the input texts and translations asset type resources that contain text data.
\n","urlObject":{"path":["resources","download",":UID"],"host":["https://api.asianlegacylibrary.org"],"query":[{"description":{"content":"< _Optional_ >
\nThe requested format of data.
\nNote that format is required if 'force_download' is set to true.
\njson: All resources can return JSON, which will be their associated metadata.
\ntxt: Works that have an associated digital asset type of either input texts or translations will have associated text, but only if the digital rights is in the public domain will there be an option to download the text itself in txt format.
\n< _Optional_ >
\nDefaults to false
\nIf set to true then the requested format is automatically downloaded, if it exists.
\nWhen false HTML is returned with links to available downloads.
\n","type":"text/plain"},"key":"force_download","value":"false"}],"variable":[{"description":{"content":"< _Required_ >
\nThe resource UID.
\n","type":"text/plain"},"type":"any","value":"W.95019a","key":"UID"}]}},"response":[],"_postman_id":"e25429f1-cb06-4f7d-a18a-ebcb5576ded1"},{"name":"Search Resource","id":"5fad1d39-fbfc-4f87-bef8-2e38d49bc34a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api.asianlegacylibrary.org/resources/:UID/search?q=logic&search_fields=title,subject","description":"Search a resource for terms and phrases and return the resource with the search matches enclosed in the HTML tags <em> for highlighting.
See Search for Resources endpoint for lengthy description for q parameter.
See Search for Resources endpoint for description for search_fields parameter.
Resource Work UID
\n","type":"text/plain"},"type":"any","value":"W.667819a","key":"UID"}]}},"response":[],"_postman_id":"5fad1d39-fbfc-4f87-bef8-2e38d49bc34a"}],"event":[{"listen":"prerequest","script":{"id":"482f42da-0ee6-4f75-8eca-6e4b78d05223","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"0399607f-4321-489c-8663-e7e715af0da7","type":"text/javascript","exec":[""]}}],"variable":[{"key":"dev_url","value":"http://localhost:5000"},{"key":"api_url","value":"https://api.asianlegacylibrary.org"},{"key":"uid","value":"W.95015a"},{"key":"class","value":"works"},{"key":"search_fields","value":"title,subject"},{"key":"query","value":"logic"},{"key":"include_data","value":"false"},{"key":"summary_field","value":"source"},{"key":"summary_sort","value":"key:asc"},{"key":"include_aggs","value":"source"}]}