api.yaml

openapi: 3.0.3
info:
  title: Equipment Management API
  description: This API has all the operations for equipment resource.
  version: "2.0"
servers:
  - url: https://equipmentapi.deere.com/isg
tags:
  - name: Equipment Resource
    description: |
      This resource provides the ability to retrieve equipment information
      based on the supplied query parameters.
paths:
  /equipment:
    get:
      tags:
        - Equipment Resource
      description: |
        - Retrieve all Equipment by either of the following query parameters - 
          1. Primary filters:
             - OrganizationEquipment id(s)
             - Organization id(s) 
             - SerialNumber(s) and/or OrganizationId(s)
             - Principal id(s) and/or OrganizationId(s)
          2. Supported secondary filters
              - categories
              - capableOf
              - organizationRole.type
              - archived
          3. Other parameter(s)
              - embed
        - If none of the primary parameters/filters are supplied in the request 
              - Should return all the equipment from the organizations that user has access to.
              - Should return 403, when user does has access to any organization.
      parameters:
        - $ref: '#/components/parameters/OrganizationEquipmentIds'
        - $ref: '#/components/parameters/EquipmentSerialNumbers'
        - $ref: '#/components/parameters/OrganizationIds'
        - $ref: '#/components/parameters/PrincipalIds'
        - $ref: '#/components/parameters/CapableOf'
        - $ref: '#/components/parameters/Categories'
        - $ref: '#/components/parameters/Role'
        - $ref: '#/components/parameters/Archived'
        - $ref: '#/components/parameters/EmbedForList'
        - $ref: '#/components/parameters/PageOffset'
        - $ref: '#/components/parameters/ItemLimit'
      responses:
        200:
          description: Equipment(s) found based on the query parameters and filters.
          content:
            application/json:
              schema:
                properties:
                  values:
                    type: array
                    items:
                      anyOf:
                        - $ref: 'implement.yaml'
                        - $ref: 'machine.yaml'
        400:
          description: Bad Request - No query parameters provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        403:
          description: |
            Authorization Error 
            - user/applications does not have access to api or resource
            or 
            - user does not have required permissions/BusinessActivities for the org.

  /organizations/{organizationId}/equipment:
    post:
      tags:
        - Equipment Resource
      description: |
        - Create Equipment in requested organization.
      operationId: createEquipment
      parameters:
        - $ref: '#/components/parameters/organizationId'
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - $ref: 'machine.yaml'
                - $ref: 'implement.yaml'
        required: true
      responses:
        201:
          description: Created
        202:
          description: Accepted
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        403:
          description: User is not authorized for this request.

  /equipment/{id}:
    get:
      tags:
        - Equipment Resource
      description: |
        - Get Equipment by OrganizationEquipment ID. 
      parameters:
        - $ref: '#/components/parameters/id'
        - $ref: '#/components/parameters/Embed'
      responses:
        200:
          description: Equipment found by Id or Serial Number
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: 'machine.yaml'
                  - $ref: 'implement.yaml'
        404:
          description: Equipment not found
        403:
          description: |
            Authorization Error 
            - user/applications does not have access to api or resource
            or 
            - user does not have required permissions/BusinessActivities for the org.
    put:
      tags:
        - Equipment Resource
      description: |
        - Update Equipment by OrganizationEquipment Id.
      operationId: putEquipment
      parameters:
        - $ref: '#/components/parameters/id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: 'equipment-patch.yaml'
      responses:
        200:
          description: Patch Successful
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        403:
          description: User is not authorized for this request.
    delete:
      tags:
        - Equipment Resource
      description: |
        - Delete OrganizationEquipment by OrganizationEquipment Id.
      operationId: deleteEquipment
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        200:
          description: Deleted
        400:
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        403:
          description: User is not authorized for this request.

  /equipmentMakes:
    get:
      tags:
        - Equipment Make Resource
      description: |
        - Retrieves Equipment Makes with embed
      operationId: getEquipmentMakes
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                properties:
                  links:
                    type: array
                    items:
                      $ref: "./link.yaml"
                  values:
                    type: array
                    items:
                      $ref: './equipment-make.yaml'
        403:
          description: User is not authorized
  
  /equipmentMakes/{equipmentMakeId}:
    get:
      tags:
        - Equipment Make Resource
      description: |
        - Retrieve Equipment Make by Id with embed
      operationId: getEquipmentMakesById
      parameters:
        - $ref: "#/components/parameters/EquipmentMakeId"
        - $ref: "#/components/parameters/Embed"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                properties:
                  links:
                    type: array
                    items:
                      $ref: "./link.yaml"
                  values:
                    type: array
                    items:
                      $ref: './equipment-make.yaml'
        403:
          description: User is not authorized
        404:
          description: Resource Not foundapi-makes
  
  /equipmentMakes/{equipmentMakeId}/equipmentTypes:
    get:
      tags:
        - Equipment Type Resource
      description: |
        - This operation retrieves a list of Equipment Types by makeId supplied query parameters.
      operationId: getEquipmentTypesByMakeId
      parameters:

        - $ref: '#/components/parameters/EquipmentMakeId'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                properties:
                  links:
                    type: array
                    items:
                      $ref: "./link.yaml"
                  values:
                    type: array
                    items:
                      $ref: './equipment-type.yaml'
  
  /equipmentMakes/{equipmentMakeId}/equipmentTypes/{equipmentTypeId}:
    get:
      tags:
        - Equipment Type Resource
      description: |
        - Retrieve Equipment Type by Make Id and Type Id. 
      operationId: getEquipmentType
      parameters:
        - $ref: '#/components/parameters/EquipmentMakeId'
        - $ref: '#/components/parameters/EquipmentTypeId'
        - $ref: '#/components/parameters/Embed'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: "./equipment-type.yaml"
        404:
          description: Resource Not Found.
  
  /equipmentTypes:
    get:
      tags:
        - Equipment Type Resource
      description: |
        - Retrieve all Equipment Types with embed.
      operationId: getEquipmentTypes
      parameters:
        - $ref: "#/components/parameters/EquipmentTypeName"
        - $ref: "#/components/parameters/EquipmentMakeName"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                properties:
                  links:
                    type: array
                    items:
                      $ref: "./link.yaml"
                  values:
                    type: array
                    items:
                      $ref: "./equipment-type.yaml"

  /equipmentMakes/{equipmentMakeId}/equipmentTypes/{equipmentTypeId}/equipmentModels:
    parameters:
      - $ref: '#/components/parameters/EquipmentMakeId'
      - $ref: '#/components/parameters/EquipmentTypeId'
    get:
        tags:
            - Equipment Model Resource
        description: |
          - This operation retrieves a list of Equipment Models based on makeId and typeId.
        operationId: getEquipmentModelsByMakeIdAndTypeId
        responses:
          200:
            description: OK
            content:
              application/json:
                schema:
                  properties:
                    links:
                      type: array
                      items:
                        $ref: './link.yaml'
                    values:
                      type: array
                      items:
                        $ref: './equipment-model.yaml'
          403:
            description: User is not authorized
  
  /equipmentMakes/{equipmentMakeId}/equipmentTypes/{equipmentTypeId}/equipmentModels/{equipmentModelId}:
    parameters:
      - $ref: '#/components/parameters/EquipmentMakeId'
      - $ref: '#/components/parameters/EquipmentTypeId'
      - $ref: '#/components/parameters/EquipmentModelId'
    get:
      tags:
        - Equipment Model Resource
      description: |
        - This operation retrieves a single Equipment Model based on given makeId, typeId and modelId.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: './equipment-model.yaml'
        403:
          description: User is not authorized
  
  /equipmentModels:
    get:
      tags:
        - Equipment Model Resource
      description: |
        - This operation retrieves a list of Equipment Models based on the supplied query parameters.
      operationId: getEquipmentModels
      parameters:
        - $ref: "#/components/parameters/category"
        - $ref: "#/components/parameters/PageOffset"
        - $ref: "#/components/parameters/ItemLimit"
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                properties:
                  links:
                    type: array
                    items:
                      $ref: "./link.yaml"
                  values:
                    type: array
                    items:
                      $ref: './equipment-model.yaml'



