Upload
others
View
8
Download
0
Embed Size (px)
Citation preview
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.
Parameter Required Data Type Description
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:
Parameter Required Data Type Description
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:
Parameter Required Data Type Description
Finish Latitude Mandatory String Must provide at least 4 decimal places.
Parameter Required Data Type Description
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:
Parameter Required Data Type Description
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:
Parameter Required Data Type Description
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 Must be a whole number.
Parameter Required Data Type Description
Number Injured Mandatory if
measured_by =
count
Number Must be a whole number.
Number Dead Mandatory if
measured_by =
count
Number Must be a whole number.
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:
Parameter Data Type Description
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
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
Response Response Status:
Status Description
200 Ok Status when event has been retrieved successfully.
Status Description
404 Not Found Status when event cannot be found.
401 Unauthorised Status when the user does not have the appropriate authorisation to perform the action.
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": {
"totalLengthOfNetsMeters": 4
"minMeshSizeMm": 1.5,
"netHeight": 3,
"isNetLost": false,
"startOfHaul": "2017-05-04T11:30:00+13:00",
"method": "DN",
"targetSpeciesCode": "HOK",
"mitigationDevicesUsed": [
"STR",
"LAS"
],
"startDateTime": "2017-04-05T09:15:00+11:00",
"startLocation": {
"longitude": 174.732177, "latitude": -41.409898,
"isManual": false
},
"finishDateTime": "2017-05-04T12:30:00+13:00",
"finishLocation": {
"longitude": 174.6799,
"latitude": -41.4289,
"isManual": false
},
"isNonFishOrProtectedSpeciesCatchPresent": false,
"catches": [
{
"speciesCode": "CRA",
"greenWeightEstimateKg": 50.25,
"productState": null,
"processedWeightKg": null,
"numberOfFish": null
},
{
"speciesCode": "HOK",
"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"]
}, ],
"eventId": "5ba04c30-c81a-4618-898e-e832da93cf99",
"schemaEdition": 1,
"eventVersion": 1,
"clientNumber": "1234567",
"eventDateTime": "2017-04-05T09:15:00+11:00",
"vesselNumber": "1",
"isVesselUsed": true,
"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
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:
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.
Parameter Required Data Type Description
Event Version Mandatory Number The version of the event that the fisher is wanting to update.
Request Body:
Example:
{
"eventHeader": {
"eventId": "5ba04c30-c81a-4618-898e-e832da93cf99",
"eventVersion" : 1,
"vesselNumber": "11149",
"isVesselUsed": true,
"notes": "None"
},
"startDateTime": "2017-04-05T09:15:00+11:00",
"method": "DN",
"targetSpeciesCode": "HOK",
"mitigationDevicesUsed": ["HOP", "DDD"],
"startLocation": {
"longitude": "174.732177",
"latitude": "-41.409898",
"isManual": false
},
"isNonFishOrProtectedSpeciesCatchPresent": 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": "SNA",
"greenWeightEstimateKg": 50.25,
},
{
"speciesCode": "HOK",
"greenWeightEstimateKg": 23.75,
}
],
}
Response Response Status:
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.
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:
Parameter Data Type Description
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."
}
]
}