openapi-old-10-21-2020.yaml

---
openapi: "3.0.0"
info:
  title: "trips Api"
  description: "a service to provide unique trip identifiers, and receive trip catch (logbook and em review) submissions"
  contact:
    name: "Fram Data Team"
    url: "https://www.fisheries.noaa.gov/region/west-coast"
    email: "nmfs.nwfsc.fram.data.team@noaa.gov"
  version: "0.0.1"
tags:
- name: "Login"
  description: "api login"
- name: "Trip"
  description: "an individual trip"
- name: "Trips"
  description: "all trips"
- name: "Catch"
  description: "logbook data or em review"
paths:
  /login:
    post:
      tags:
      - "Login"
      summary: "Perform login to get JWT token"
      operationId: "postLogin"
      requestBody:
        description: "Need username and password"
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Login"
            examples:
              Basic:
                value:
                  username: "your username"
                  password: "your password"
              Encoded:
                value:
                  username: "your username"
                  passwordEnc: "your base64 encoded password"
                  applicationName: "BOATNET_OBSERVER"
        required: true
      responses:
        "200":
          description: "User Authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_200"
              example:
                token: "JWT Token"
        "401":
          description: "Authorization information is missing or invalid."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_401"
              example:
                status: 401
                message: "You have not been granted access to this application."
  /tripCatch/{tripNum}:
    get:
      tags:
      - "Catch"
      summary: "get catch for trip"
      parameters:
      - name: "tripNum"
        in: "path"
        description: "ID of desired trip catch"
        required: true
        style: "simple"
        explode: false
        schema:
          type: "string"
      responses:
        "200":
          description: "successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_200_1"
        "404":
          description: "No data found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_401"
              example:
                status: 404
                message: "Not Found"
      security:
      - bearerAuth: []
    put:
      tags:
      - "Catch"
      description: "update trip catch"
      parameters:
      - name: "tripNum"
        in: "path"
        required: true
        style: "simple"
        explode: false
        schema:
          type: "number"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TripCatch"
        required: true
      responses:
        "200":
          description: "update success"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_401"
              example:
                status: 200
                message: "catch data updated"
        "400":
          description: "Invalid Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_401"
              example:
                status: 400
                message: "Invalid Request"
      security:
      - bearerAuth: []
    post:
      tags:
      - "Catch"
      summary: "submit new catch (logbook or review)"
      parameters:
      - name: "tripNum"
        in: "path"
        description: "trip Id for catch"
        required: true
        style: "simple"
        explode: false
        schema:
          type: "string"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TripCatch"
        required: true
      responses:
        "200":
          description: "save success"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_401"
              example:
                status: 200
                message: "catch data saved"
        "400":
          description: "Invalid Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_401"
              example:
                status: 400
                message: "Invalid Request"
      security:
      - bearerAuth: []
  /trips/:
    get:
      tags:
      - "Trips"
      summary: "get all trips"
      parameters:
      - name: "vesselId"
        in: "query"
        description: "all trips for a given vessel"
        required: false
        style: "form"
        explode: true
        schema:
          type: "string"
      - name: "captain"
        in: "query"
        description: "all trips for a given captain"
        required: false
        style: "form"
        explode: true
        schema:
          type: "string"
      - name: "port"
        in: "query"
        description: "trips starting or ending in specified port"
        required: false
        style: "form"
        explode: true
        schema:
          type: "string"
      - name: "fishery"
        in: "query"
        description: "trips in a given fishery"
        required: false
        style: "form"
        explode: true
        schema:
          type: "string"
      responses:
        "200":
          description: "successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_200_2"
        "404":
          description: "No data found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_401"
              example:
                status: 404
                message: "Not Found"
      security:
      - bearerAuth: []
    post:
      tags:
      - "Trips"
      summary: "create a new trip"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewTrip"
          application/xml:
            schema:
              $ref: "#/components/schemas/NewTrip"
        required: true
      responses:
        "200":
          description: "successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_200_3"
        "400":
          description: "Invalid Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_401"
              example:
                status: 400
                message: "Invalid Request"
      security:
      - bearerAuth: []
  /trips/{tripNum}:
    get:
      tags:
      - "Trip"
      description: "get an individual trip by trip num"
      parameters:
      - name: "tripNum"
        in: "path"
        required: true
        style: "simple"
        explode: false
        schema:
          type: "number"
      responses:
        "200":
          description: "returned a valid trip"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_200_4"
        "404":
          description: "No data found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_401"
              example:
                status: 404
                message: "Not Found"
      security:
      - bearerAuth: []
    put:
      tags:
      - "Trip"
      description: "update an individual trip"
      parameters:
      - name: "tripNum"
        in: "path"
        required: true
        style: "simple"
        explode: false
        schema:
          type: "number"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Trip"
        required: true
      responses:
        "200":
          description: "successfully edited an existing trip"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Trip"
        "400":
          description: "Invalid Request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/inline_response_401"
              example:
                status: 400
                message: "Invalid Request"
      security:
      - bearerAuth: []
