This page provides a high-level introduction to the Vocabulary Registry API. The first main section outlines guiding principles; the second main section gives examples of how those guiding principles are worked out in practice.

Principles of the API

This section lays out the guiding principles of the API and its implementation. More precise details are given further down this page in the section The details.

Built with HTTPS

The Registry API is web-based; its methods are accessed exclusively using HTTPS.

The SSL certificates for vocabs.ardc.edu.au and demo.vocabs.ardc.edu.au are issued by Let's Encrypt. This means that your client must be able to accept Let's Encrypt certificates. In general, this should not be a problem, but if you are using a very old platform, you may experience a problem related to the root certificate. Please check the Let's Encrypt Certificate Compatibility page for more details. As noted at the DST Root CA X3 Expiration Notice page, if you use OpenSSL, you must use version 1.1.0 or later.

CORS-enabled

The OPTION HTTP method is supported, and all the necessary CORS headers are provided, so you can access the API from JavaScript in your browser. 

Built with OpenAPI (a.k.a. Swagger)

The Registry API has been constructed from the bottom up using version 2 of the OpenAPI specification and toolset, also known as Swagger. In practice, this means:

Built with XML Schema (but we also speak JSON)

The Registry API methods consume and produce structured data. The structures used by the API methods are described using XML Schema. In practice, this means:

The technology that provides marshalling and unmarshalling of data accepts both XML and JSON formats. That means:

If you are accessing the API using the Swagger UI system, or more directly using a tool such as Postman, you will be able to work with your choice of XML or JSON.

If you are using an API client library that has been generated from the OpenAPI description, you usually don't have to worry about the serialisation format – the client library takes care of that for you. For example, if you use a client library generated in Java, the generated code includes model classes that represent vocabulary metadata, and the client library does the work of marshalling and unmarshalling of instances of those classes for transport to/from the API.

Built with authentication and authorisation

Some API methods are public, meaning that they can always be invoked by anyone, without the need to provide authentication, or otherwise to "log in". In general, methods that perform queries are public.

Access to some API methods requires authentication. In general, these are methods that perform modifications (creation/update/deletion) of Registry data.

In addition, some API methods apply additional authorisation checks based on the organisations to which the API user belongs.

Inspired by REST principles

It is not a design goal of the API to make it conform precisely to the REST principles. (Conformity to those principles turns out to be very complex, so we prefer not to claim it.) However, there are some "REST-like" characteristics of the API methods. In particular, the Registry has a notion of "resource", and:

The details

OpenAPI

These pages provide background information about OpenAPI v2:

The Registry API description is available in OpenAPI v2 format here: https://vocabs.ardc.edu.au/registry/swagger.json. (For the demo environment, the URL is https://demo.vocabs.ardc.edu.au/registry/swagger.json.)

Research Vocabularies Australia hosts a customised instance of Swagger UI, linked directly to the Registry API: http://vocabs.ardc.edu.au/registry/swagger-ui/. (For the demo environment, the URL is http://demo.vocabs.ardc.edu.au/registry/swagger-ui/.)

XML Schema

See Vocabulary Registry data for links to the XML Schema files.

Authentication

As noted above, public methods of the API do not require authentication. If you only need to use the API's public methods, you may skip this section.

Portal users log in using the Portal's "My Vocabs Login" function. This creates an authentication token which is then used as an "API key" to authenticate to the Registry API. The use of this mechanism for systems other than the Portal is not currently supported, and so will not be discussed further here.

At present, the publicly-supported means of authentication to the Registry is by providing the username and password of an ARDC "built-in user" through the HTTP "Basic" authentication scheme, i.e., using the "Authorization" HTTP header. (See, e.g., https://en.wikipedia.org/wiki/Basic_access_authentication for more information about the "Basic" authentication scheme.)

Such "built-in users" are managed in the ARDC roles database. If you would like to use the authenticated methods of the API directly yourself, you will need to acquire a "built-in user" account from ARDC, and then provide its username and password using the "Basic" authentication scheme. To apply for an account, please contact services@ardc.edu.au.

If you use Swagger UI, you authenticate by clicking one of the buttons that says "Authorize" or that contains a padlock icon, then entering the username and password into the "Basic authorization" section and clicking the "Authorize" button.

If you use Postman or a similar REST API client, use that tool's normal means of specifying the username and password for "Basic" authentication.

If you are using an API client library, it will have its own means of specifying the username and password; you won't need to construct the "Authorization" HTTP header yourself.

Example: Java API client library, using Basic authentication

if you are using the generated Java API client library, you can do something like this:

ApiClient defaultClient = Configuration.getDefaultApiClient();

defaultClient.setUsername("myusername");
defaultClient.setPassword("mypassword");
 
ResourcesApi apiInstance = new ResourcesApi();
// And now invoke the methods of apiInstance.

Miscellaneous notes