vet data collection api development · the api development project provides a set of restful...

National Centre for Vocational Education Research

Version 6a

VET Data Collection API Development

Technical Use Cases

2 API Development Technical Use Cases

DMS #185274 3

Contents

1 Introduction 5

1.1 Purpose 5

1.2 Document Overview 5

1.3 Glossary 6

2 Scope 7

2.1 In Scope 7

2.2 Out of Scope 7

2.3 Assumptions 7

3 Overview 8

3.1 Description 8

3.2 Context diagrams 10

3.3 State Chart and permitted operations 13

4 Use Cases 14

4.1 GET Classification Type List 14

4.2 GET Classification List 15

4.3 GET Organisation List 16

4.4 GET Collection List 17

4.5 GET File Set 18

4.6 DELETE File Set 20

4.7 PUT File 22

4.8 DELETE File 24

4.9 GET File 26

4.10 POST File Content 28

4.11 PUT File Set Content Part 30

4.12 PUT File Set Content 32

4.13 PATCH File Set Content 34

4.14 GET File Set Content 38

4.15 PATCH File Set for Collection 40

4.16 GET Error List 42

4.17 Validation Status (Web Hook) 44

4.18 Shared Alternate Flows 46


Tables and figures

Tables Basic HTTP methods and their purposes 8

Candidate Resources and Methods for API 9

Figures API Session – Setup for Data Entry 10

API Session Manage File BPMN 11

API Session Upload Data BPMN 12

API Submission Process Statechart 13

DMS #185274 5

1 Introduction

1.1 Purpose

This document describes of the API services developed under the NCVER API development project

(2017).

It is intended to form the basis for:

• Agreement between parties on the signatures and other expectations of these services;

• Implementation of the services by NCVER; and

• Implementation of functionality within client systems that use these services.

1.2 Document Overview

The documentation consists of

• Scope;

• Overview; and

• Use cases.

The overview includes

• A list of the services, each with a brief description; and

• BPMN diagrams showing services in the context of a process within a candidate client system;

The use cases provide detail of the signatures and other expectations.


1.3 Glossary

Term Meaning

API Application Programming Interface. A software interface against which client programs can be developed.

AVETMISS Australian Vocational Education and Training Management Information Statistical Standard. The standard that specifies data requirements for inclusion in Collections.

AVS AVETMISS Validation Software.

BOS Board of Studies (submitter to the VIS collection)

BPMN Business Process Modelling Notation (a standard modelling notation for processes).

Collection A set of data collected by NCVER from multiple sources and combined to provide a basis for research and other purposes.

HTTP Hypertext Transfer Protocol a protocol designed to access server resources from client and which provides different methods suitable for RESTful APIs.

JavaScript A scripting language commonly supported in internet browsers.

JSON JavaScript Object Notation. A notation for representing data in textual form that allows for nested structured objects and is designed for transfer of data between programs.

JSON Schema A notation for describing JSON structures that is also written in JSON

NCVER National Centre for Vocational Education Research. The provider of AVS and the API software

Organisation Depending on context could be either :

• A submitter of AVETMISS data to a collection and particularly the representation of that submitter in the AVS/API security system; or

• A Training Organization referenced in the AVETMISS data itself.

NOTE: a submitter of data would either be an STA, an RTO or BOS

REST REpresentational State Transfer. An interface style based on using different methods to transfer state to and from resources.

RTO Registered Training Organisation (Submitter to the VET collection)

SMS Student Management System. Any system used by a Training Authority or Training Organisation to manage student data and which may act as a client for the API services.

STA State Training Authority (Submitter to the VET collection)

URI Universal Resource Identifier, a formatted string used with HTTP to identify resources.

VET Vocational Education and Training

VIS VET in Schools

DMS #185274 7

2 Scope

2.1 In Scope

The use cases in this document cover the following functions for VET collections in AVETMISS release

8:

• Retrieval of Classification data from NCVER by the client system for use in internal validation

within the client system;

• Identification of an organisation and a collection for which AVETMISS data is to be submitted;

• Monitoring of the current state of the AVETMISS data for that organisation and collection;

• Upload of data in preparation for inclusion in that collection;

• Validation of the uploaded data;

• Identification of any errors raised by the validation process; and

• update of the validated data to remove any errors;

These functions are currently provided by NCVER through the user interface driven AVS application.

The APIs provide an additional approach that SMSs can use to achieve the same results.

2.2 Out of Scope

The following functionality associated with the data in AVS is excluded from scope:

• Reporting;

• Export of submitted data;

• USI corrections;

• Apprentice and Training Collections;

• VET and VIS collections other than those covered by AVETMISS release 8;

• Submission of the validated Data

These functions will continue to be provided only by AVS.

2.3 Assumptions

To be added


3 Overview

3.1 Description

