netting event - fishserve event.pdf · parameter required data type description is net lost...

Netting Event The sections below describe the information necessary to create, get and update a Netting event.

Create

Request URL:

POST https://ers.demo.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/netting/{eventID}

Example:

POST https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/netting/5ba04c30-c81a-4618-898e-e832da93cf99

Create URL Parameters:

Parameter Required Data type Description

Client Number Mandatory String The main permit holder client number that the event is submitted against.

Event ID Mandatory String Unique logbook generated ID for an event.

Request Header:

Content-Type: application/json

Software-Vendor: YOUR_SOFTWARE_VENDOR_NAME (For example, elogbook)

Software-Version: YOUR_SOFTWARE_VERSION_NUMBER (For example, 1.0.0.0)

Software-Installation-Id: YOUR_SOFTWARE_INSTALLATION_ID (Optional) (For example, a13afab2-c409-4622-b8f8-146996587809)

Authorization: Bearer YOUR_USER_TOKEN

Request Body Parameters:

Parameter Required Data Type Description

Event ID Mandatory String Unique logbook generated ID for an event. The same event ID as defined in the URL.

Is Vessel Used Mandatory Boolean Identifies if the fishing took place on a vessel or not

Vessel Number Mandatory String If the fishing took place on a vessel, then the vessel must be identified. Must be a valid vessel number.

Notes Optional String The Fisher may record additional information relating to the event.

Method Mandatory String Must be a valid Method for the Fishing Event Type. E.g. the SN method must be reported through the netting Fishing Event.

Target Species Code Mandatory String Must be a valid species.

Mitigation Devices Used Optional Array of Strings List all mitigation devices used. Must be a valid mitigation device.

Start Date Time Mandatory String Must provide a date, 24 hr time and UTC offset. Date time of start SET.

Start Location Mandatory Geolocation See Start Location Parameters below. Position of start SET.

Is Non Fish Or Protected Species Catch Present

Mandatory Boolean The Fisher is to state whether or not they have caught any non-fish or protected species.

Total Length of Nets Meters Mandatory Number Can provide up to 2 decimal places. Must be greater than 0.

Min Mesh Size Mm Mandatory Number Can provide up to 2 decimal places. Smallest size of net if multiple sized nets used. Must be greater than 0.

Net Height Mandatory Number Number of meshes. Must be greater than 0.


Is Net Lost Conditional Boolean Records if net has been lost and unable to be hauled.

Start of Haul Date Time Mandatory String If not provided, ‘Is Net Lost’ must be true. Must provide a date, 24 hr time and UTC offset.

Finish Date Time Mandatory String Must provide a date, 24 hr time and UTC offset. Date Time of finish SET.

Finish Location Mandatory Geolocation See Finish Location Parameters below. Position of finish SET.

Catches Mandatory if

Estimated Catch > 0

Array See Catches Parameters below.

Non Fish or Protected Species Mandatory if Is Non

Fish Or Protected

Species Catch

Present is ‘Yes’

Array See Non Fish or Protected Species Parameters below.

Start Location Parameters:


Start Latitude Mandatory String Must provide at least 4 decimal places.

Start Longitude Mandatory String Must provide at least 4 decimal places.

Is Start Location Manual Mandatory Boolean Identifies if the GPS details have been altered by the Fisher.

Finish Location Parameters:


Finish Latitude Mandatory String Must provide at least 4 decimal places.


Finish Longitude Mandatory String Must provide at least 4 decimal places.

Is Finish Location Manual Mandatory Boolean Identifies if the GPS details have been altered by the Fisher.

Catches Parameters:


Species Code Mandatory String Must be a valid species.

Green Weight Estimate Kg Mandatory Number Can provide up to 2 decimal places.

Non Fish or Protected Species Parameters:


Species Code Mandatory String Must be provided if Non Fish Or Protected Species Catch Present is True. Valid species from the non-fish / protected species list.

Seabird Capture Details Optional String

Estimated Weight Kg Mandatory if

measured_by =

weight

Number Must be a whole number.

Number Uninjured Mandatory if

measured_by =

count



Number Injured Mandatory if

measured_by =