components:
  schemas:
    Error:
      type: object
      properties:
        message:
          type: string
          description: An english description of the error
          example: <parameter> was invalid because <reason>
        code:
          type: string
          description: A string constant representing the type of error
          example: 400
        field:
          type: string
          description: The name of the property or parameter deemed invalid
          example: Machine.serialNumber
        gud:
          type: string
          format: uuid
          description: A reference to this encounter of the error, for traceability and troubleshooting
          example: 9b331708-10e8-4e15-8097-a9aed7455d6d
        invalidValue:
          type: string
          description: The value that was supplied for this field in the request
          example: null
      readOnly: true
    Errors:
      type: array
      items:
        $ref: '#/components/schemas/Error'
      readOnly: true



  parameters:
    OrganizationEquipmentIds:
      name: ids
      in: query
      required: false
      description: List of OrganizationEquipment Ids (these ids are unique across all orgs)
      schema:
        type: array
        items:
          type: integer
        example: [1, 2, 3]
    EquipmentSerialNumbers:
      name: serialNumbers
      in: query
      required: false
      description: List of serial numbers of the equipment
      schema:
        type: array
        items:
          type: string
        example: ["A01775E760247", "1DW410ETHFF669067"]
    OrganizationIds:
      name: organizationIds
      in: query
      required: false
      description: List of OrganizationIds
      schema:
        type: array
        items:
          type: integer
        example: [1, 2, 3]
    PrincipalIds:
      name: principalIds
      in: query
      required: false
      description: List of PrincipalIds
      schema:
        type: array
        items:
          type: integer
        example: [1, 2, 3]
    PageOffset:
      name: pageOffset
      in: query
      required: false
      description: Refers to the page number
      schema:
        type: integer
        format: int32
        default: 0
      example: 1
    ItemLimit:
      name: itemLimit
      in: query
      required: false
      description: Refers to number of items per page
      schema:
        type: integer
        format: int32
        default: 100
        maximum: 5000
      example: 10
    id:
      name: id
      in: path
      required: true
      schema:
        type: integer
        format: int32
      example: 1111
    organizationId:
      name: organizationId
      in: path
      required: true
      schema:
        type: integer
        format: int32
      example: 1234
    EmbedForList:
      name: embed
      in: query
      required: false
      description: embed 'pairingDetails' is only supported along with 'devices' or 'equipment' embeds
      schema:
        type: string
        enum:
          - devices
          - equipment
          - icon
          - pairingDetails
    Embed:
      name: embed
      in: query
      required: false
      description: embed 'pairingDetails' is only supported along with 'devices' or 'equipment' embeds
      schema:
        type: string
        enum:
          - devices
          - equipment
          - pairingDetails
          - icon
          - offsets
          - capabilities
    Categories:
      name: categories
      in: query
      required: false
      schema:
        type: array
        items:
          type: string
        enum:
          - Machine
          - Implement
        example: [Machine, Implement | Machine | Implement]
    CapableOf:
      name: capableOf
      in: query
      required: false
      schema:
        type: string
        enum:
          - Connectivity
          - "!Connectivity"
    Role:
      name: organizationRole.type
      in: query
      required: false
      schema:
        type: string
        enum:
          - Controlling
          - NonControlling
    Archived:
      name: archived
      in: query
      required: false
      schema:
        type: boolean
    SerialNumber:
      name: serialNumber
      in: path
      required: true
      schema:
        type: string
      example: VIN1234
    EquipmentMakeId:
      name: equipmentMakeId
      in: path
      required: true
      description: ID for Equipment Make
      schema:
        type: integer
        format: int32
        example: 1111
    EquipmentTypeId:
      name: equipmentTypeId
      in: path
      required: true
      description: ID for Equipment Type
      schema:
        type: integer
        format: int32
        example: 2222
    EquipmentModelId:
      name: equipmentModelId
      in: path
      required: true
      description: ID for Equipment Model
      schema:
        type: integer
        format: int32
        example: 3333
    category:
      name: category
      in: query
      required: false
      description: List of type categories for the Equipment Model
      schema:
        type: array
        items:
          type: string
        example: ["machine", "implement"]
        enum:
          - machine
          - implement
    EquipmentTypeName:
      name: equipmentTypeName
      in: query
      required: false
      description: Name for Equipment Type
      schema:
        type: string
        example: "8285R"
    EquipmentMakeName:
      name: equipmentTypeId
      in: query
      required: false
      description: Name for Equipment Make
      schema:
        type: string
        example: "JOHN DEERE"