openapi: 3.2.0
info:
  title: Street Open Maintenance Requests API
  description: Build on top of the UKs most advanced Estate Agency software.
  version: '1.0'
  contact:
    name: Street API Development Team
    url: https://street.co.uk
    email: apis@street.co.uk
servers:
- url: https://street.co.uk/open-api/v1
  description: Production.
- url: https://demo.street.co.uk/open-api/v1
  description: Testing.
security:
- your-api-token: []
tags:
- name: Maintenance Requests
  description: Maintenance Request endpoints for this API.
paths:
  /maintenance-requests:
    parameters: []
    post:
      summary: Create a new maintenance request
      tags:
      - Maintenance Requests
      responses:
        '201':
          description: Created.
          content:
            application/vnd.api+json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/MaintenanceRequest'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '406':
          $ref: '#/components/responses/406'
        '409':
          $ref: '#/components/responses/409'
        '415':
          $ref: '#/components/responses/415'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
      operationId: post-maintenance-requests
      description: This endpoint allows you to create a `maintenance request` record.
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                      - maintenance-request
                    attributes:
                      type: object
                      properties:
                        priority:
                          type: string
                          enum:
                          - low
                          - medium
                          - high
                          - urgent
                          - emergency
                        summary:
                          type: string
                        description:
                          type: string
                        reported_by:
                          type: string
                          enum:
                          - tenant
                          - landlord
                          - agent
                          - contractor
                        reported_at:
                          type: string
                          format: date-time
                    relationships:
                      type: object
                      properties:
                        property:
                          type: object
                          required:
                          - data
                          properties:
                            data:
                              oneOf:
                              - type: string
                                format: uuid
                                description: Legacy format - direct UUID string
                                deprecated: true
                              - type: object
                                required:
                                - type
                                - id
                                properties:
                                  type:
                                    type: string
                                    enum:
                                    - property
                                  id:
                                    type: string
                                    format: uuid
                                description: JSON:API format
components:
  schemas:
    jsonApiError:
      title: JSON:API Error Object
      description: A JSON:API object representing a single error.
      type: object
      properties:
        title:
          type: string
        detail:
          type: string
        code:
          type: string
        source:
          type: object
          description: An object containing references to the primary source of the error.
          properties:
            pointer:
              type: string
              description: A JSON Pointer to the value in the request document that caused the error.
            parameter:
              type: string
              description: A string indicating which URI query parameter caused the error.
      required:
      - title
      examples:
      - title: 401 Unauthorized
        detail: The requester is not authorized to access the resource.
        code: '401'
    Link:
      title: Link
      oneOf:
      - description: a string containing the link's URL
        type: string
        format: uri-reference
      - type: object
        required:
        - href
        properties:
          href:
            description: a string containing the link's URL
            type: string
            format: uri-reference
          meta:
            $ref: '#/components/schemas/Meta'
    RelationshipSingular:
      title: Relationship Singular
      description: Inheritable schema for 1:1 relationships. Data may be null if the relationship is empty.
      type: object
      properties:
        data:
          oneOf:
          - type: object
            properties:
              type:
                type: string
              id:
                type: string
                format: uuid
                example: a827a3ae-4c74-4c32-8b42-42248d4010d3
            required:
            - type
            - id
          - type: 'null'
        links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/Link'
            related:
              $ref: '#/components/schemas/Link'
    BaseModel:
      title: Base Model
      type: object
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
        attributes:
          type: object
        relationships:
          type: object
    Meta:
      title: Meta Information
      description: The server's implementation.
      type: object
    jsonApiErrorResponseBody:
      title: JSON:API Error Response Body
      description: Response body for JSON:API errors, containing an array of `errors` in place of the `data` property provided in JSON:API success responses. Used for non-400/500 error codes where only a single error is expected.
      type: object
      properties:
        meta:
          type: object
        source:
          type: object
          description: The primary source of the conflict for 409 responses.
          properties:
            pointer:
              type: string
              description: JSON Pointer to the conflicting request value.
            parameter:
              type: string
              description: URI parameter related to the conflict.
        errors:
          description: An array of error objects providing additional information about problems encountered while processing the request.
          type: array
          maxItems: 1
          items:
            $ref: '#/components/schemas/jsonApiError'
      required:
      - errors
    jsonApiMultiErrorResponseBody:
      title: JSON:API Multi-Error Response Body
      description: Response body for JSON:API errors that may contain multiple error objects (400 Bad Request and 500 Internal Server Error).
      type: object
      properties:
        meta:
          type: object
        errors:
          description: An array of error objects providing additional information about problems encountered while processing the request.
          type: array
          items:
            $ref: '#/components/schemas/jsonApiError'
      required:
      - errors
    MaintenanceRequest:
      title: Maintenance Request
      allOf:
      - $ref: '#/components/schemas/BaseModel'
      - type: object
        properties:
          type:
            type: string
            enum:
            - maintenance-request
          attributes:
            $ref: '#/components/schemas/MaintenanceRequestAttributes'
          relationships:
            type: object
            properties:
              property:
                allOf:
                - $ref: '#/components/schemas/RelationshipSingular'
                - type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          enum:
                          - property
    MaintenanceRequestAttributes:
      title: Maintenance Request (attributes)
      type: object
      properties:
        summary:
          type: string
        description:
          type: string
        priority:
          type: string
          enum:
          - Low
          - Medium
          - High
          - Urgent
          - Emergency
        reported_at:
          type: string
          format: date-time
  responses:
    '403':
      description: The HTTP 403 Forbidden response status code indicates that the server understands the request but refuses to authorize it.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiErrorResponseBody'
    '406':
      description: The HTTP 406 Not Acceptable client error response code indicates that the server cannot produce a response matching the list of acceptable values defined in the request's proactive content negotiation headers, and that the server is unwilling to supply a default representation.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiErrorResponseBody'
    '401':
      description: The HTTP 401 Unauthorized response status code indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiErrorResponseBody'
    '500':
      description: The HTTP 500 Internal Server Error server error response code indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiMultiErrorResponseBody'
    '409':
      description: The HTTP 409 Conflict response status code indicates a request conflict with the current state of the target resource.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiErrorResponseBody'
    '422':
      description: The 422 Unprocessable Content response status code indicates that the server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiMultiErrorResponseBody'
    '415':
      description: The HTTP 415 Unsupported Media Type client error response code indicates that the server refuses to accept the request because the payload format is in an unsupported format.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiErrorResponseBody'
    '400':
      description: The HTTP 400 Bad Request response status code indicates that the server cannot or will not process the request due to something that is perceived to be a client error.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiMultiErrorResponseBody'
  securitySchemes:
    your-api-token:
      type: http
      scheme: bearer
x-ext-urls: {}