Page tree
Contents

Authentication

After ANDS has set up your IGSN account you will be issued with an Account Name and Password to use with the API.

Example:

  • Account Name: ANDS.EXAMPLE
  • Password: 5f4ab4cdeaa

To authenticate with the IGSN service API your credentials must be passed in the HTTP request header using basic authentication.

PHP example:

  • Authorization: Basic '.base64_encode($app_id.":".$password) ;
    OR
  • $str = base64_encode($app_id.":".$password);
    Authorization: Basic '.$str;

Service Endpoints

Mint an IGSN

Mints a new IGSN with associated metadata.

Each mint request is comprised of two parts. The first part of the request is concerned with validating the request and updating the ANDS IGSN Service database. The second part of the request registers the IGSN in the global IGSN system and is only processed if the first part succeeds. The basic flow of this process is shown in the diagram below:

 

Service Point

Service Type

POST

Post Variables

Name

Required?

Description

Example

XML

Yes

The CSIRO IGSN schema v3 XML which describes the sample

Example IGSN XML

Schema documentation https://igsn.csiro.au/schemas/3.0/doc/

Responses

It’s important to note that because of the 2 part structure of a mint request, the JSON response message sent back from the API is also comprised of 2 parts. The databaseStatus messages and codes indicate if the ANDS IGSN service database was successfully updated while the mintStatus messages and codes indicate if the IGSN was successfully registered in the global IGSN system.

Where a mint partially succeeds (e.g. created in ANDS DB but minting fails at IGSN) the API returns a status of 200 with a structured JSON message. Until ANDS can update the API to return another HTTP status, users should check along with the HTTP status, that the 'mintStatusCode' and 'databaseStatusCode' values are set to "200".

HTTP status codes

Status Code Response Message Format
200Returned upon successful mint or partial mint.JSON
400Returned when request fails due to invalid XMLString
401Returned when credentials are incorrect/not passedHTML
400Returned when request can not be processed due to not-well-formed XMLHTML

Mint error codes

mintStatus messagemintStatusCode
PREFIX_UNREGISTERED101
MINT_FAILURE102
MINT_SUCCESS200

Database error codes

databaseStatus messagedatabaseStatusCode
UPDATE_ERROR103
DUPLICATE_KEY104
NOT_ATTEMPTED(105
 UPDATE_SUCCESS 200

 

Example of a successful response message

[
    {
        "mintStatus": "MINT_SUCCESS",
        "databaseStatus": "UPDATE_SUCCESS",
        "mintLog": "Mint Successful",
        "databaseLog": "Database successfully updated.",
        "mintExceptionCause": null,
        "databaseExceptionCause": null,
        "sampleId": "XXAATDOJBO23",
        "handle": "http://hdl.handle.net/20.500.11812/XXAATDOJBO23",
        "mintStatusCode": 200,
        "databaseStatusCode": 200
    }
]

Example of a failure response message due to invalid XML

XML validation failed : null

Example of a failure response message due to not-well-formed XML

<html>
    <head>
        <title>Apache Tomcat/7.0.69 - Error report</title>
        <style>
            <!--H1 {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:22px;} H2 {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:16px;} H3 {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;font-size:14px;} BODY {font-family:Tahoma,Arial,sans-serif;color:black;background-color:white;} B {font-family:Tahoma,Arial,sans-serif;color:white;background-color:#525D76;} P {font-family:Tahoma,Arial,sans-serif;background:white;color:black;font-size:12px;}A {color : black;}A.name {color : black;}HR {color : #525D76;}-->
        </style>
    </head>
    <body>
        <h1>HTTP Status 400 - </h1>
        <HR size="1" noshade="noshade">
        <p>
            <b>type</b> Status report
        </p>
        <p>
            <b>message</b>
            <u></u>
        </p>
        <p>
            <b>description</b>
            <u>The request sent by the client was syntactically incorrect.</u>
        </p>
        <HR size="1" noshade="noshade">
        <h3>Apache Tomcat/7.0.69</h3>
    </body>
</html>

IGSNs minted via the API cannot be edited via the IGSN Service Web Interface (Due to complexity of mapping certain field to html widgets)

 

Mint Test IGSN

This endpoint allows users to test their integration with the ANDS IGSN service without actually minting IGSNs. The service runs through the full mint process of an IGSN including XML validation and sending the request to register the IGSN in the global IGSN system, however, no information is committed into the ANDS IGSN database nor registered in the IGSN global system. 

Service Point

Service Type

GET

Responses

Status Response Message Format
200Returned upon successful GETXML
404Returned when IGSN does not exist.String
401Returned when credentials are incorrect/not passedHTML

Retrieve IGSN Metadata

Gets the metadata associated with an IGSN.

Service Point

https://handle.ands.org.au/igsn/api/metadata/30/retrieve/<IGSN>

E.g. https://handle.ands.org.au/igsn/api/metadata/30/retrieve/XXAA2DJIBN

Service Type

GET

Service Point Parameters

Name

Required?

Description

Example

schema

No

Preferred response schema

Must be one of:

  • 'cs_igsn' (the csiro IGSN schema returned as XML)
  • 'igsn' (top level IGSN schema returned as XML)
  • 'oai_dc' (standard dublin core implementation returned as JSON)

NA

Responses

Status Response Message Format
200Returned upon successful GETXML/JSON
404Returned when IGSN does not exist.String
401Returned when credentials are incorrect/not passedHTML