openapi: 3.0.2
info:
  version: 1.1.1
  title: Charge Code API
  description: API for reading, adding, and updating CJIS charge codes
servers:
  - url: "https://api-test.codes.lacounty-isab.org/api/v1"
    description: Test environment
  - url: "https://api.codes.lacounty-isab.org/api/v1"
    description: Production environment
paths:
  '/ChargeCode/{id}':
    get:
      summary: Get charge by id 
      description: Query a single charge code by ID.
      parameters:
        - name: id
          in: path
          description: >-
            Matches the internal ID (primary key) of the charge code.
            Returns an array of zero (no match) or one (match) charge code.
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/x-api-key"
      responses:
        '200':
          $ref: "#/components/responses/ChargeCodeList"
    delete:
      summary: Delete charge by id
      description: Delete a single charge code by ID.
      parameters:
        - name: id
          in: path
          description: >-
            Matches the internal ID (primary key) of the charge code.
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/x-api-key"
      responses:
        '200':
          description: >-
            Returns number of charge codes deleted.  If charge
            code did not exist, this number will be 0.
          content:
            application/json:
              schema:
                type: object
                properties:
                  affectedRows:
                    type: integer
              example:
                affectedRows: 1
        "400":
          description: missing parameter
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              example:
                message: id URL parameter missing
        "403":
          $ref: "#/components/responses/Unauthorized"
        '500':
          $ref: "#/components/responses/DatabaseError"
      security:
        - cjis-auth: []
  '/ChargeCode/{code}/{statute}':
    get:
      summary: Get charges by code and statute
      description: Match charges with code and statutes that begin with provided value.
      parameters:
        - name: code
          in: path
          description: Matches the two character code
          required: true
          schema:
            type: string
        - name: statute
          in: path
          description: Matches the beginning of the statue.
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/x-api-key"
      responses:
        '200':
          $ref: "#/components/responses/ChargeCodeList"
  '/ChargeCode/{code}/{statute}/{level}':
    get:
      summary: Get charges by code, statute, and level
      description: Match charges with code and statutes that begin with provided value.
      parameters:
        - name: code
          in: path
          description: Matches the two character code exactly
          required: true
          schema:
            type: string
        - name: statute
          in: path
          description: Matches the beginning of the statue.
          required: true
          schema:
            type: string
        - name: level
          in: path
          description: Matches the charge level exactly
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/x-api-key"
      responses:
        '200':
          $ref: "#/components/responses/ChargeCodeList"
  '/ChargeCode':
    get:
      summary: Get all charge codes
      parameters:
        - $ref: "#/components/parameters/x-api-key"
      responses:
        "200":
          $ref: "#/components/responses/ChargeCodeList"
    post:
      summary: Create a charge code
      description: Adds a new CJIS charge code
      parameters:
        - $ref: "#/components/parameters/x-api-key"
      requestBody:
        description: New charge code without id
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewChargeCode"
      responses:
        "200":
          description: ID of created charge code
          content:
            application/json:
              schema:
                type: object
                properties:
                  insertId:
                    type: integer
              example:
                insertId: 4325
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "403":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/DatabaseError"
      security:
        - cjis-auth: []
    patch:
      summary: Update a charge code
      description: Update an existing charge code
      parameters:
        - $ref: "#/components/parameters/x-api-key"
      requestBody:
        description: Updated charge code with id
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateChargeCode"
      responses:
        '200':
          description: 200 number of changed rows
          content:
            application/json:
              schema:
                type: object
                properties:
                  changedRows:
                    type: integer
              example:
                changedRows: 1
        '400':
          $ref: "#/components/responses/InvalidRequest"
        '403':
          $ref: "#/components/responses/Unauthorized"
        '500':
          $ref: "#/components/responses/DatabaseError"
      security:
        -  cjis-auth: []