count


Number Dead Mandatory if

measured_by =

count


Tag Optional Array of Strings NFPS Tag Number.

Request Body:

Example:

{

"eventHeader": {

"eventId": "5ba04c30-c81a-4618-898e-e832da93cf99",

"vesselNumber": "1",

"isVesselUsed": true,

"notes": "Fishing conditions were poor"

},

"method": "DN",

"targetSpeciesCode": "HOK",

"mitigationDevicesUsed": ["STR", "LAS"],

"startDateTime": "2017-04-05T09:15:00+11:00",

"startLocation": {

"longitude": "174.732177",

"latitude": "-41.409898",

"isManual": false

},

"totalLengthOfNetsMeters": 4

"minMeshSizeMm": 1.5,

"netHeight": 3,

"isNetLost": false,

"startOfHaul": "2017-05-04T11:30:00+13:00",

"finishDateTime": "2017-05-04T12:30:00+13:00",

"finishLocation": {

"longitude": "174.6799",

"latitude": "-41.4289",

"isManual": false

},

"catches": [

{

"speciesCode": "CRA",

"greenWeightEstimateKg": 50.25,

},

{

"speciesCode": "HOK",

"greenWeightEstimateKg": 25,

},

],

"isNonFishOrProtectedSpeciesCatchPresent": false,

"nonFishOrProtectedSpeciesCatches": [

{

"speciesCode": "XAF",

"seabirdCaptureDetails": "Warp",

"estimatedWeightKg": null,

"numberUninjured": 2,

"numberInjured": 3,

"numberDead": 5,

"tags": ["SG101", "SG105", "SG305", "SG501", "SG111"]

},

{

"speciesCode": "DEN",

"seabirdCaptureDetails": null,

"estimatedWeightKg": 45.54,

"numberUninjured": null,

"numberInjured": null,

"numberDead": null,

"tags": ["SDG101", "DG105", "DG305", "DG501", "DG111"]

},

]

}

Response Response Status:

Status Description

201 Created Status when event has been accepted successfully.

400 Bad Request Status when there are missing headers, missing event parameters, duplicate event ID.

401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.

Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.

Parameter Data Type Description

Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:


Property Name String The name of the property that has an error.

Attempted Value String The attempted value used.

Error Code String The type of error.

Error Message String The description of the error.

Example 1:

The following example of the response body is returned when there are no errors and the event is accepted (Status Code – 201).

{

"errors": []

}

Example 2:

The following example of the response body is returned when there are errors and the event is rejected (Status Code – 400).

{

"errors": [

{

"propertyName": "EventId",

"attemptedValue": "5ba04c30-c81a-4618-898e-e832da93cf99",

"errorCode": "DuplicateValue",

"errorMessage": "EventId already exists."

}

]

}

Get

Request URL:

GET https://ers.demo.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/netting/{eventID}

Example:

GET https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/netting/5ba04c30-c81a-4618-898e-e832da93cf99





Request Header:







Status Description

200 Ok Status when event has been retrieved successfully.

Status Description

404 Not Found Status when event cannot be found.


Response Body Parameters:

Parameter Data Type

Event ID String

Is Vessel Used Boolean

Vessel Number String

Notes String

Method String

Target Species Code String

Mitigation Devices Used Array of Strings

Start Date Time String

Start Location See Start Location Parameters below.

Geolocation

Is Non Fish Or Protected Species Catch Present

Boolean

Total Length of Nets Meters Number

Min Mesh Size Mm Number

Net Height Number

Is Net Lost Boolean

Parameter Data Type

Start of Haul Date Time String

Finish Date Time String

Finish Location See Finish Location Parameters below.

Geolocation

Catches See Catches Parameters below.

Array

Non Fish or Protected Species See Non Fish or Protected Species Parameters below.

Array

Errors Array

Start Location Parameters:

Parameter Data Type

Start Latitude Number

Start Longitude Number

Is Start Location Manual Boolean

Finish Location Parameters:

Parameter Data Type

Finish Latitude Number

Finish Longitude Number

Is Finish Location Manual Boolean

Catches Parameters:

Parameter Data Type

Species Code String

