Vocabulary Registry API methods

This page contains notes on some of the supported Registry API methods. The focus is on those methods that will be needed as part of the most common workflows.

Before working with any of the Registry API methods, you will need to be familiar with the principles that apply to data sent between the Registry and its clients. These principles are explained at the page  Vocabulary Registry data.

You can get a certain amount of documentation about a particular method's request parameters and results via the Swagger UI view, and you will also get some documentation by generating an API client library using the swagger-codegen tools. See  Accessing the Vocabulary Registry API for details.

About these method specifications

Each method described below contains an information box as follows. Note: each information box contains only those items that are relevant to the method.

• Method name: this is the name of the method as defined in the Registry API implementation. If you generate an API client library using the Swagger codegen tools, it is likely that these are the names of the methods you will find in the generated library.

• Path: this is the URL path component for the method. If you are invoking the method using a REST tool, append the given path to https://vocabs.ardc.edu.au/registry to get the full URL of the method.

  • The Path may contain one or more variable path components; these are specified in braces. For example, /api/resource/relatedEntities/{relatedEntityId} means that the path is /api/resource/relatedEntities/ followed by a value for relatedEntityId. In this case, given underneath the path is the information "relatedEntityId: Integer", which means that the value provided for relatedEntityId must be an integer value.

• HTTP method: either GET, POST, PUT, or DELETE. If you are invoking the method using a REST tool or a command-line tool (e.g., curl or wget), you must take care to use the particular HTTP method specified.

• Query parameters: "None", if none are accepted. Otherwise, there will be one line for each query parameter, indicating whether or not the parameter is required or optional, the name of the parameter, its type, and, if optional, its default value. (If the parameter is optional, and a default value is not indicated, the difference in behaviour between specifying or not specifying the parameter will be explained.) Examples:

  • optional: relatedEntityType: one of party, service, vocabulary

    • The parameter "relatedEntityType" is optional; if specified, its value must be one of the three values listed.

  • includeAccessPoints: Boolean := false

    • The parameter "includeAccessPoints" is optional; if specified, its value must be a Boolean value (i.e., either true or false); if not specified, its value defaults to false.

  • required: input: String

    • The parameter "input" is required, and its value is a String.

• Request body type: If the HTTP method is POST or PUT, and the method requires a request body, this entry gives an indication of the type of data that must be provided in the body. (This may also determine the value to be provided in the Content-Type request header.)

• Form data: If the HTTP method is POST or PUT, the method may accept form data. If so, a line for each form data parameter will be included in the information box, indicating if the parameter is required or optional, the parameter's name, and the type of the form data.

• Authentication required?: Either "No", for most query methods, or "Yes", for methods that perform create/update/delete actions.

• Authorization: if authentication is required, there may be additional authorization requirements that are checked. For example, an API user can only create new registry entities that specify an owner that is one of the user's organisational roles, or update or delete registry entities that are owned by the user.

• Validation mode: this method has incoming metadata describing one or more related model entities. Validation will be applied to that metadata according to the rules specified at Validation of Registry model entity data, using this validation mode.

• Response type: An indication of the type of data contained in the response body, when the method returns successfully. Some common response types (e.g., Result) are explained at the page  Vocabulary Registry data. Some methods provide a response only using an HTTP status code, without a body; for these methods, the response type is "None".

Service methods

search

The search method is the main discovery interface to the Registry. It is used to implement the "Vocabularies" tab of the Portal's search results page.

The method is a light-weight facade over the underlying search index, which is implemented using Apache Solr.

For this reason, unlike most API methods, the search method only consumes JSON, and only produces JSON. Indeed, the method's responses are exactly what has come back from Solr. (See the Solr documentation page JSON Response Writer for more information.)

The search query is provided as the parameter filtersJson, encoded as HTTP form data (Content-Type application/x-www-form-urlencoded). The format of the search query is a simple JSON object with strings as keys, and with values that are either strings (or arrays of strings), integers, or booleans. Supported keys are:

The two examples for access show how to specify one filter query term and multiple filter query terms, respectively. The same syntax is used for the other filter query types.

Filter query terms are conjoined