components:
  schemas:
    NewChargeCode:
      type: object
      required:
        - code
        - statute
        - offense_level
        - full_description
        - template_id
      properties:
        template_id:
          type: integer
          format: int32
          minimum: 0
          description: Used as primary key by original ADABAS `32757` table
        code:
          type: string
          maxLength: 2
        statute:
          type: string
          maxLength: 18
        literal_id:
          type: string
          maxLength: 3
          description: >-
             Three-character description of specifics associated with
             the same charge; e.g. `COC` for Cocaine, 
             `PCP` for Phencyclidine
        degree:
          type: string
          maxLength: 1
          description: >-
            Identifies the degree of a specific charge.
            There are only two types of degree, `1` and `2`.  Only
            associated with three charges - burglary, robbery and murder.  
        offense_level:
          type: string
          maxLength: 1
          description: >-
            Identifies `F` - felony, `M` - misdemeanor, `I` - infraction,
            `O` - other, `J` - juvenile
          enum:
            - F
            - M
            - I
            - O
            - J
        full_description:
          type: string
          maxLength: 60
        short_description:
          type: string
          maxLength: 25
        classification_code:
          type: string
          maxLength: 2
          description: >-
            Identifies type of charge; e.g. `HO` - Homicide, `RO` - Robbery.
            Originally created based on BCS code groups.
        bcs_class_code:
          type: string
          minLength: 3
          maxLength: 3
          description: >-
            Three-digit BCS code assigned by the state to group charges by type
            of offense.  Must be three digits; left-pad with zeros if needed.
        reduce_flag:
          type: string
          maxLength: 1
          description: >-
            Whether a felony charge is reducible to a misdemeanor.
          enum:
            - Y
            - N
        violent_flag:
          type: string
          maxLength: 1
          description: >-
            Whether charge is classified as a violent offense.
          enum:
            - Y
            - N
        register_flag:
          type: string
          maxLength: 1
          description: >-
            Whether charge requires subject to register.  Three types of
            registration are arson, narcotics and sex.  `C` was later added
            for conditional registration.
          enum:
            - Y
            - N
            - C
        destruct_flag:
          type: string
          maxLength: 1
          description: >-
            Whether HS code violations require an agency to destroy records
            after a certain date.  Data comes from APS.
          enum:
            - Y
            - N
        reporting_district:
          type: string
          maxLength: 2
          description: >-
            Abbreviaton of state agency receiving reportable data.  Data for
            this field originally obtained from MCI.
        bail_amount:
          type: string
          maxLength: 9
          description: >-
            Originally obtained from bail schedules developed by Municipal
            and Superior courts.
        bcs_hierarchy:
          type: integer
          maxLength: 6
          description: >-
            Originally obtained from BCS code listing and pertains to the 
            seriousness of the offense.  Lower numbers are more serious.
        eff_date:
          type: string
          maxLength: 10
          description: Effective date
        exp_date:
          type: string
          maxLength: 10
          description: Expiration date; often used to designate a charge as invalid.
        reason:
          type: string
          maxLength: 40
          description: Reason for expiring a charge
        state_cjis_code:
          type: string
          maxLength: 7
          description: Requested by CCHRS in 2002
        custody_code:
          type: string
          maxLength: 1
          description: Requested by APS in 1991
        sentence_range:
          type: string
          maxLength: 12
          description: Requested by ACTS and DIMS in 1991
    UpdateChargeCode:
      type: object
      required:
        - id 
      properties:
        id:
          type: integer
        template_id:
          type: integer
          format: int32
          minimum: 0
          description: Used as primary key by original ADABAS `32757` table
        code:
          type: string
          maxLength: 2
        statute:
          type: string
          maxLength: 18
        literal_id:
          type: string
          maxLength: 3
          description: >-
             Three-character description of specifics associated with
             the same charge; e.g. `COC` for Cocaine, 
             `PCP` for Phencyclidine
        degree:
          type: string
          maxLength: 1
          description: >-
            Identifies the degree of a specific charge.
            There are only two types of degree, `1` and `2`.  Only
            associated with three charges - burglary, robbery and murder.  
        offense_level:
          type: string
          maxLength: 1
          description: >-
            Identifies `F` - felony, `M` - misdemeanor, `I` - infraction,
            `O` - other, `J` - juvenile
          enum:
            - F
            - M
            - I
            - O
            - J
        full_description:
          type: string
          maxLength: 60
        short_description:
          type: string
          maxLength: 25
        classification_code:
          type: string
          maxLength: 2
          description: >-
            Identifies type of charge; e.g. `HO` - Homicide, `RO` - Robbery.
            Originally created based on BCS code groups.
        bcs_class_code:
          type: string
          minLength: 3
          maxLength: 3
          description: >-
            Three-digit BCS code assigned by the state to group charges by type
            of offense.  Must be three digits; left-pad with zeros if needed.
        reduce_flag:
          type: string
          maxLength: 1
          description: >-
            Whether a felony charge is reducible to a misdemeanor.
          enum:
            - Y
            - N
        violent_flag:
          type: string
          maxLength: 1
          description: >-
            Whether charge is classified as a violent offense.
          enum:
            - Y
            - N
        register_flag:
          type: string
          maxLength: 1
          description: >-
            Whether charge requires subject to register.  Three types of
            registration are arson, narcotics and sex.  `C` was later added
            for conditional registration.
          enum:
            - Y
            - N
            - C
        destruct_flag:
          type: string
          maxLength: 1
          description: >-
            Whether HS code violations require an agency to destroy records
            after a certain date.  Data comes from APS.
          enum:
            - Y
            - N
        reporting_district:
          type: string
          maxLength: 2
          description: >-
            Abbreviaton of state agency receiving reportable data.  Data for
            this field originally obtained from MCI.
        bail_amount:
          type: string
          maxLength: 9
          description: >-
            Originally obtained from bail schedules developed by Municipal
            and Superior courts.
        bcs_hierarchy:
          type: integer
          maxLength: 6
          description: >-
            Originally obtained from BCS code listing and pertains to the 
            seriousness of the offense.  Lower numbers are more serious.
        eff_date:
          type: string
          maxLength: 10
          description: Effective date
        exp_date:
          type: string
          maxLength: 10
          description: Expiration date; often used to designate a charge as invalid.
        reason:
          type: string
          maxLength: 40
          description: Reason for expiring a charge
        state_cjis_code:
          type: string
          maxLength: 7
          description: Requested by CCHRS in 2002
        custody_code:
          type: string
          maxLength: 1
          description: Requested by APS in 1991
        sentence_range:
          type: string
          maxLength: 12
          description: Requested by ACTS and DIMS in 1991
    ChargeCode:
      allOf:
        - type: object
          required:
            - id
          properties:
            id:
              type: integer
        - $ref: "#/components/schemas/NewChargeCode"
        - type: object
          properties:
            composite_key:
              type: string
              maxLength: 33
              description: |
                A concatenation of six fields used to enforce uniqueness of entries
                within ADABAS table `32757`.
                * `code` - 2 characters
                * `statute` - 18 characters
                * `literal_id` - 3 characters
                * `degree` - 1 character
                * `offense_level` - 1 character
                * `exp_date` - 8 characters
            alt_composite_key:
              type: string
              maxLength: 33
              description: Same as `alt_composite_key`
            last_updated:
              type: string
              maxLength: 10
  responses:
    ChargeCodeList:
      description: A list of charge codes
      headers:
        x-amzn-RequestId:
          $ref: "#/components/headers/x-amzn-RequestId"
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/ChargeCode"
          example:
            - id: 2309
              code: PC
              statute: 12220(A)
              literal_id: ""
              degree: ""
              offense_level: M
              full_description: POSSESS/TRANSPORT MACHINEGUN
              short_description: WEAPONS VIOLATION
              classification_code: WE
              bcs_class_code: "846"
              reduce_flag: ""
              violent_flag: ""
              eff_date: "1991-01-01"
              exp_date: "2011-12-31"
              reason: REPEALED - SEE PC32625
              template_id: 2309
        text/csv:
          schema:
            type: string
    InvalidRequest:
      description: Not authorized; return unauthorized fields
      headers:
        x-amzn-RequestId:
          $ref: "#/components/headers/x-amzn-RequestId"
        x-cjisapi-RequestId:
          $ref: "#/components/headers/x-cjisapi-RequestId"
      content:
        application/json:
          schema:
            type: array
            minLength: 1
            items:
              type: string
    Unauthorized:
      description: Not authorized; return reason
      headers:
        x-amzn-RequestId:
          $ref: "#/components/headers/x-amzn-RequestId"
        x-cjisapi-requestid:
          $ref: "#/components/headers/x-cjisapi-RequestId"
      content:
        application/json:
          schema:
            type: object
            properties:
              reason:
                type: string
            example:
              - reason: Unauthorized fields
    DatabaseError:
      description: Server error
      headers:
        x-amzn-RequestId:
          $ref: "#/components/headers/x-amzn-RequestId"
        x-cjisapi-RequestId:
          $ref: "#/components/headers/x-cjisapi-RequestId"
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: integer
              errno:
                type: integer
              sqlMessage:
                type: string
  parameters:
    x-api-key:
      name: x-api-key
      in: header
      description: API key enforced by AWS API Gateway
      schema:
        type: string
      required: true
  headers:
    x-amzn-RequestId:
      description: "Logged in AWS API Gateway CloudWatch; formatted as UUID"
      schema:
        type: string
    x-cjisapi-RequestId:
      description: Audit log reference formatted as UUID
      schema:
        type: string
  securitySchemes:
    cjis-auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
