NVA search api

README for the search api in NVA. The API was created to allow third parties to make queries to our search engine backed by Amazon OpenSearch.

Every endpoint documented here is implemented with the same philosophy and technology. We exposes part of the indexed documents as search keys.

Search Keys

Key names are case-insensitive and can be in camelCase or SNAKE_CASE. Each search key allow searching a field or sometimes fields for content, and most keys comes in three variants. Every search key applied are joined with AND between them, making the query more restricted for each key added to the search.

• keyName
  • Usually a keyword search, see Parameter README for details.
  • Supports search for several keywords, separated by comma.
    • Depending on underlying structure require, either ALL or ONE OR MORE to hit, see Parameter README for details.
• keyName + not
  • Should always return the inverse selection of just KeyName
• keyName + should
  • Usually a text search, see Parameter README for details.
  • Supports search for several text phrases, separated by comma.
    • Usually ONE OR MORE to hit, see Parameter README for details.

QueryKind

• number
  • Integer
• date
  • DateTimeFormat -> yyyy | yyyy-MM-dd | yyyy-MM-ddTHH:mm:ssZ | yyyy-MM-ddTHH:mm:ss.SSSZ
• keyword
  • Only hit on complete field
• fuzzy_keyword
  • will hit on partial field, boost hits on complete field
• text
  • hits on any partial match in field(s), boosts on exact match and phrases
• free_text
  • Search through whole document
• custom
  • some keys have more complex search algorithms

Free text search

We support free text search through all parts of our indexed documents. As with all other search keys, we support searching for several phrases, comma separated. All phrases have to match. It is possible to specify which fields to search through, but its use is limited and not recommended to use.

key_name	keyName	queryKind	scope
search_all	searchAll	text with ranking	all_items across document
query	query	text with ranking	all_items across document
fields	fields	list of search keys	user, tags, title
nodes_searched	nodesSearched	list of search keys	user, tags, title
nodes_included	nodesIncluded	list of node names to include	publisher.id, id, topLevelOrganizations
nodes_excluded	nodesExcluded	list of node names to exclude	publisher.id, id, topLevelOrganizations

Pagination, aggregation & sorting

Every endpoint have the same syntax and functionality in regard to sorting, paging & aggregation. Each endpoint have their own list of valid sortKeys, see README for each endpoint for details.

key_name	keyName	queryKind	example
aggregation	aggregation	Enum	all, none
page	page	number	0 to 10000/size
from	from	number	0 to 10000-size
size	size	number	0 to 1000
sort	sort	Enum(:order)	key1, key1:asc, key1:desc, key1:asc,key2:desc
sort_order	sortOrder	Enum	asc, desc
search_after	searchAfter	sortindex	supplied by api

Valid sort query parameters

The reason we support that many different sort formatting, is due to legacy systems we need to support.

orderBy=created_date&order=desc

order_by=createdDate&order=desc

sort=created_date&sortOrder=desc

sort=createdDate:desc

sort=created_date desc                      //use '+' or URL-encode

sort=createdDate                            //default sort order : desc

orderBy=created_date:asc,modifiedDate:desc

orderBy=createdDate:asc,modified_date:desc

sort=created_date,modifiedDate              //default sort order : desc

sort=createdDate:asc,modifiedDate:desc

sort=created_date&sortOrder=asc&sort=modifiedDate&order=desc

sort=createdDate&sortOrder=asc&orderBy=modifiedDate

sort=created_date&sortOrder=asc&orderBy=modifiedDate:desc

sort=createdDate asc&sort=modifiedDate desc    //use '+' or URL-encode

Aggregations have the following JSON format

"id" is the current query with the selected aggregation/filter added to it, useful for drill-downs into sub-selections of the resource.

If you want to filter on an aggregation without the current filter included, you can construct a search key by using the aggregation name + key value . (i.e. type=RequestType)

{
  "type": {
    "id": "https://unset/resource/search?type=RequestType&aggregation=all&size=10&from=0",
    "key": "RequestType",
    "count": 1,
    "labels": {
      "nb": "Første type",
      "en": "First kind"
    }
  }
}

EndPoints

/Resource

Valid search parameters /search/resources?parameters=...

GET /search/resources HTTP/1.1
Host: api.test.nva.aws.unit.no
Accept: application/json

GET /search/resources HTTP/1.1
Host: api.test.nva.aws.unit.no
Accept: application/csv

/Resource (logged in user)

Valid search parameters /search/customer/resources?parameters=...

GET /search/customer/resources HTTP/1.1
Host: api.test.nva.aws.unit.no
Accept: application/json

JSON from Response endpoints

{
  "id": "https://api.dev.nva.aws.unit.no/search/resources",
  "totalHits": 120387,
  "hits": [],
  "nextResults": "https://api.dev.nva.aws.unit.no/search/resources?aggregation=all&size=10&from=20",
  "previousResults": "https://api.dev.nva.aws.unit.no/search/resources?aggregation=all&size=10&from=0",
  "aggregations": {
    "type": [],
    "license": [],
    "contributor": [],
    "journal": [],
    "series": [],
    "contextType": [],
    "course": [],
    "publisher": [],
    "files": [],
    "fundingSource": [],
    "scientificIndex": [],
    "status": [],
    "topLevelOrganization": []
  },
  "@context": "https://bibsysdev.github.io/src/search/paginated-search-result.json"
}

/Ticket

Valid search parameters /search/customer/tickets?parameters=...

GET /search/customer/tickets HTTP/1.1
Host: api.test.nva.aws.unit.no
Accept: application/json

JSON from ticket endpoint

{
  "id": "https://api.dev.nva.aws.unit.no/search/customer/tickets",
  "totalHits": 120387,
  "hits": [],
  "nextResults": "https://api.dev.nva.aws.unit.no/search/customer/tickets?aggregation=all&size=10&from=20",
  "previousResults": "https://api.dev.nva.aws.unit.no/search/customer/tickets?aggregation=all&size=10&from=0",
  "aggregations": {
    "type": [],
    "notifications": [],
    "status": [],
    "byUserPending": []
  },
  "@context": "https://bibsysdev.github.io/src/search/paginated-search-result.json"
}

/Import-candidate

Valid search parameters /search/import-candidates2?parameters=...

GET /search/import-candidates2 HTTP/1.1
Host: api.test.nva.aws.unit.no
Accept: application/json

JSON from import-candidate endpoint

{
  "id": "https://api.dev.nva.aws.unit.no/search/importcandidates2",
  "totalHits": 120387,
  "hits": [],
  "nextResults": "https://api.dev.nva.aws.unit.no/search/importcandidates2?aggregation=all&size=10&from=20",
  "previousResults": "https://api.dev.nva.aws.unit.no/search/importcandidates2?aggregation=all&size=10&from=0",
  "aggregations": {},
  "@context": "https://bibsysdev.github.io/src/search/paginated-search-result.json"
}

---

Useful links

• API documentation
  • NVA git README
  • NVA swagger (test)
  • NVA swagger (production)
  • READMES (Endpoint parameter documentation)
    • Resources
    • Tickets
    • Import-candidates
• API Endpoints
  • Test
    • https://api.test.nva.aws.unit.no/search/resources
    • https://api.test.nva.aws.unit.no/search/customer/resources
    • https://api.test.nva.aws.unit.no/search/customer/tickets
    • https://api.test.nva.aws.unit.no/search/import-candidates2
  • Production
    • https://api.nva.unit.no/search/resources
    • https://api.nva.unit.no/search/customer/resources
    • https://api.nva.unit.no/search/customer/tickets

---

Utility startpoints and flows