The API development project provides a set of RESTful services that receive and transmit data over HTTP. The data will mostly be transmitted in JSON format

with the exception being the submitted AVETMISS collection data which will be transmitted as either:

• Plain text message bodies containing lists of whole AVETMISS records, with a slightly modified format that allows for client a system reference; or

• Binary message bodies containing all or parts of a ZIP file that contains the complete set of AVETMISS files (again with the modified record format).

RESTful HTTP services make HTTP requests using different HTTP Methods to perform different actions on a resource.

Resources are identified by a URI and can represent any object that conceptually exists on the target server including a list of other resources. Resources covered

by the API Development project include each of the AVETMISS files stored on the server and lists of: classification values; organisations; collections; files and

errors.

The JSON message formats are specified using Open API specification. These specifications are provided to describe the structure of messages and not to provide a

full validation capability. AVETMISS formats are described in the appropriate AVETMISS standards documents

The modified AVETMISS record format allows for the inclusion of a client system generated record identifier as the last 40 characters of the record. Systems will

identify the presence of this field by preceding it with a fixed 5 character string “UUID:”. This identifier and its prefix (45 characters) must be beyond the end of

the record as described in the AVETMISS standard.

The following table provides an overview of the HTTP methods used in RESTful APIs and the uses in the API Development Project.

Basic HTTP methods and their purposes

Method Purpose API uses of the method

GET Request the identified resource Retrieval of all resources

POST Create a new subordinate resource. Appending data to a file

PUT Update the identified resource by replacing it with the request content Create a new file or replacing an existing file.

DELETE Delete the identified resource. Delete a file or a file validation process

PATCH Update the resource according to instructions contained in the request. Change the status of a set of files by initiating validation of those files to a collection.

HEAD Same as GET but only returns the header part of the response (not the body).

OPTIONS List supported Methods

