Vocabularies

Vocabularies

Used for accessing vocabulary records. Currently the following vocabularies are supported:

• Languages (ISO 639-3 language codes)
• Licenses (SPDX licenses)
• Resource types (custom)

Search vocabularies

GET /api/vocabularies/{type}

Parameters

Name	Type	Location	Description
type	string	path	Vocabulary (one of languages, licenses or resourcetypes)
q	string	query	Search query used to filter results based on ElasticSearch's query string syntax.
suggest	string	query	One or more words used to suggest records as the user types (i.e. auto-complete).
tags	string	query	Filter results to the tag
sort	string	query	Sort search results. Unless overridden by a specific vocabulary, the built-in options are "bestmatch", "title", "newest", "oldest" (default: "bestmatch" or "title").
size	integer	query	Specify number of items in the results page (default: 10).
page	integer	query	Specify the page of results.
accept	string	header	- application/json (default) - application/vnd.inveniordm.v1+json

Specifically for the application/vnd.inveniordm.v1+json format:

Name	Type	Location	Description
ln	string	query	Locale used to localize the title and description (e.g. en or en_US)
accept-language	string	header	Locale used to localize the title and description (e.g. en or en_US)

The API uses a locale matching algorithm, that will do its best effort to translate the vocabulary record's title and description.

The sort options available vary depending on the vocabulary being searched. These cannot presently be configured via config variables but are set in the service configuration for each vocabulary service. The default sort options are used where a vocabulary service has not defined its own.

Request

GET /api/vocabularies/{type} HTTP/1.1

Response

For all vocabularies:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "hits": {...},
  "links": {...},
  "sortBy": ...,
}

Each hit looks like a vocabulary record below.

Get a vocabulary record

GET /api/vocabularies/{type}/{id}

Parameters

Name	Type	Location	Description
type	string	path	Vocabulary (one of languages, licenses or resourcetypes)
id	string	path	Identifier of the record, e.g. eng for type languages
accept	string	header	- application/json (default) - application/vnd.inveniordm.v1+json

Specifically for the application/vnd.inveniordm.v1+json format:

Name	Type	Location	Description
ln	string	query	Locale used to localize the title and description (e.g. en or en_US)
accept-language	string	header	Locale used to localize the title and description (e.g. en or en_US)

The API uses a locale matching algorithm, that will do it's best effort to translate the vocabulary record's title and description.

Request

GET /api/vocabularies/{type}/{id} HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

{

  "id": "{id}",
  "type": "{type}",
  "created": "2020-11-26T19:20:39",
  "updated": "2020-11-26T19:20:39",
  "revision_id": 1,
  "title": {
    "en": "..."
  },
  "description": {
    "en": "..."
  },
  "icon": "...",
  "props": { ... },
  "tags": [...],
  "links": { ... }
}

Specific vocabularies

Some vocabularies have their own endpoints because their size and structure is different from the vocabularies above. We refer to these vocabularies as "specific vocabularies".

Their search and get endpoints have the following shape:

Search

GET /api/{type}

Get

GET /api/{type}/{id}

Their Parameters are the same. Their responses are similar but have fields dependent on the specific vocabulary.

Supported types so far are: affiliations, names, funders, awards, and subjects.