Parameter Data Type

Green Weight Estimate Kg Number

Product State String

Processed Weight Kg Number

Number of Fish Number

Non Fish or Protected Species Parameters:

Parameter Data Type

Species Code String

Seabird Capture Details String

Estimated Weight Kg Number

Number Uninjured Number

Number Injured Number

Number Dead Number

Tag Array of Strings

Response Body:

Example:

{

"event": {



"netHeight": 3,

"isNetLost": false,

"startOfHaul": "2017-05-04T11:30:00+13:00",

"method": "DN",


"mitigationDevicesUsed": [

"STR",

"LAS"

],

"startDateTime": "2017-04-05T09:15:00+11:00",

"startLocation": {

"longitude": 174.732177, "latitude": -41.409898,

"isManual": false

},


"finishLocation": {

"longitude": 174.6799,

"latitude": -41.4289,

"isManual": false

},


"catches": [

{

"speciesCode": "CRA",


"productState": null,

"processedWeightKg": null,

"numberOfFish": null

},

{


"greenWeightEstimateKg": 25,

"productState": null,

"processedWeightKg": null, "numberOfFish": null

},

],

"nonFishOrProtectedSpeciesCatches": [

{

"speciesCode": "XAF",

"seabirdCaptureDetails": "Warp",

"estimatedWeightKg": null,

"numberUninjured": 2,

"numberInjured": 3,

"numberDead": 5,

"tags": ["SG101", "SG105", "SG305", "SG501", "SG111"]

},

{

"speciesCode": "DEN",

"seabirdCaptureDetails": null,

"estimatedWeightKg": 45.54,

"numberUninjured": null,

"numberInjured": null,

"numberDead": null,

"tags": ["SDG101", "DG105", "DG305", "DG501", "DG111"]

}, ],


"schemaEdition": 1,

"eventVersion": 1,

"clientNumber": "1234567",

"eventDateTime": "2017-04-05T09:15:00+11:00",



"notes": "Fishing conditions were poor"

},

"errors": []

}

Update

Request URL:

PUT https://ers.demo.kupe.fishserve.co.nz/api/{clientNumber}/event/v1/netting/{eventID}

Example:

PUT https://ers.demo.kupe.fishserve.co.nz/api/1234567/event/v1/netting/5ba04c30-c81a-4618-898e-e832da93cf99





Request Header:






Request Body Parameters:

The request body parameters includes all those fields that have been defined in the create event and the following additional parameters.

The amended value of the fields that need to be updated will be passed in the request body.


Event Version Mandatory Number The version of the event that the fisher is wanting to update.

Request Body:

Example:

{

"eventHeader": {


"eventVersion" : 1,



"notes": "None"

},

"startDateTime": "2017-04-05T09:15:00+11:00",

"method": "DN",


"mitigationDevicesUsed": ["HOP", "DDD"],

"startLocation": {

"longitude": "174.732177",

"latitude": "-41.409898",

"isManual": false

},




"netHeight": 3,

"isNetLost": false,

"startOfHaul": "2017-05-04T11:30:00+13:00",


"finishLocation": {

"longitude": "174.6799",

"latitude": "-41.4289",

"isManual": false

},

"catches": [

{

"speciesCode": "SNA",


},

{



}

],

}


Status Description

200 Ok Status when event has been updated successfully.

400 Bad Request Status when event failed to update. This can be as a result of the event version not matching the correct version of the message in the update request or missing headers, missing event parameters.


Response Parameters:

The response parameters includes all the fields that have been included in the request body and the following additional parameters.


Errors Array List of errors, if any. See Errors Parameters below.

Errors Parameters:


Property Name String The name of the property that has an error.

Attempted Value String The attempted value used.

Error Code String The type of error.

Error Message String The description of the error.

Example 1:

{

"errors": []

}

Example 2:

{

"errors": [

{

"propertyName": "EventVersion",

"attemptedValue": "2",

"errorCode": "InvalidValue",

"errorMessage": "You are not amending the most recent version for this event. Please get the latest version and try again."

}

]

}

netting event - fishserve event.pdf · parameter required data type description is net lost...

Documents