The IGSN service has been designed and developed in a way that makes it extendable and reusable for uses beyond IGSN. Users of the API should take a few minutes to understand the service architecture, basic principals and data model, as it will come in handy when creating and managing IGSNs via the API.

System Architecture 

The ARDC IGSN service is comprised of 4 main components:


Requests

Pre-validation

All API requests that create or modify resources are pre-validated prior to being accepted by the Metadata Registry. The checks within the pre-validation process ensure that the user making the request is authorised to perform the action and that the request payload can be understood by the service. If any of these checks fail, the request will be rejected with an appropriate HTTP status code and message.

Example of response to invalid request

{
    "message": "Unable to determine content format or content not supported : The element type \"resourceTsditle\" must be terminated by the matching end-tag \"</resourceTsditle>\".",
    "timestamp": "2020-12-10T02:59:25.104+00:00",
    "status": 400,
    "error": "400 BAD_REQUEST",
    "path": "/api/services/igsn/bulk-mint"
}


Bulk Requests

Requests involving more than one resource (e.g. bulk mint), are added to a queue for processing. Upon acceptance of a bulk request, the service will queue the request and return a response containing links which allow you to monitor the progress of the request (refer to response example below). 

The '/api/resources/requests/{id}'  link provided in the response will allow you to monitor the overall status of the request as well as see a summary of the request actions.

The '/api/resources/requests/{id}/logs'  link provided in the response will allow you to view the request logs. The details of any errors that occur during processing will be output in the logs. 

Statuses returned for bulk requests:

Example of a bulk mint request response

{
    "id": "2ab7af89-c01c-417c-a782-e2f2a4dba996",
    "status": "QUEUED",
    "type": "igsn.bulk-mint",
    "createdBy": "b3cc6369-448a-4853-9b9f-2ab56f90a18d",
    "createdAt": "2020-12-10T09:09:30.806+00:00",
    "updatedAt": "2020-12-10T09:09:30.900+00:00",
    "message": "Bulk Mint Request is Queued",
    "summary": {},
    "_links": {
        "self": {
            "href": "https://test.identifiers.ardc.edu.au/igsn-registry/api/resources/requests/2ab7af89-c01c-417c-a782-e2f2a4dba996"
        }
        "logs": {
            "href": "https://test.identifiers.ardc.edu.au/igsn-registry/api/resources/requests/2ab7af89-c01c-417c-a782-e2f2a4dba996/logs"
        },
        "identifiers": {
            "href": "https://test.identifiers.ardc.edu.au/igsn-registry/api/resources/requests/2ab7af89-c01c-417c-a782-e2f2a4dba996/identifiers"
        },
        "records": {
            "href": "https://test.identifiers.ardc.edu.au/igsn-registry/api/resources/requests/2ab7af89-c01c-417c-a782-e2f2a4dba996/records"
        }
    }
}


Single Requests 

Requests involving single resources (e.g mint and update) are processed more or less synchronously. The only caveat being that any interactions with IGSN MDS are processed as independent background tasks. The service has been designed on the premise that once your single IGSN request has passed validation and the records created or updated in the Metadata Registry, then the minting or updates at MDS are guaranteed to be performed. The background processing of MDS transactions optimises the request process by removing the need to wait for the interaction with MDS to be completed before responding to a clients request. It also has the additional benefit of allowing users to create and update IGSNs when IGSN MDS is offline. 

The background MDS processing does however mean that there will be a delay in the IGSN becoming resolvable or updated in the global system. The delay will entirely depend on how many tasks are in the queue ahead of your request. This is usually only a matter of minutes but could be longer if large bulk requests are being processed. 

You can check the registration status of the identifiers in your request by polling the '/api/resources/requests/{id}'  link returned from the request. 

Statuses returned for single requests:

Example of a mint request response

{
    "id": "6d154893-9f89-4f79-b158-b8867d1f5551",
    "status": "COMPLETED",
    "type": "igsn.mint",
    "createdBy": "1a59c4c8-d8b2-448b-84cf-7108dd54869b",
    "createdAt": "2020-12-10T02:55:18.139+00:00",
    "updatedAt": "2020-12-10T02:55:18.453+00:00",
    "message": "Successfully created Identifier 20.500.11812/XXZT1TESTJA3B",
    "summary": {
        "TOTAL TIME": "0h 0m 0s",
        "IGSN REGISTERED": "0",
        "RECORDS RECEIVED": "1",
        "IMPORT TIME": "0h 0m 0s",
        "RECORDS CREATED": "1",
        "RECORDS UPDATED": "0",
        "ERROR": "0"
    },
    "_links": {
        "self": {
            "href": "https://test.identifiers.ardc.edu.au/igsn-registry/api/resources/requests/6d154893-9f89-4f79-b158-b8867d1f5551"
        },
        "logs": {
            "href": "https://test.identifiers.ardc.edu.au/igsn-registry/api/resources/requests/6d154893-9f89-4f79-b158-b8867d1f5551/logs"
        },
        "identifiers": {
            "href": "https://test.identifiers.ardc.edu.au/igsn-registry/api/resources/requests/6d154893-9f89-4f79-b158-b8867d1f5551/identifiers"
        },
        "records": {
            "href": "https://test.identifiers.ardc.edu.au/igsn-registry/api/resources/requests/6d154893-9f89-4f79-b158-b8867d1f5551/records"
        }
    }
}


Data Model

Below is a simplified Entity Relationship Diagram (ERD) for the Metadata Registry which shows the 3 main entities relevant to API users. 

Records

Records are the main entity in the ARDC IGSN system. Each time you mint an IGSN you are creating a Record in the ARDC IGSN Registry. 


Identifiers

The unique identifiers for a resource. 

Versions 

Metadata content associated with a record.

When you mint/update an IGSN, the system will generate additional "current" versions from the provided descriptive metadata. These include a basic JSON-LD and Dublin Core representation of the provided metadata as well as the IGSN registration metadatawhich is sent to IGSN MDS. If you are minting with the CSIRO IGSN Schema the system will also generate a "current" ARDC IGSN Descriptive Schema version. This version ensures you can edit the IGSN via the Editor which currently only supports the ARDC IGSN schema.