TRACE Echo the request (allows the client to see changes made by enroute N/A

DMS #185274 9

The following table provides a list of the resources covered by the APIs and the HTTP Methods that are allowed for those resources. Each combination of resource and method is covered by a use case.

Candidate Resources and Methods for API

Resource type Scope Method Query Parameters Request Content Purpose

Organisation list User GET Retrieve a list of Organisations to which the user has access

Collection Type List GET Retrieve the list of Collection types supported by the system.

Collection list Collection Type GET Retrieve the list of Collections to which the selected organization has access (including the status of the latest process for that collection)

Classification type list Collection GET Retrieve a list of classification types

Classification list Collection, Classification type

GET collType, CollNbr Retrieve a list of codes for one classification type

File Set Organisation, Collection

GET Retrieve the current list of files for a chosen collection (i.e. the latest process for a collection) including the status of the file.

PATCH Operation = validate Initiate validation of the list of files or submit the list of files.

DELETE Delete a process

File Set Content Organisation, Collection

PUT Upload part of a ZIP file containing content for all files in the list multiple requests may be required depending on the size of the ZIP file to be uploaded

GET Retrieve the entire file set as a ZIP file.

PATCH Operation = compose and List of PartId

Compose the complete File Set from the listed set of parts, which must have been previously uploaded using PUT File Set Content Part

File Set Content Part Organisation, Collection,PartId

PUT Upload part of a ZIP file containing content for all files in the file set. Multiple requests may be required depending on the size of the ZIP file to be uploaded

File Organisation, Collection, File

GET Retrieve the entire file.

PUT Upload the entire file (either add or replace).

DELETE Delete the entire file.

Errors Organisation, Collection

GET Retrieve all errors for a fileSet.

Organisation, Collection, File

GET Retrieve all errors for a particular file within a fileset.

The API will use Bearer token Authentication with Bearer tokens being obtained from the AVS server using the OAuth2 Device Code extension flow.


3.2 Context diagrams

The following diagram shows a candidate scenario for setting up Classification data prior to data entry into a client system. It is intended to provide some context

around the use cases that describe each of the services rather than to dictate a process to be implemented. The list of services shown is not exhaustive

API Session – Setup for Data Entry

DMS #185274 11

The following diagram shows a candidate scenario for validation of AVETMISS data after data entry into a client system. The collapsed sub-process Upload Data is

shown in a separate diagram. It is intended to provide some context around the use cases that describe each of the services rather than to dictate a process to be

implemented. The list of services shown is not exhaustive.

API Session Manage File BPMN


The following diagram shows candidate scenarios for upload of AVETMISS data for validation. It is intended to provide some context around the use cases that

describe each of the services rather than to dictate a process to be implemented. The list of services shown is not exhaustive.

API Session Upload Data BPMN

DMS #185274 13

3.3 State Chart and permitted operations

The following state chart shows the possible values for status on FileSet and File resources and the API Operations that will be permitted depending on the

current status of the process. The status values Uploading, Validating, Queued and Submitting are transient values and permit no operations except deletion of

the whole process.

API Submission Process Statechart


4 Use Cases

4.1 GET Classification Type List

4.1.1 Description

The NCVER API provides a list of valid Classification Types, i.e. those available for use with GET

Classification List.

4.1.2 Parameters

Name Type Description

collType URI element The Collection Type of the collection for which validation will be

performed using the classifications downloaded.

collYear URI element The Collection Year Type of the collection for which validation will

be performed using the classifications downloaded.

collPeriod URI element The Collection Type of the collection for which validation will be

performed using the classifications downloaded.

4.1.3 Dialog

Name Upload File

Triggering

Event/s

1. The client system needs to identify a classification type prior to retrieving

Classification data.

Preconditions None

Basic Flow of

Events

1. The client system invokes a GET request with a matching URI

2. The NCVER API system retrieves the list of classification types from the

database.

3. The NCVER API system returns the Response with the retrieved list of

classification types, status = “success” and response code 200 OK

4.1.4 Data Attributes


Response JSON Format defined by JSON Schema:

https://avs-api.ncver.edu.au/avs-api/v2/api-

docs?group=1.0.0#definitions/classificationTypeListResponse

URI URI A string of the format

/classificationTypeList/{collType}/{collYear}/{collPeriod}

DMS #185274 15

4.2 GET Classification List

4.2.1 Description

The NCVER API provides a list of valid values for a chosen Classification Type.

4.2.2 Parameters


collType URI element The Collection Type of the collection for which validation will


collYear URI element The Collection Type of the collection for which validation will


collPeriod URI element The Collection Type of the collection for which validation will


classificationType URI element The classification type for which the data items are required.

4.2.3 Dialog

Name Upload File

Triggering

Event/s

1. The client system requires classification data for use in internal validation.

Preconditions The Client system has identified the Classification Type after executing Get

Classification type List

Basic Flow of

Events


2. The NCVER API System retrieves the list of classification items from the

database filtered by classificationType and collection;

3. The NCVER API System returns the Response with the retrieved classification

items, status = “success” and response code 200 OK

Alternate

Flow

2a The NCVER API System finds the classification Type does not exist.

2a.1 The NCVER API System returns Response with status = “Not Found”,

statusMessage = “The classificationType ({classification Type}) does not exist

for collection ({collType},{collYear},{collPeriod})” and HTTP response code

404 Not Found

2a.2 The use case ends





docs?group=1.0.0#definitions/classificationListResponse


URI URI A string of the format

/classificationList/{collType}/{collYear}/{collPeriod}/{classificationType}

4.3 GET Organisation List

4.3.1 Description

The NCVER API provides a list of valid organisations for the current user. Organisation details contains

the identifier to use for other services as well as training name and legal name.

4.3.2 Parameters

None

4.3.3 Dialog

Name Upload File

Triggering

Event/s

1. The client system needs to choose an organisation.

Preconditions None

Basic Flow of

Events


2. The NCVER API System retrieves the list of organisations from the database

where the user is either a submitter or validator.

3. The NCVER API System returns the Response with the retrieved list of

organisations , status = “success” and response code 200 OK





docs?group=1.0.0#definitions/organisationListResponse

URI URI /organisationList

DMS #185274 17

4.4 GET Collection List

4.4.1 Description

The NCVER API provides a list of valid collections for a specified collection type.

Collection details contains Collection type , year, period, start date and end date, AVETMISS release

number, and current submission start and end date.

4.4.2 Parameters


collType URI element The Collection Type for which the list of collections is required

4.4.3 Dialog

Name Upload File

Triggering

Event/s

1. The client system needs to add/update content to a file that forms part of

a validation/submission process.

Preconditions 1. The client system has identified the appropriate {collType} (derived from

the target organisation) preferably after executing use case GET

Organisation List.

Basic Flow of

Events


2. The NCVER API System retrieves the available list of collections from the

database filtered by {collType}.


collections status = “success” and response code 200 OK

Alternate

Flow

2a The NCVER API System finds the collection Type does not exist.

2a.1 The NCVER API System returns Response with status = “Not Found”,

statusMessage = “The collection type {collType} does not exist ” and HTTP

response code 404 Not Found






docs?group=1.0.0#definitions/collectionListResponse

URI URI /collectionList/{collType}


4.5 GET File Set

4.5.1 Description

The NCVER API provides a list of uploaded files for the selected organisation and collection. File

details contains name, record count, error and warning counts and processing status. An overall

validation process status is also included in the response.

4.5.2 Parameters


collType URI element The Collection Type associated with identified the

validation/submission process.

collYear URI element The Collection Year associated with the identified


collPeriod URI element The Collection Period associated with the identified


orgRef URI element The organisation Reference associated with the identified


4.5.3 Dialog

Name Upload File

Triggering

Event/s

1. The client system wishes to check the current status of a set of files

before making changes or downloading errors.

Preconditions 1. The client system has identified the appropriate organisation {orgRef},

preferably after executing GET Organisation List, and collection

{collType}, {collYear}, {collPeriod}, preferably after executing GET

Collection List.

Basic Flow of

Events


2. The NCVER API System retrieves the list of files from the database.

3. The NCVER API System returns the Response with the retrieved list of files,

status = “success” and response code 200 OK

Alternate

Flow

2a. Shared alternate flow : Collection Does Not Exist

Alternate

Flow

2b. Shared alternate flow : Organisation Does Not Exist

Alternate

Flow

2c. Shared alternate flow : Invalid access to Organisation

DMS #185274 19





docs?group=1.0.0#definitions/fileSetResponse

URI URI /fileSet/{orgRef}/{collType}/{collYear}/{collPeriod}


4.6 DELETE File Set

4.6.1 Description

The NCVER API cancels a validation process and deletes all un-submitted data associated with it

including any uploaded or validated files.

4.6.2 Parameters


collType URI Element The Collection Type associated with identified the



validation/submission process



orgRef URI Element The organisation Reference associated with the identified


4.6.3 Dialog

Name Upload File

Triggering

Event/s

1. The client system needs to cancel an entire validation/submission process.

Preconditions 1. The client system has identified the appropriate organisation {orgRef},

preferably after executing GET Organisation List, and collection

{collType}, {collYear}, {collPeriod}, preferably after executing GET

Collection List.

Basic Flow of

Events

1. The client system invokes a DELETE request with a matching URI

2. The NCVER API System Deletes the process and all associated data from the

system.

3. The NCVER API System returns the Response with status = “success” and

response code 200 OK

Alternate

Flow


Alternate

Flow


Alternate

Flow




DMS #185274 21



docs?group=1.0.0#definitions/fileSetResponse

URI URI /fileSet/{orgRef}/{collType}/{collYear}/{collPeriod}


4.7 PUT File

4.7.1 Description

The client system transmits data to the NCVER API

4.7.2 Parameters










fileId URI Element The File Identifier (e.g. nat00010) to be deleted

4.7.3 Dialog

Name Upload File

Triggering

Event/s

1. The client system needs to add or update the content of a file that forms

part of a validation/submission process.

Preconditions 1. The client system has identified the appropriate file after executing GET

File Set.

Basic Flow of

Events

1. The client system invokes a PUT request with a matching URI and plain text

AVETMISS Request Data

2. The NCVER API System finds that the file does not exist.

3. The NCVER API System creates the file using the data from the Request

4. The NCVER API System returns Response with status = “success” and HTTP

response code 200 OK

Alternate

Flow

2a The NCVER API System finds the file already exists.

2a.1 The NCVER API System replaces the file contents with the data from

the Request

2a.2 The NCVER API System returns Response with status = “success” and

HTTP response code 200 OK


Alternate

Flow


DMS #185274 23

Alternate

Flow


Alternate

Flow


Alternate

Flow

2d. Shared alternate flow : Upload Not Permitted

Alternate

Flow

2e. Shared alternate flow : Invalid Request Format

Alternate

Flow

2f. Shared alternate flow : File Id is Invalid



avetmissVersion Derived The Avetmiss Version associated with the validation/submission

process (derived from the {collType}, {collYear} and {collPeriod})

Request Plain text Plain text request containing a set of whole AVETMISS Records



docs?group=1.0.0#definitions/fileUploadResponse

URI URI /file/{collType}/{collYear}/{collPeriod}/{orgRef}/{fileId}


4.8 DELETE File

4.8.1 Description

The client system removes a file from data stored through the NCVER API.

4.8.2 Parameters










fileId URI Element The File Identifier (e.g. nat00010) to be deleted

4.8.3 Dialog

Name Upload File

Triggering

Event/s

1. The client system needs to remove a file that forms part of a



File Set.

Basic Flow of

Events

1. The client system invokes a DELETE request with a matching URI

2. The NCVER API System finds that the file exists.

3. The NCVER API System deletes the file.


HTTP response code 200 OK”

Alternate

Flow

2a The NCVER API System finds the file does not exist.

2a.1 The NCVER API System returns the Response with status = “success”

and HTTP response code 200 OK”


Alternate

Flow

2b. Shared alternate flow : Collection Does Not Exist

Alternate

Flow

2c. Shared alternate flow : Organisation Does Not Exist

DMS #185274 25

Alternate

Flow

2d. Shared alternate flow : Invalid access to Organisation

Alternate

Flow

2e. Shared alternate flow: Delete Not Permitted.

Alternate

Flow

2f. Shared alternate flow : File Id is Invalid





docs?group=1.0.0#definitions/genericResponse



4.9 GET File

4.9.1 Description

The client system retrieves AVETMISS data from the NCVER API

4.9.2 Parameters










fileId URI element The File Identifier (e.g. nat00010) of the file which the response

data will be read.

4.9.3 Dialog

Name Upload File

Triggering

Event/s

1. The client system needs to retrieve the entire contents of a file that forms

part of a validation/submission process.


File Set.

Basic Flow of

Events


2. The NCVER API System finds that the file exists.

3. The NCVER API System reads the content from the file

4. The NCVER API System returns the Response with plain text content read

from the file and HTTP response code 200 OK”

Alternate

Flow

2a The NCVER API System finds the file does not exists.

2a.1 The NCVER API System returns the Response with status == “Not

Found” , statusMessage = “Cannot find an uploaded file for Organisation

({orgRef}), Collection ({collType},{collYear},{collPeriod}) and id ({fileId})”

and Status code 404 Not Found


Alternate

Flow


DMS #185274 27

Alternate

Flow


Alternate

Flow


Alternate

Flow

2e. Shared alternate flow : File Id is Invalid



Response text/plain Plain text response containing a set of whole AVETMISS



4.10 POST File Content

4.10.1 Description

The client system transmits AVETMISS data to the NCVER API as additional content for an existing file

or the initial content of a file that does not exist.

4.10.2 Parameters










fileId URI element The File Identifier (e.g. nat00010) to which the desired Validation

Submission process is validated, or ready

4.10.3 Dialog

Name Upload File

Triggering

Event/s

1. The client system needs to add content to a file that forms part of a



File Set.

Basic Flow of

Events

1. The client system invokes a POST request with a matching URI

2. The NCVER API System finds that the file does not exist.

3. The NCVER API System creates the file using the data from the {File

Upload Request}

4. The NCVER API System returns The Response with status = “success” and

Response code 200 OK

Alternate

Flow

2a The NCVER API System finds the file already exists.

2a.1 The NCVER API System appends records to the file with the data from

the {File Upload Request}

2a.2 The NCVER API System returns The Response with status = “success”

and Response code 200 OK


DMS #185274 29

Alternate

Flow


Alternate

Flow


Alternate

Flow


Alternate

Flow

2e. Shared alternate flow : Upload Not Permitted

Alternate

Flow

2f. Shared alternate flow : Invalid Request Format

Alternate

Flow

2g. Shared alternate flow : File Id is Invalid





Request text/plain Plain text request containing a set of whole AVETMISS Records



docs?group=1.0.0#definitions/fileUploadResponse


http://api.avs.ncver.edu.au/api#definitions/fileUploadResponse

http://api.avs.ncver.edu.au/api#definitions/fileUploadResponse


4.11 PUT File Set Content Part

4.11.1 Description

The client system requests upload of part of a zipped set pf AVETMISS files in preparation for

validation.

4.11.2 Parameters










partId URI element A string uniquely identifying the this part within the set of parts

that constitute the whole Zipped Fileset.

4.11.3 Dialog

Name Upload File

Triggering

Event/s

1. The client system needs to upload a set of files for validation and has

chosen to do so in ZIP file format but the file is too large to upload in one

piece.

Preconditions 1. The client system has identified the appropriate organisation {orgRef} and

collection {collType}, {collYear}, {collPeriod}.

Basic Flow of

Events

1. The client system invokes a PUT request with:

URI – {File Set Content Part URI}

Content - {File Set Content Part Request}

2. The NCVER API system confirms that the process status allows upload.

3. Stores the data from the request body as a file in preparation for assembly.

4. The NCVER API System returns Response with status = “success” and

Response Code = 200 OK

Alternate

Flow


Alternate

Flow


DMS #185274 31

Alternate

Flow




File Set

Content Part

Request

application

/octet-

stream

Binary Data containing a part of a ZIP file to be combined later by

PATCH File Set Content

Generic

Response

JSON Format defined by JSON Schema:



File Set

Content Part

URI

URI /{collType}/{collYear}/{collPeriod}/{orgRef}/allFiles.zip/{partId}


4.12 PUT File Set Content

4.12.1 Description

The client system requests upload of a complete zipped set of AVETMISS files in preparation for

validation.

4.12.2 Parameters










4.12.3 Dialog

Name Upload File

Triggering

Event/s

1. The client system needs to upload a set of files for validation and has

chosen to do so in ZIP file format and the file is small enough to upload in

one piece.



Basic Flow of

Events

1. the client system invokes a PUT request with:

URI – {File Set Content URI}

Content - {File Set Content Request}


3. The NCVER API system extracts the files from the contents of the request

using ZIP file format but ignores any files with names that are not valid

AVETMISS file Ids



DMS #185274 33

Alternate

Flow

2a The NCVER API system fails to unpack any contents of the request using ZIP

format.

2a.1 The NCVER API System returns The Response with status == “Bad

Request”, statusMessage = “Empty or invalid Zip content provided.”, and

Response code = 400 Bad Request.


Alternate

Flow


Alternate

Flow


Alternate

Flow


Alternate

Flow

2e The NCVER API system fails to unpack the contents of the request using ZIP

format after initially successfully processing part of the content.

2e.1 The NCVER API System returns The Response with status == “Bad

Request”, statusMessage = “Error extracting content for file {filename}”,

and Response code = 400 Bad Request.

2e.2 The use case ends





Request application/

zip

Binary Data containing the content of a ZIP file containing the

AVETMISS files




URI URI /{collType}/{collYear}/{collPeriod}/{orgRef}/allFiles.zip


4.13 PATCH File Set Content

4.13.1 Description

The client system requests upload of a complete zipped set of AVETMISS files in preparation for

validation.

4.13.2 Parameters










operation JSON Request

body element

The operation to be performed on the file set content (only

“compose” is currently supported but this has been included to

allow for future expansion)

partIds JSON Request

body element

The list of {partId} values that were used within previous PUT

FileSet Content Part requests and which, when concatenated in the

order listed, constitute the whole ZIP file.

4.13.3 Dialog

Name Upload File

Triggering

Event/s

1. The client system is uploading a set of files for validation in ZIP file format

that is too large to upload in one piece and the client system needs to

finish the upload process using the pieces already uploaded.



2. The user has previously uploaded several File Set Content Parts using PUT

File Set Content Part

DMS #185274 35

Basic Flow of

Events

1. The client system invokes a PATCH request with a matching URI


3. The NCVER API system finds the {operation} is “compose”

4. The NCVER API system confirms that all partIds listed in the request

correspond to existing previously uploaded parts

5. The NCVER API system concatenates the parts in the order listed in the

request

6. The NCVER API system extracts the files from the concatenated parts using

ZIP file format but ignores any files with names that are not valid

AVETMISS file Ids

7. The NCVER API system deletes all parts whether they were listed or not

(assuming those not listed were from abandoned or failed upload

attempts.



Alternate

Flow


Alternate

Flow


Alternate

Flow


Alternate

Flow

2f The NCVER API system recognises that the one or more of the file parts

listed in the request have not been successfully uploaded.

2f.1 The NCVER API System returns The Response with status == “Bad

Request” and statusMessage = “One or more of the listed File Set Content

Parts has not been uploaded, ({partIds:[ a list of partIds for the missing file

parts]}) for the identified collection ({collType},{collYear},{collPeriod}) and

Organisation ({orgRef})” and Response code = 400 Bad Request.

2f.2 The use case ends

Alternate

Flow

2g The NCVER API system fails to unpack any contents of the request using ZIP

format.

2g.1 The NCVER API System returns The Response with status == “Bad

Request”, statusMessage = “Empty or invalid Zip content provided.”, and

Response code = 400 Bad Request.

2g.2 The use case ends


Alternate

Flow

2h The NCVER API system fails to unpack the contents of the request using ZIP

format after initially successfully processing part of the content.

2h.1 The NCVER API System returns The Response with status == “Bad

Request”, statusMessage = “Error extracting content for file {filename}”,

and Response code = 400 Bad Request.

2h.2 The use case ends

DMS #185274 37



Request JSON Format defined by JSON Schema:


docs?group=1.0.0#definitions/filesetContentPatchRequest


https://avs-api.ncver.edu.au/avs-api/v2/api-docs?group=1.0.0#definitions/

filesetContentPatchResponse



4.14 GET File Set Content

4.14.1 Description

The client system requests download of a complete zipped set of AVETMISS.

4.14.2 Parameters










4.14.3 Dialog

Name Upload File

Triggering

Event/s

1. The client system needs to download a set of files for validation and has

chosen to do so in ZIP file format.



2. The user has previously uploaded data using APIs from File Set Content or

File resources

Basic Flow of

Events

1. The client system invokes a PUT request with a matching URI

2. The NCVER API system confirms that the uploaded data is still present.

3. The NCVER API system returns Response with Response Code = 200 OK

Alternate

Flow


Alternate

Flow


Alternate

Flow


DMS #185274 39



Response application/

octet-stream

Binary Data containing the content of a ZIP file containing the

AVETMISS files



4.15 PATCH File Set for Collection

4.15.1 Description

The client system requests Validation of data previously transmitted to the NCVER API.

4.15.2 Parameters


collType URI The Collection Type associated with identified the






orgRef URI The organisation Reference associated with the identified


operation JSON Request

body element

The operation to be performed on the file set (only “validate” is

currently supported but this has been included to allow for future

expansion)

callbackUrl JSON Request

body element

URL that will be invoked to signal completion of the process (see

4.17 Validation Status (Web Hook)).

4.15.3 Dialog

Name Upload File

Triggering

Event/s

1. The client system needs to validate the files that are the target of



collection {collType}, {collYear}, {collPeriod} after executing GET

Collection List.

2. The client system has transmitted data for validation by executing API

services on File and Record List resources.

Basic Flow of

Events

1. the client system invokes a PATCH request with a matching URI

2. The NCVER API system recognises the request contains operation =

“validate”

3. The NCVER API system confirms that the process status allows validation.

4. The NCVER API System initiates the Validation using the AVS rules engine

and includes the callbackUrl if it is provided.


with Response Code = 200 OK

DMS #185274 41

Alternate

Flow


Alternate

Flow


Alternate

Flow


Alternate

Flow


Alternate

Flow

2f The NCVER API system recognises the request contains operation =

“validate” but the fileset status does not support validation

2f.1 The NCVER API System returns the Response with status =

“Forbidden”, statusMessage = “Cannot transition process from

{currentStatus} to Validating.” and Response Code = 403 Forbidden.

Alternate

Flow

2g The NCVER API system recognises the request contains operation other than

validate

2g.1 The NCVER API System returns the Response with status =

“Forbidden”, statusMessage = “Operation {operation} has not been

implemented.” and Response Code = 403 Forbidden.







docs?group=1.0.0#definitions/fileSetActionRequest



docs?group=1.0.0#definitions/fileSetActionResponse

URI URI fileSet/{collType}/{collYear}/{collPeriod}/{orgRef}


4.16 GET Error List

4.16.1 Description

The client system retrieves error details from the NCVER API for AVETMISS data after validation.

4.16.2 Parameters










fileId URI Element The File Identifier (e.g. nat00010) to which the desired Validation

Submission process is validated, or ready

4.16.3 Dialog

Name Upload File

Triggering

Event/s

1. The client system needs to retrieve errors related to files that form part of

a validation/submission process.

Preconditions 1. The client system has identified the appropriate file(s) after executing

GET File Set.

Basic Flow of

Events

1. the client system invokes a GET request with a matching URL

2. The NCVER API System reads the errors from the database filtered

according to the supplied query parameters.

3. The NCVER API System returns Response with status = “success” ” and with


Alternate

Flow


Alternate

Flow


Alternate

Flow


Alternate

Flow


DMS #185274 43

Alternate

Flow

2f The NCVER API system recognises fileset for which the errors are being

requested has not been validated since upload:

2f.1 The NCVER API System returns the Response with status =

“Conflict”, statusMessage = “The latest fileset uploaded for Organisation

({orgRef}) and Collection ({collType},{collYear},{collPeriod}) has not yet been

validated.” and Response Code = 409 Conflict.

Alternate

Flow

2g The NCVER API system recognises fileset for which the errors are being

requested does not exist:

2g.1 The NCVER API System returns the Response with status = “Not

Found”, statusMessage = “There is no file set for Organisation ({orgRef}) in

Collection ({collType},{collYear},{collPeriod}).” and Response Code = 404 Not

Found.





docs?group=1.0.0#definitions/errorListResponse

URI URI errorList/{collType}/{collYear}/{collPeriod}/{orgRef}; or

errorList/{collType}/{collYear}/{collPeriod}/{orgRef}/{fileId}


4.17 Validation Status (Web Hook)

4.17.1 Description

The NCVER API notifies the client system that a requested Validation has completed.

4.17.2 Parameters


collType Internal Data The Collection Type associated with identified the


collYear Internal Data The Collection Year associated with the identified


collPeriod Internal Data The Collection Period associated with the identified


orgRef Internal Data The organisation Reference associated with the identified


callbackUrl Internal Data URL that will be invoked to signal completion of the process.

status Internal Data The final status of the File Set that was the subject of the

validation job.

retryCount Internal Data The number of retries that have already been attempted.

4.17.3 Dialog

Name Upload File

Triggering

Event/s

1. The AVS Validation engine completes a validation Job that was initialised

with a Web Notification Address.

Preconditions 1. The client system has identified the appropriate file(s) after executing

GET File Set.

Basic Flow of

Events

1. The AVS Validation engine publishes an event with :

{collType},{collYear},{collPeriod},{orgRef},{callbackUrl},{processStatus}

and {retryCount}

2. The NCVER API System receives the event .

3. The NCVER API System sends an HTTP post request to the {callbackUrl}

containing the {collType},{collYear},{collPeriod},{orgRef} and

{processStatus}

4. The application at the {callbackUrl} returns a response with HTTP response

in the 200 range.

DMS #185274 45

Alternate

Flow

4a The application at the {callbackUrl} returns a response with HTTP response

Code in the 300 range.

4a.1 The NCVER API System follows any redirection as a GET request.


Alternate

Flow

4b The application at the {callbackUrl} returns a response with HTTP response

Code in the 400 range.

4b.1 The use case ends (the NCVER API System abandons the attempt to

notify the webhook)

Alternate

Flow

4c The application at the {callbackUrl} returns a response with HTTP response

Code in the 500 range and {retryCount} is >= 5.

4c.1 The use case ends (the NCVER API System abandons the attempt to

notify the webhook)

Alternate

Flow

4d The application at the {callbackUrl} returns a response with HTTP response

Code in the 500 range and {retryCount} is < 5.

4d.1 The NCVER API System increments the {retryCount} and republishes

the event with a 5 minute delay;

4d.2 The Basic flow resumes at step 2.

Alternate

Flow

4e The application at the {callbackUrl} does not return a response (i.e. the

request times out) and {retryCount} is >= 5.

4e.1 The use case ends (the NCVER API System abandons the attempt to

notify the webhook)

Alternate

Flow

4f The application at the {callbackUrl} does not return a response (i.e. the

request times out) and {retryCount} is < 5.

4f.1 The NCVER API System increments the {retryCount} and republishes

the event with a 5 minute delay;

4f.2 The Basic flow resumes at step 2.





docs?group=1.0.0#definitions/validatonNotificationResponse


4.18 GET Collection Type List

4.18.1 Description

The NCVER API provides a list of valid collection types and provides the API code and AVETMISS name

for each.

4.18.2 Parameters


(None)

4.18.3 Dialog

Name Get List

Triggering

Event/s

1. The client system needs to identify the collection before downloading the

classification data for a collection.

Preconditions 1. none.

Basic Flow of

Events


5. The NCVER API System retrieves the available list of collection types.


collections status = “success” and response code 200 OK





docs?group=1.0.0#definitions/collectionListResponse

URI URI /collectionTypeList

DMS #185274 47

4.19 Shared Alternate Flows

Name Steps

Invalid Token The NCVER API system finds that the credentials provided are incorrect.

1 The NCVER API System returns the Response with status ==

“Unauthorised” and statusMessage = “Invalid access token provided” and

response code 403 Unauthorized

1.a. The response will also contain a WWW-Authenticate header with

error=”invalid_token” and error_description matching the statusMessage

above

2 The use case ends

Invalid User The NCVER API system finds that the credentials provided are incorrect.

1 The NCVER API System returns the Response with status == “Forbidden”

and statusMessage = “The user associated with the provided token does not

have the required access” and response code 403 Forbidden

1.a. The response will also contain a WWW-Authenticate header with

error=”insufficient_scope” and error_description matching the

statusMessage above

2 The use case ends

Collection

Does Not Exist

The NCVER API system recognises that the collection does not exist.

1 The NCVER API System returns the Response with status == “Not Found” ,

statusMessage = “The identified collection

({collType},{collYear},{collPeriod}) does not exist” and response code 404

Not Found

2 The use case ends

Organisation

Does Not Exist

The NCVER API system recognises that the identified organisation does not

exist.

1 The NCVER API System returns the Response with status == “Not Found” ,

statusMessage = “The identified organisation ({orgRef}) does not exist” and

response code 404 Not Found

2 The use case ends

Invalid access

to

Organisation

The NCVER API system recognises that the user does not have access to the

identified organisation.

1 The NCVER API System returns the Response with status == “Forbidden” ,

statusMessage = “The current user does not have access to the identified

organisation ({orgRef})” and response code 403 Forbidden

2 The use case ends


Upload Not

Permitted

The NCVER API System finds the process status does not permit upload.


and statusMessage = “Cannot transition process from {currentStatus} to

Uploading.” and response code 403 Forbidden

2 The use case ends

Delete Not

Permitted

The NCVER API System finds the process status does not permit delete.


and statusMessage = “Cannot transition process from {currentStatus} to

Uploading.” and response code 403 Forbidden

2 The use case ends`

Invalid Access

to File Set

The NCVER API system recognises that the user does not have access to the

identified Validation/Submission process or fileset.


and statusMessage = “The current user does not have the required access

to the identified file set” and response code 403 Forbidden

2 The use case ends

Invalid

Request

Format

The NCVER API system recognises that the request content format does not

match the format expected for the URL.

1 The NCVER API System returns the Response with status == “Bad

Request” and statusMessage indicating the nature of the content

mismatch” and response code 400 Bad Request

2 The use case ends

File Id is

Invalid

The NCVER API system recognises that the request fileId parameter does not

identify a file that is valid for the collection identified in the URL.

1 The NCVER API System returns the Response with status == “Not Found”

and statusMessage = “Invalid File Name {FileId}” and response code = 404

Not Found

2 The use case ends

vet data collection api development · the api development project provides a set of restful...

Documents