Page tree
Contents

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:

  • Metadata Registry - The registry is the heart of the service and is responsible for managing all IGSN requests and associated data. 
  • IGSN Editor - Web interface for clients to create and manage their IGSNs.
  • IGSN Portal - Web interface for viewing IGSN metadata. 
  • Identity and Access Management - Used by administrations to manage access to the service.


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:

  • CREATED - The request has been stored in the system.

  • ACCEPTED - The request has passed pre-validation. 

  • QUEUED - The request is queued for processing. 

  • RUNNING - The request is being processed.

  • COMPLETED - The request has been processed. Note that this does not mean that all transactions were successful. Please refer to the summary within the request for details.

  • FAILED - The system was unable to process any item in the request successfully. E.g. Failure to create all 10 records in the request payload because they already exist. 

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:

  • COMPLETED - The request has been processed successfully. Note that as mentioned above, this does not mean that the MDS registration/update has been performed. Please refer to the summary within the request for details.

  • FAILED - The request passed pre-validation but there was an error processing the request. It is unlikely that you will see this status. It can occur when simultaneous requests attempt to action the same IGSN. E.g. 2 mint requests for the same IGSN.

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. 

Simplified Data Model

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. 

  • Each record must relate to at least 1 identifier (e.g. an IGSN). 
  • Each record may relate to 0 or more metadata versions.
    • A record may only relate to one "current" version in each schema supported by the service. 
    • A record may relate to many "superseded" versions.
  • Records are owned by individual users or groups. 
  • Possible record visibility statuses::
    • Public - the current metadata version for the record is publicly visible in the ARDC IGSN Portal and exposed via the OAI-PMH protocol. 
    • Private - the metadata for a record is only visible in the ARDC IGSN Portal by authenticated and authorised users. The metadata is not exposed publicly via the OAI-PMH protocol or other API endpoints. The private status includes metadata that is still under an active embargo period. 


Identifiers

The unique identifiers for a resource. 

  • When you mint/reserve an IGSN, the system will create an identifier with the value provided in the descriptive metadata and associate it with a record. The type of identifier is set by the system and is always 'IGSN"
  • Identifiers must relate to a single record.
  • All identifiers for a record can be retrieved by using the /api/resources/records/{id} API endpoint. 
  • Possible identifier statuses:
    • Pending - Waiting to be registered in IGSN MDS
    • Accessible - The identifier has been registered in IGSN MDS
    • Reserved - The identifier value has been reserved. The identifier has NOT been registered in IGSN MDS. 

Versions 

Metadata content associated with a record.

  • Each time you submit a request to mint/update an IGSN the descriptive metadata provided in the request is saved as a version. 
  • The latest version in each supported schema is always set to a status of "current". 
  • Versions must relate to a single record.
  • Possible version statuses:
    • Current - the latest version of metadata in a specific schema. "Current" is the only status of metadata which is exposed by the OAI-PMH protocol for publicly visible records.
    • Superseded - historical version of metadata.

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. 

  • No labels

This page has no comments.