openapi: 3.0.2
info:
  version: 1.0.0
  title: Court District API
  description: LA County court district public information
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:
  /CourtDistrict/{judicial_district}/{court_type}:
    get:
      summary: Get court district by primary key
      description: Returns an arry of 0 (no match) or 1(match) court districts  
      parameters:
        - name: judicial_district
          in: path
          description: >-
            The name of the district.
          required: true
          schema:
            type: string
          example: "CEN"
        - name: court_type
          in: path
          description: >-
            The court type of the district.
          required: true
          schema:
            type: string
          example: "M"
        - $ref: "#/components/parameters/x-api-key"
      responses:
        '200':
          $ref: "#/components/responses/CourtDistrictList"
  /CourtDistrict/{judicial_district}:
    get:
      summary: Get court districts
      description: |
        Returns court districts that match judicial_district code.
      parameters:
        - name: judicial_district
          in: path
          description: >-
            The name of the district.
          required: true
          schema:
            type: string
          example: "CEN"
        - $ref: "#/components/parameters/x-api-key"
      responses:
        '200':
          $ref: "#/components/responses/CourtDistrictList"
  /CourtDistrict:
    get:
      summary: Get all court districts
      parameters:
        - $ref: "#/components/parameters/x-api-key"
      responses:
        '200':
          $ref: "#/components/responses/CourtDistrictList"
    post:
      summary: Create new court district record
      parameters:
        - $ref: "#/components/parameters/x-api-key"
      requestBody:
        description: Court district without ID, which will be auto-generated
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewCourtDistrict"
      responses:
        '200':
          description: ID of created court district record
          content:
            application/json:
              schema:
                type: object
                properties:
                  insertId:
                    type: integer
              example:
                insertId: 132
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "403":
          $ref: "#/components/responses/Unauthorized"
      security:
        - cjis-auth: []
    patch:
      summary: Update existing court district record
      parameters:
        - $ref: "#/components/parameters/x-api-key"
      requestBody:
        description: Court district properties with unique ID
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateCourtDistrict"
            examples:
              prob1:
                summary: Change probation service office
                value:
                  court_type: "M"
                  judicial_district: "ING"
                  prob_svce_office: "XYZ"
              expire1:
                summary: Set an expiration date
                value:
                  court_type: "M"
                  judicial_district: "ING"
                  exp_date: "2022-03-15"
              expire2:
                summary: Clear an expiration date
                value:
                  court_type: "M"
                  judicial_district: "ING"
                  exp_date: null
      responses:
        "200":
          description: Number of updated records
          content:
            application/json:
              schema:
                type: object
                properties:
                  changedRows:
                    type: integer
              example:
                changedRows: 1
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "403":
          $ref: "#/components/responses/Unauthorized"
      security:
        - cjis-auth: []
components:
  schemas:
    NewCourtDistrict:
      type: object
      required:
        - court_type
        - judicial_district
        - description
      properties:
        court_type:
          type: string
          minLength: 1
          maxLength: 1
          description: |
            Part of primary key.
            Values have the following meanings:
            * `M` - Municipal
            * `S` - Superior
            * `X` - Juvenile
            * `J` - Justice
            * `P` - Parole
          enum:
            - M
            - S
            - X
            - J
            - P
        judicial_district:
          type: string
          minLength: 1
          maxLength: 3
          description: Part of primary key.
        description:
          type: string
          minLength: 1
          maxLength: 30
        city:
          type: string
          nullable: true
          maxLength: 20
        state_code:
          type: string
          nullable: true
          maxLength: 5
        state_district_code:
          type: string
          nullable: true
          maxLength: 6
        judicial_district_name:
          type: string
          nullable: true
          maxLength: 30
        exp_date:
          type: string
          format: date
          nullable: true
          minLength: 10
          maxLength: 10
          description: Optional expiration.  Not expired if null or absent.
        prob_svc_office:
          type: string
          description: Probation service office
          nullable: true
          maxLength: 6
        case_number_prefix:
          type: string
          nullable: true
          maxLength: 1
    CourtDistrict:
      allOf:
        - type: object
          properties:
            last_updated:
              type: string
              format: date
              maxLength: 10
        - $ref: "#/components/schemas/NewCourtDistrict"
    UpdateCourtDistrict:
      type: object
      required:
        - court_type
        - judicial_district
      properties:
        court_type:
          type: string
          minLength: 1
          maxLength: 1
          description: |
            Part of the primary key.
            Values have the following meanings:
            * `M` - Municipal
            * `S` - Superior
            * `X` - Juvenile
            * `J` - Justice
            * `P` - Parole
          enum:
            - M
            - S
            - X
            - J
            - P
        judicial_district:
          type: string
          minLength: 1
          maxLength: 3
          description: Part of the primary key.
        description:
          type: string
          minLength: 1
          maxLength: 30
        city:
          type: string
          nullable: true
          maxLength: 20
        state_code:
          type: string
          nullable: true
          maxLength: 5
        state_district_code:
          type: string 
          nullable: true
          maxLength: 6
        judicial_district_name:
          type: string
          nullable: true
          maxLength: 30
        exp_date:
          type: string
          format: date
          nullable: true
          minLength: 10
          maxLength: 10
          description: Optional expiration.  Not expired if null or absent.
        prob_svc_office:
          type: string
          description: Probation service office
          nullable: true
          maxLength: 6
        case_number_prefix:
          type: string
          nullable: true
          maxLength: 1
  responses:
    CourtDistrictList:
      description: A list of court district records
      headers:
        x-amzn-RequestId:
          $ref: "#/components/headers/x-amzn-RequestId"
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/CourtDistrict"
          example:
            - court_type: S
              judicial_district: CEN
              description: CENTRAL
              city: LOS ANGELES
              state_code: 19100
              state_district_code: 190001
              judicial_district_name: CENTRAL
              prob_svc_office: CAI
              case_number_prefix: B
        text/csv:
          schema:
            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: User not authorized
    InvalidRequest:
      description: Missing required 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
  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