components:
  schemas:
    Login:
      required:
      - "username"
      type: "object"
      properties:
        username:
          type: "string"
        password:
          type: "string"
          description: "Required if passwordEnc not specified"
        passwordEnc:
          type: "string"
          description: "Required if password not specified"
        applicationName:
          type: "string"
          description: "Application name, determines which roles are returned in JWT"
          default: "BOATNET_OBSERVER"
    TripCatch:
      required:
      - "buyers"
      - "crewSize"
      - "departureDateTime"
      - "departurePortCode"
      - "departureState"
      - "fisherySector"
      - "hauls"
      - "isEFPTrip"
      - "isObserved"
      - "isSigned"
      - "permitNumber"
      - "provider"
      - "resubmission"
      - "returnDateTime"
      - "returnPortCode"
      - "returnPortState"
      - "reviewerName"
      - "skipperName"
      - "source"
      - "submissionDatetime"
      - "totalReviewTime"
      - "tripNum"
      - "vesselName"
      - "vesselNumber"
      - "year"
      type: "object"
      properties:
        tripNum:
          type: "number"
          description: "Unique 6 digit Trip id - generated by Trips API"
        source:
          type: "string"
          description: "data provider / type (should be thirdParty, logbook, or nwfsc)"
        logbookPageNumber:
          type: "number"
          description: "Page number from vessel logbook"
        fisherySector:
          type: "string"
          description: "Description of the EM fishery. Whiting, Midwater Rockfish, Fixed Gear, Bottom Trawl"
        year:
          type: "string"
          description: "Year the fishing activity took place"
        vesselName:
          type: "string"
          description: "Name of the fishing vessel"
        vesselNumber:
          type: "string"
          description: "Vessel Coast Guard or State Reg Number"
        permitNumber:
          type: "string"
          description: "Limited Entry permit number (GF0000)"
        isEFPTrip:
          type: "boolean"
          description: "Flag indicating if the trip was an EFP trip"
        isObserved:
          type: "boolean"
          description: "Flag indicating if a scientific observer was on board"
        crewSize:
          type: "number"
          description: "Total number of crew on board the vessel"
        departureDateTime:
          type: "string"
          description: "Date/Time the vessel departed port"
        departureState:
          type: "string"
          description: "State where the vessel departed for fishing activities (WA, OR, CA)"
        departurePortCode:
          type: "string"
          description: "Port code where the vessel departed. The port code is the same as the PacFIN port code"
        returnDateTime:
          type: "string"
          description: "Date/Time the vessel returned to port for offload"
        returnPortState:
          type: "string"
          description: "State where the vessel returned for fishing activities (WA, OR, CA)"
        returnPortCode:
          type: "string"
          description: "Port code where the vessel returned. The port code is the same as the PacFIN port code"
        buyers:
          type: "array"
          description: "IFQ Dealer where the vessel offloaded"
          items:
            type: "string"
        isSigned:
          type: "boolean"
          description: "Flag inidicating if the logbook was signed"
        skipperName:
          type: "string"
          description: "Name of the vessel captain"
        fishTickets:
          type: "array"
          description: "fish ticket number(s) from the deleivery"
          items:
            $ref: "#/components/schemas/FishTicket"
        comment:
          type: "string"
          description: "Notes from the logbook"
        submissionDatetime:
          type: "string"
          description: "Date the loogbook was submitted by the 3rd party provider (auto-populated)"
        resubmission:
          type: "boolean"
          description: "Flag indicating the submission of corrected data"
        provider:
          type: "string"
          description: "Name of the Third Party Provider"
        reviewerName:
          type: "string"
          description: "Name of the person who entered the logbook data"
        totalReviewTime:
          type: "string"
          description: "Time (in Minutes) to complete the review of all hauls in the database"
        hauls:
          type: "array"
          items:
            $ref: "#/components/schemas/Haul"
        createdBy:
          type: "string"
          description: "auto-populated"
        createdDate:
          type: "string"
          description: "auto-populated"
        updatedBy:
          type: "string"
          description: "auto-populated"
        updatedDate:
          type: "string"
          description: "auto-populated"
      example:
        tripNum: 100123
        source: "thirdParty"
        fisherySector: "Midwater Rockfish"
        year: "2020"
        vesselName: "Fish Master 3000"
        vesselNumber: "321456"
        permitNumber: "GF99999"
        isEFPTrip: true
        isObserved: false
        crewSize: 4
        departureDateTime: "2020-09-01T15:00:00Z"
        departureState: "WA"
        departurePortCode: "SEQ"
        returnDateTime: "2020-09-04T15:00:00Z"
        returnState: "WA"
        returnPortCode: "SEQ"
        buyers:
        - "ABC Seafood Co"
        skipperName: "Bill Wilson"
        fishTickets:
        - fishTicketNumber: "21df23f23e3"
          fishTicketDate: "2020-09-04T15:00:00Z"
        - fishTicketNumber: "bf45t45htg4"
          fishTicketDate: "2020-09-04T15:00:00Z"
        comment: "Is there any thing better in the world?"
        resubmission: false
        provider: "ABC EM Provider"
        reviewerName: "Sue Wilson"
        totalReviewTime: "180"
        hauls:
        - haulNum: 1
          deliveryDate: "2020-09-01T17:00:00Z"
          gearTypeCode: "3"
          startDateTime: "2020-09-01T17:00:00Z"
          startDepth: 40
          startLatitude: 44.245
          startLongitude: -124.945
          endDateTime: "2020-09-01T19:00:00Z"
          endDepth: 43
          endLatitude: 44.776
          endLongitude: -124.447
          codendCapacity: 3000
          isCodendLost: false
          comments: "camera was a little foggy"
          targetStrategy: "203"
          systemPerformance: 1
          catchHandlingPerformance: 1
          catch:
          - catchId: 1
            disposition: "Discarded"
            fate: "11"
            speciesCode: "614"
            weight: 320
          - catchId: 2
            disposition: "Discarded"
            fate: "11"
            speciesCode: "200"
            weight: 200
    Haul:
      required:
      - "catchHandlingPerformance"
      - "deliveryDate"
      - "endDateTime"
      - "endDepth"
      - "endLatitude"
      - "endLongitude"
      - "gearLost"
      - "gearPerSet"
      - "gearTypeCode"
      - "haulNum"
      - "startDateTime"
      - "startDepth"
      - "startLatitude"
      - "startLongitude"
      - "systemPerformance"
      type: "object"
      properties:
        haulNum:
          type: "number"
          description: "Sequential haul number generated by the database"
        deliveryDate:
          type: "string"
          description: "Date and time the vessel offloaded to a buyer"
        gearTypeCode:
          type: "string"
          description: "1 = Groundfish trawl, footrope < 8 inches (small footrope), 2 = Groundfish trawl, footrope > 8 inches (large footrope), 3 = Midwater trawl, 4 = Danish/Scottish seine (trawl), 5 = Other trawl gear, 17 = Oregon set-back flatfish net, 10 = pot, 19 = Longline (fixed), 20 = Longline (snap)"
        gearPerSet:
          type: "number"
          description: "Total number of pots or hooks set (Mandatory for FG hauls)"
        gearLost:
          type: "number"
          description: "Number of pots or hooks lost (Mandatory for FG hauls)"
        avgHooksPerSeg:
          type: "number"
          description: "Average hooks per set"
        startDateTime:
          type: "string"
          description: "Date and time the gear was set"
        startDepth:
          type: "number"
          description: "Depth of fishing gear when gear is deployed (Fathoms)"
        startLatitude:
          type: "number"
          description: "Latitude of gear deployement in decimal degrees"
        startLongitude:
          type: "number"
          description: "Longitude of gear deployement in decimal degree"
        endDateTime:
          type: "string"
          description: "Date and time the gear was set"
        endDepth:
          type: "number"
          description: "Depth of fishing gear when gear is deployed (Fathoms)"
        endLatitude:
          type: "number"
          description: "Latitude of gear deployement in decimal degrees"
        endLongitude:
          type: "number"
          description: "Longitude of gear deployement in decimal degree"
        codendCapacity:
          type: "number"
          description: "Total estimated weight the codened can hold"
        isCodendLost:
          type: "boolean"
          description: "Indicate a lost codend"
        comments:
          type: "string"
          description: "Notes pertaining to a specific haul record"
        targetStrategy:
          type: "string"
          description: "Target species or grouping"
        systemPerformance:
          type: "number"
          description: "1 = No issues, 2 = Video Gaps, 3 = Poor video quality"
        catchHandlingPerformance:
          type: "number"
          description: "1 = No issues, 2 = Issues"
        catch:
          type: "array"
          items:
            $ref: "#/components/schemas/Catch"
    Catch:
      required:
      - "catchDisposition"
      - "speciesCode"
      properties:
        catchId:
          type: "number"
          description: "Unique Catch ID"
        disposition:
          type: "string"
          description: "Retained vs Discarded"
        fate:
          type: "string"
          description: "Observer Discard Reason -- 11 Accidental, Incidental, 12  Drop-off, 13  Market, 14  Other, 15  Predation, 18  Market- At Dock,19  Utilized on board,16  Regulation, 17  Safety, 20  Survival"
        speciesCode:
          type: "string"
          description: "WCGOP species code (3 or 4 digits)"
        weight:
          type: "number"
          description: "Total estimated weight (lbs)"
        speciesCount:
          type: "number"
          description: "Number of fish for a species (Yellow Eye RF, PHLB, Species of concern...Salmon, Green Sturgeon, Eulachon). Not required for all species"
        calcWeightType:
          type: "string"
          description: "Description of how the catch was calculated (EstWeight, FromAverageWt, FromLength, CaclField)"
        length:
          type: "number"
          description: "Length (in cm) of individual fish (Pacific Halibut)"
        timeOnDeck:
          type: "number"
          description: "Time on deck (in min) specific to each Pacific Halibut"
        comments:
          type: "string"
          description: "Notes pertaining to a specific catch record"
        screenShotId:
          type: "string"
        screenShotDescription:
          type: "string"
    Trip:
      required:
      - "departureDate"
      - "returnDate"
      - "vesselId"
      type: "object"
      properties:
        tripNum:
          type: "number"
        vesselId:
          type: "string"
        vesselName:
          type: "string"
        departurePort:
          type: "string"
        returnPort:
          type: "string"
        departureDate:
          type: "string"
        returnDate:
          type: "string"
        fishery:
          type: "string"
        permits:
          type: "array"
          items:
            type: "string"
        captain:
          type: "string"
        createdBy:
          type: "string"
        createdDate:
          type: "string"
        updatedBy:
          type: "string"
        updatedDate:
          type: "string"
    FishTicket:
      type: "object"
      properties:
        fishTicketNumber:
          type: "string"
        fishTicketDate:
          type: "string"
    NewTrip:
      required:
      - "departureDate"
      - "returnDate"
      - "vesselId"
      type: "object"
      properties:
        vesselId:
          type: "string"
        vesselName:
          type: "string"
        departurePort:
          type: "string"
        returnPort:
          type: "string"
        departureDate:
          type: "string"
        returnDate:
          type: "string"
        fishery:
          type: "string"
        permits:
          type: "array"
          items:
            type: "string"
        captain:
          type: "string"
        createdBy:
          type: "string"
        createdDate:
          type: "string"
        updatedBy:
          type: "string"
        updatedDate:
          type: "string"
      example:
        vesselId: 544123
        vesselName: "Fish Master 3000"
        departurePort: "SEQ"
        returnPort: "SEQ"
        departureDate: "2020-09-1T15:00:00Z"
        returnDate: "2020-09-3T15:00:00Z"
        fishery: "EM EFP"
        permits:
        - "GF9999"
        captain: "Bill Wilson"
    inline_response_200:
      type: "object"
      properties:
        username:
          type: "string"
        token:
          type: "string"
          description: "JWT encoded token"
    inline_response_401:
      type: "object"
      properties:
        status:
          type: "integer"
          format: "int64"
        message:
          type: "string"
    inline_response_200_1:
      type: "object"
      properties:
        tripCatch:
          $ref: "#/components/schemas/TripCatch"
    inline_response_200_2:
      type: "array"
      items:
        $ref: "#/components/schemas/Trip"
    inline_response_200_3:
      type: "object"
      properties:
        tripNum:
          type: "integer"
        trip:
          type: "object"
      example:
        tripNum: 123456,
        trip:
          vesselId: 544123
          vesselName: "Fish Master 3000"
          departurePort: "SEQ"
          returnPort: "SEQ"
          departureDate: "2020-09-1T15:00:00Z"
          returnDate: "2020-09-3T15:00:00Z"
          fishery: "EM EFP"
          permits: ["GF999"]
          captain: "Bill Wilson"
    inline_response_200_4:
      type: "object"
      properties:
        vesselId:
          type: "string"
        vesselName:
          type: "string"
        startPort:
          type: "string"
  responses:
    NotFoundError:
      description: "No data found"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/inline_response_401"
          example:
            status: 404
            message: "Not Found"
    InvalidRequestError:
      description: "Invalid Request"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/inline_response_401"
          example:
            status: 400
            message: "Invalid Request"
    CatchDataSaved:
      description: "save success"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/inline_response_401"
          example:
            status: 200
            message: "catch data saved"
    CatchDataUpdated:
      description: "update success"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/inline_response_401"
          example:
            status: 200
            message: "catch data updated"
  securitySchemes:
    bearerAuth:
      type: "http"
      scheme: "bearer"
      bearerFormat: "JWT"