Filter query terms are added to the search query as a conjunction of disjunctions. That is, within any particular filter key (say, publisher), results are found which match any of the values specified for that key, and then the final search result contains only vocabularies whose metadata matches all filter query terms.

For example, the following query is a search for the keyword water, with the publisher Australian Bureau of Statistics, and with a subject that matches either Agriculture or Economics (or both); only the first 10 results will be returned.

{"q":"water","publisher":"Australian Bureau of Statistics",
 "subject_labels": ["Agriculture", "Economics"]}

searchResources

The searchResources method is the discovery interface to the resource data (SKOS concepts, concept schemes, and collections) of vocabularies stored in the Registry. It is used to implement the "Concepts, etc." tab of the Portal's search results page.

The method is a light-weight facade over the underlying resource search index, which is implemented using Apache Solr.

For this reason, unlike most API methods, the searchResources method only consumes JSON, and only produces JSON. Indeed, the method's responses are exactly what has come back from Solr. (See the Solr documentation page JSON Response Writer for more information.)

The search query is provided as the parameter filtersJson, encoded as HTTP form data (Content-Type application/x-www-form-urlencoded). The format of the search query is a simple JSON object with strings as keys, and with values that are either strings (or arrays of strings) or integers. Supported keys are:

The two examples for publisher show how to specify one filter query term and multiple filter query terms, respectively. The same syntax is used for the other filter query types.

Filter query terms are conjoined

Filter query terms are added to the search query as a conjunction of disjunctions. That is, within any particular filter key (say, publisher), results are found which match any of the values specified for that key, and then the final search result contains only vocabularies whose metadata matches all filter query terms.

For example, the following query is a search for the keyword water, with the publisher Australian Bureau of Statistics, and with a subject that matches either Agriculture or Economics (or both); only the first 10 results will be returned.

{"q":"water","publisher":"Australian Bureau of Statistics",
 "subject_labels": ["Agriculture", "Economics"]}

Languages in the index and in search results

Vocabulary content in RDF is indexed into a number of language-specific and language-independent fields. Search results contain a selection of these fields, based on the value provided for the language filter. For example, given the following vocabulary data in Turtle syntax:

my:c1 a skos:Concept;
  skos:prefLabel "No language prefLabel", "English prefLabel"@en, "Français prefLabel"@fr;
  skos:altLabel "No language altLabel", "English altLabel"@en, "Français altLabel"@fr .

the index will include the following fields and values for this concept:

