openapi: 3.0.2
info:
  version: 1.0.0
  title: Court Department API
  description: LA County court department/division 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:
  /CourtDepartment/{judicial_district}/{department}/{court_type}:
    get:
      summary: Get court department by primary key
      description: Returns an array of 0 (no match) or 1 (single match) court department.
      parameters:
        - name: judicial_district
          in: path
          required: true
          schema:
            type: string
          example: "NO"
        - name: department
          in: path
          required: true
          schema:
            type: string
          example: "P"
        - name: court_type
          in: path
          required: true
          schema:
            type: string
          example: "S"
        - $ref: "#/components/parameters/x-api-key"
      responses:
        "200":
          $ref: "#/components/responses/CourtDepartmentList"
  /CourtDepartment/{judicial_district}/{department}:
    get:
      summary: Get court departments
      description: |
        Return court departments matching a judicial
        district and department name.
      parameters:
        - name: judicial_district
          in: path
          required: true
          schema:
            type: string
          example: "NO"
        - name: department
          in: path
          required: true
          schema:
            type: string
          example: "P"
        - $ref: "#/components/parameters/x-api-key"
      responses:
        "200":
          $ref: "#/components/responses/CourtDepartmentList"
  /CourtDepartment/{judicial_district}:
    get:
      summary: Get court departments
      description: Return court departments for a judicial district.
      parameters:
        - name: judicial_district
          in: path
          required: true
          schema:
            type: string
          example: "NO"
        - $ref: "#/components/parameters/x-api-key"
      responses:
        "200":
          $ref: "#/components/responses/CourtDepartmentList"
  /CourtDepartment:
    get:
      summary: Get all court departments
      parameters:
        - $ref: "#/components/parameters/x-api-key"
      responses:
        "200":
          $ref: "#/components/responses/CourtDepartmentList"
    post:
      summary: Create new court department record
      parameters:
        - $ref: "#/components/parameters/x-api-key"
      requestBody:
        description: New court department
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewCourtDepartment"
      responses:
        "200":
          description: ID of created court department record
          content:
            application/json:
              schema:
                type: object
                properties:
                  insertId:
                    type: integer
                example:
                  insertId: 1437
        "400":
          $ref: "#/components/responses/InvalidRequest"
        "403":
          $ref: "#/components/responses/Unauthorized"
      security:
        - cjis-auth: []
    patch:
      summary: Update existing court department record
      parameters:
        - $ref: "#/components/parameters/x-api-key"
      requestBody:
        description: Court department properties with unique ID
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateCourtDepartment"
            examples:
              phone1:
                summary: Change phone number
                value:
                  court_type: "S"
                  judicial_district: "NO"
                  department: "P"
                  phone: "213-123-4567"
              phone2:
                summary: Remove phone number
                value:
                  court_type: "S"
                  judicial_district: "NO"
                  department: "P"
                  phone: null
              expire1:
                summary: Set an expiration date
                value:
                  court_type: "S"
                  judicial_district: "NO"
                  department: "P"
                  exp_date: "2022-03-15"
              expire2:
                summary: Remove an expiration date
                value:
                  court_type: "S"
                  judicial_district: "NO"
                  department: "P"
                  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:
    NewCourtDepartment:
      type: object
      required:
        - court_type
        - judicial_district
        - department
        - 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.
        department:
          type: string
          minLength: 1
          maxLength: 3
          description: Part of primary key.
        description:
          type: string
          maxLength: 30
        address:
          type: string
          nullable: true
          maxLength: 37
        city:
          type: string
          nullable: true
          maxLength: 20
        state:
          type: string
          nullable: true
          minLength: 2
          maxLength: 2
        zip:
          type: string
          nullable: true
          minLength: 5
          maxLength: 10
        phone:
          type: string
          nullable: true
          pattern: '^\d{3}-\d{3}-\d{4}$'
          maxLength: 18
        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
          nullable: true
          description: Probation service office
          maxLength: 6
    CourtDepartment:
      allOf:
        - $ref: "#/components/schemas/NewCourtDepartment"
        - type: object
          properties:
            last_updated:
              type: string
              format: date
              maxLength: 10
    UpdateCourtDepartment:
      type: object
      required:
        - court_type
        - judicial_district
        - department
      properties:
        court_type:
          type: string
          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.
        department:
          type: string
          minLength: 1
          maxLength: 3
          description: Part of primary key.
        description:
          type: string
          minLength: 1
          maxLength: 30
        address:
          type: string
          nullable: true
          maxLength: 37
        city:
          type: string
          nullable: true
          maxLength: 20
        state:
          type: string
          nullable: true
          minLength: 2
          maxLength: 2
        zip:
          type: string
          nullable: true
          minLength: 5
          maxLength: 10
        phone:
          type: string
          nullable: true
          pattern: '^\d{3}-\d{3}-\d{4}$'
          minLength: 12
          maxLength: 18
        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
          nullable: true
          maxLength: 6
          description: Probation service office
  responses:
    CourtDepartmentList:
      description: A list of court department records
      headers:
        x-amzn-RequestId:
          $ref: "#/components/headers/x-amzn-RequestId"
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: "#/components/schemas/CourtDepartment"
          example:
            - court_type: S
              judicial_district: NO
              department: A05
              description: NORTH - LANCASTER
              address: 42011 4TH ST. WEST
              city: LANCASTER
              state: CA
              zip: 93534
              phone: 661-974-7200
              prob_srv_office: ESFVAV
        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