skos_prefLabel: ["No language prefLabel"]
skos_prefLabel-en: ["English prefLabel"]
skos_prefLabel-fr: ["Français prefLabel"]
skos_prefLabel_all: ["No language prefLabel", "English prefLabel, "Français prefLabel"]
skos_altLabel: ["No language altLabel"]
skos_altLabel-en: ["English altLabel"]
skos_altLabel-fr: ["Français altLabel"]
skos_altLabel_all: ["No language altLabel", "English altLabel, "Français altLabel"]

The following table gives some examples showing how various settings of the language filter determine which of these fields will be included in search results.

getUserData

This method returns information about the user, including all the user's "organisational roles", i.e., the allowed values of vocabulary "owner" that the user may use when creating, editing, or deleting registry entities.

Resource methods

Resource methods are the API methods for creating, reading, updating, and deleting individual vocabularies and associated model entities.

Related Entities

Please refer to Vocabulary Registry model entities: Related Entity for important information about Related Entities. The most important thing to know is that there is a business rule that requires all vocabularies to be related to at least one Related Entity (of type party) as a publisher. This means that before vocabulary creation, you should already have a suitable Related Entity "ready to go", and you will need to know its resource ID for use in the Vocabulary metadata.

getRelatedEntities

This method allows you to fetch all Related Entities, optionally filtered by type. The results do not include the details of Related Entity Identifiers. (To see details of Related Entity Identifiers, you must use the getRelatedEntityById method.)

getRelatedEntityById

This method fetches one Related Entity, by its resource ID. The result includes details of all the Related Entity's Related Entity Identifiers.

createRelatedEntity

The metadata contained in the body of the request must not include any resource IDs.

The response for a successful creation is the Related Entity instance as persisted in the Registry. In particular, that means that the response contains a resource ID for the new Related Entity and one each for its Related Entity Identifiers.

updateRelatedEntity

This method supports updating the details of a Related Entity instance. The resource ID of the Related Entity must be specified both as a path parameter, and in the body of the request. The body must contain resource IDs for all existing Related Entity Identifiers that are to be preserved. That means that:

• if a Related Entity Identifier is to be preserved, include its resource ID and the content of the entity unchanged

• if a Related Entity Identifier is to be deleted, don't include it at all

• if a Related Entity Identifier is to be added, include its details, but don't include any resource ID

There is no concept of an "update" to a Related Entity Identifier. For example, if you are correcting an error, you specify the deletion of the existing Related Entity Identifier and the addition of the correct one.

deleteRelatedEntity

A Related Entity instance can be deleted (by its owner), as long as there are no current or draft Vocabulary instances that are related to it. In general, users are not obliged to delete unused Related Entity instances, but can choose to do so if they wish. Please note that there is currently no facility in the Portal to delete Related Entities; only this API method provides such functionality.

Uploads

createUpload

Use this method to upload a file containing vocabulary data to the Registry.

Note that the uploaded vocabulary data is then "owned" by the specified owner: whenever creating/updating a vocabulary, the authenticated user must "own" all of the uploads specified in the metadata.

The value of the "type" query parameter must be one of the values in the first column of the following table:

The filename provided in the filename parameter of the Content-Disposition of the request body must include a file extension that is consistent with the type parameter, as shown in the second column of the table. For example, if the value of the type parameter is TTL, the filename must end with ".ttl".

If the upload is successful, the upload ID of the upload is returned in two ways:

• The Location response header includes the upload ID encoded as the last part of a URL. Note that this URL is "theoretical" only: it does not resolve. (That is why, as noted at Vocabulary Registry model entities: Resources and their resource IDs, these upload IDs are not really resource IDs.)

• The upload ID is contained in the response body, in the integerValue of the Result element. This is probably the more convenient way to access the the upload ID.

It is very important that you take note of the upload ID returned by this method, as there is currently no other way of accessing it. (For example, there is not currently an API method to list all uploads.) It is this value that you provide as the value of the upload-id attribute of a file access point.

The filename provided in the request body is passed through a sanitization process (i.e., that replaces characters not allowed in filenames with underscores) and returned in the response body in the stringValue of the Result element.

Vocabularies

The search method is a flexible way to locate a particular vocabulary, if you don't already know its vocabulary Id. However, the most general way is to use the getVocabularies resource method to get a list of all vocabularies. Once you have the vocabulary Id, you can use the additional resource methods to get the detailed metadata of the vocabulary.

getVocabularies

This method returns a list of all publicly-visible vocabularies (i.e., with status either published or deprecated). Only the top-level metadata of each vocabulary is included; in particular, versions and access points are not included. However, related entity references and related vocabulary references are included, i.e. with resource IDs and relations, but with no further details.

getVocabularyById

This is a "workhorse" method to get the publicly-visible metadata about a vocabulary, its versions, and access points. By default, only the top-level metadata of the vocabulary is returned; lower-level metadata may be accessed by specifying flags as query parameters.

If the includeAccessPoints query parameter is specified as true, this implicitly forces the value of the includeVersions flag to be true.

Irrespective of the presence or absence, or the value of the includeRelatedEntitiesAndVocabularies query parameter, the response always includes the resource IDs and the relations of the vocabulary's related entities and related vocabularies. But if the includeRelatedEntitiesAndVocabularies query parameter is specified as true, the details of the metadata of related entities and related vocabularies are also included in the response.

This method does not require authentication, and is intended for use when displaying "public" metadata. Therefore, it can only be used to access a published or deprecated vocabulary instance; it can not be used to access a draft instance. Authenticated/authorized users can make use of the hasDraftVocabularyById and getVocabularyByIdEdit methods to determine if there is a draft instance and to gain access to its metadata.

If you are updating a vocabulary, do not use the response of this method as the basis of a request to updateVocabulary; use the response of the getVocabularyByIdEdit method instead.

getVocabularyByIdEdit

This method is provided to assist API users who are updating their own vocabularies. This is the method used by the Portal when a user clicks an "Edit" button on the "My Vocabs" Portal page. The method returns a response that includes exactly the metadata that describes the "status quo" of the vocabulary metadata, and which can then be used as the basis of the request body of the updateVocabulary method. Indeed, taking the response of this method and immediately sending it to updateVocabulary will make no changes to the vocabulary.

What does "status quo" mean in practice?

• If there is currently a draft instance of the vocabulary, it is this draft instance that is returned in the response.

  • If the vocabulary has both a draft and a published/deprecated instance, you can't use this method to access the published/deprecated instance. You can use getVocabularyById to access it, but note that the response format of getVocabularyById is not the same as this method.

• If there is not currently a draft instance of the vocabulary, but only a published/deprecated instance, it is this instance that is returned in the response.

Here are some additional hints for using this method:

• If you have a draft instance, but you wish to update content based on the published/deprecated version, you should first delete the draft instance (using the deleteVocabulary method with deleteDraft=true) then use this method to retrieve the published/deprecated instance.

• If you have an existing draft instance that you want to "publish", i.e., to make it the publicly-visible instance, use this method to retrieve the draft instance, set the status attribute of the response to published (or deprecated), and send the result to updateVocabulary. See the notes on the updateVocabulary method for more details about what happens when you change the value of the status attribute.

createVocabulary

Use this method to create a new vocabulary. The new vocabulary will exist with the status specified in the status attribute. That means, for example, if the status is specified as either published or deprecated, it will be immediately "visible", e.g., in Portal search results. If the status is specified as draft, it will not appear in the public part of the portal, but it will appear in the draft section of the owner's "My Vocabs" Portal page.

On success, there is a response header Location that contains the resource URL of the newly-created vocabulary; i.e. it ends with /api/resource/vocabularies/{vocabularyId}, where {vocabularyId} is the resource ID of the new vocabulary. The resource ID is also included in the response body as the value of the id attribute of the vocabulary.

updateVocabulary

Use this method to update a vocabulary's metadata.

Changes to Vocabulary Related Vocabulary references

It is strongly recommended that when updating a vocabulary, you first use the getVocabularyByIdEdit method to obtain the current state of the vocabulary, take the response and make whatever modifications you want, then provide that as the request body of the updateVocabulary method. This helps prevent making any additional unintended changes.

If your vocabulary's metadata includes Vocabulary Related Vocabulary instances – and especially if the related vocabularies are owned by a different owner – it's important that you use the getVocabularyByIdEdit method each time you make an update, rather than keeping the response from a previous update. This is because if a related vocabulary is deleted, references to it will also no longer appear in the response of getVocabularyByIdEdit. If you nevertheless include references to deleted vocabularies in your updateVocabulary request, they will be rejected by the validation process.

If the vocabulary already exists only in a publicly-visible form (i.e., with status either published or deprecated), you add a draft instance by setting the top-level status attribute to the value draft; the existing publicly-visible form will be unaffected.

If the vocabulary already contains a draft instance, and you set the top-level status attribute either to published or deprecated, the existing draft instance will be removed.

deleteVocabulary

Specify deleteCurrent=true to delete the "current" Vocabulary instance (i.e., which has status either published or deprecated); specify deleteDraft=true to delete the draft instance.

In general, if you specify the value true for one of the query parameters, it is an error if the corresponding instance does not exist (and therefore, there is nothing to delete). However, there is one exception to this rule: it is permitted to specify the value true for both query parameters, and it is not then an error if there is only one of the corresponding instances.

Utility methods

generateSlug

See the section "Slugs" of  Vocabulary Registry data for an explanation of slug values and how they are used in the Registry and in URLs of the Repository.

You may use this method to see what slug will be generated from any particular string. If you want a different slug from the one automatically generated from the vocabulary/version title, you can specify it when you create the vocabulary/version; this "overrides" the default title-based generation process.

To see if a particular string is valid as a slug, run it through this method. If the output is exactly the same as the input, the string is already a valid slug. And this is indeed how the Registry checks if a user-supplied slug is in the correct format.