service-api.yaml

openapi: 3.0.0
servers:
  - url: '{scheme}://{hostname}'
    variables:
      scheme:
        default: http
        description: the URL scheme
      hostname:
        default: localhost:8080
        description: the hostname of your server
info:
  title: IFTTT Service API
  version: 1.0.0
  description: An API that an IFTTT service must implement.
paths:
  /ifttt/v1/status:
    get:
      summary: Service status
      operationId: getStatus
      security:
        - serviceAuth: [ ]
      responses:
        '200':
          description: successful operation
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /ifttt/v1/test/setup:
    post:
      summary: Sets up and returns test data
      operationId: setupTest
      security:
        - serviceAuth: [ ]
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestSetupResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /ifttt/v1/user/info:
    get:
      summary: Returns user info
      operationId: getUserInfo
      security:
        - serviceAuth: [ ]
        - userAuth: [ ]
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfoResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /ifttt/v1/triggers/{stepSlug}:
    post:
      summary: Checks trigger
      operationId: getTriggerEvents
      security:
        - serviceAuth: [ ]
        - userAuth: [ ]
      parameters:
        - name: stepSlug
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriggerCheckRequest'
      responses:
        '200':
          description: Trigger events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerCheckResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /ifttt/v1/triggers/{stepSlug}/fields/{stepFieldSlug}/options:
    post:
      summary: Get trigger field options
      operationId: getTriggerFieldOptions
      security:
        - serviceAuth: [ ]
        - userAuth: [ ]
      parameters:
        - name: stepSlug
          in: path
          required: true
          schema:
            type: string
        - name: stepFieldSlug
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Trigger field options
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StepFieldOptionsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /ifttt/v1/triggers/{stepSlug}/fields/{stepFieldSlug}/validate:
    post:
      summary: Validate a trigger field
      operationId: validateTriggerField
      security:
        - serviceAuth: [ ]
        - userAuth: [ ]
      parameters:
        - name: stepSlug
          in: path
          required: true
          schema:
            type: string
        - name: stepFieldSlug
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateFieldRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateFieldResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /ifttt/v1/triggers/{stepSlug}/fields/validate:
    post:
      summary: Validate trigger fields
      operationId: validateTriggerFields
      security:
        - serviceAuth: [ ]
        - userAuth: [ ]
      parameters:
        - name: stepSlug
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateFieldsRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateFieldsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /ifttt/v1/actions/{stepSlug}:
    post:
      summary: Run action
      operationId: runAction
      security:
        - serviceAuth: [ ]
        - userAuth: [ ]
      parameters:
        - name: stepSlug
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionRunRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActionRunResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /ifttt/v1/actions/{stepSlug}/fields/{stepFieldSlug}/options:
    post:
      summary: Get action field options
      operationId: getActionFieldOptions
      security:
        - serviceAuth: [ ]
        - userAuth: [ ]
      parameters:
        - name: stepSlug
          in: path
          required: true
          schema:
            type: string
        - name: stepFieldSlug
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Action field options
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StepFieldOptionsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /ifttt/v1/queries/{stepSlug}:
    post:
      summary: Perform query
      operationId: performQuery
      security:
        - serviceAuth: [ ]
        - userAuth: [ ]
      parameters:
        - name: stepSlug
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryPerformRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryPerformResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /ifttt/v1/queries/{stepSlug}/fields/{stepFieldSlug}/options:
    post:
      summary: Get query field options
      operationId: getQueryFieldOptions
      security:
        - serviceAuth: [ ]
        - userAuth: [ ]
      parameters:
        - name: stepSlug
          in: path
          required: true
          schema:
            type: string
        - name: stepFieldSlug
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Query field options
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StepFieldOptionsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    TestSetupResponse:
      title: Test setup response
      description: Test data
      type: object
      required: [ data ]
      properties:
        data:
          type: object
          required: [ samples ]
          properties:
            accessToken:
              type: string
            samples:
              type: object
              properties:
                triggers:
                  type: object
                triggerFieldValidations:
                  type: object
                actions:
                  type: object
                actionRecordSkipping:
                  type: object
    UserInfoResponse:
      title: User info response
      description: Information about a user
      type: object
      required: [ data ]
      properties:
        data:
          $ref: '#/components/schemas/UserInfo'
    UserInfo:
      description: User information.
      type: object
      required: [ id, name ]
      properties:
        id:
          type: string
          description: An unchangeable, permanent identifier to uniquely identify the resource owner within your service. We advise against using emails, usernames, or phone numbers for this as the identifier cannot be changed.
        name:
          type: string
          description: Full name, username, email, or other identification to display to the user.
        url:
          type: string
          description: URL to user’s dashboard or configuration page on your service’s website.
    ErrorResponse:
      title: Error response
      description: An error response.
      type: object
      required: [ errors ]
      properties:
        errors:
          type: array
          items:
            type: object
            required: [ message ]
            properties:
              message:
                type: string
              status:
                type: string
                enum: [ SKIP ]
    TriggerCheckRequest:
      description: Trigger check request.
      type: object
      required: [ trigger_identity, triggerFields, user ]
      properties:
        trigger_identity:
          type: string
          description: A unique identifier for this set of trigger fields for a given Applet.
        triggerFields:
          $ref: '#/components/schemas/StepFields'
        user:
          description: Information about the IFTTT user related to this request.
          $ref: '#/components/schemas/User'
        limit:
          $ref: '#/components/schemas/Limit'
        ifttt_source:
          description: Information about the personal Applet on IFTTT that triggered this request
          $ref: '#/components/schemas/IftttSource'
    Location:
      description: Location value.
      type: object
      required: [ lat, lng ]
      properties:
        lat:
          type: number
        lng:
          type: number
        radius:
          type: number
        address:
          type: string
        description:
          type: string
        zoom:
          type: number
    TriggerCheckResponse:
      description: Trigger check response.
      type: object
      required: [ data ]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TriggerEvent'
    TriggerEvent:
      description: Trigger event.
      type: object
      required: [ meta ]
      properties:
        meta:
          type: object
          required: [ id, timestamp ]
          properties:
            id:
              type: string
            timestamp:
              type: integer
              format: int32
      additionalProperties: # Ingredients
        type: object
    StepFieldOptionsResponse:
      description: Step field options response.
      type: object
      required: [ data ]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/FieldOption'
    FieldOption:
      description: Field option.
      type: object
      required: [ label ]
      properties:
        label:
          type: string
        value:
          type: string
        values:
          type: array
          items:
            $ref: '#/components/schemas/FieldSubOption'
    FieldSubOption:
      description: Field option.
      type: object
      required: [ label, value ]
      properties:
        label:
          type: string
        value:
          type: string
    ValidateFieldRequest:
      description: Validate field request.
      type: object
      required: [ value ]
      properties:
        value:
          type: string
    ValidateFieldResponse:
      description: Validate field response.
      type: object
      required: [ data ]
      properties:
        data:
          $ref: '#/components/schemas/ValidationResult'
    ValidateFieldsRequest:
      description: Validate fields request.
      type: object
      required: [ values ]
      properties:
        values:
          type: object
          additionalProperties:
            type: string
    ValidateFieldsResponse:
      description: Validate fields response.
      type: object
      required: [ data ]
      properties:
        data:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ValidationResult'
    ValidationResult:
      description: Validation result.
      type: object
      required: [ valid ]
      properties:
        valid:
          type: boolean
        message:
          type: string
    ActionRunRequest:
      description: Action run request.
      type: object
      required: [ actionFields, user ]
      properties:
        actionFields:
          $ref: '#/components/schemas/StepFields'
        user:
          description: Information about the IFTTT user related to this request.
          $ref: '#/components/schemas/User'
        ifttt_source:
          description: Information about the personal Applet on IFTTT that triggered this request
          $ref: '#/components/schemas/IftttSource'
    ActionRunResponse:
      description: Action run response.
      type: object
      required: [ data ]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ActionEvent'
    ActionEvent:
      description: Action event.
      type: object
      required: [ id ]
      properties:
        id:
          type: string
          description: A database ID, timestamp, URL, or other value which uniquely identifies the resource created or modified during action execution.
        url:
          type: string
          description: URL to the created or modified resource.
    QueryPerformRequest:
      description: A perform query request.
      type: object
      required: [ queryFields, user ]
      properties:
        queryFields:
          $ref: '#/components/schemas/QueryFields'
        user:
          description: Information about the IFTTT user related to this request.
          $ref: '#/components/schemas/User'
        limit:
          $ref: '#/components/schemas/Limit'
        ifttt_source:
          description: Information about the personal Applet on IFTTT that triggered this request
          $ref: '#/components/schemas/IftttSource'
        cursor:
          type: string
          description: Reference to the next page of the resutl set.
        include:
          type: array
          description: Ingredient slugs to resolve and include in the query response.
          items:
            type: string
    QueryPerformResponse:
      description: A query perform response.
      type: object
      required: [ data ]
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/QueryRow'
        cursor:
          type: string
    QueryRow:
      description: A query row.
      type: object
      additionalProperties: # Ingredients
        type: object
    QuerySubresult:
      description: A nested query result.
      type: object
      required: [ queryFields ]
      properties:
        queryFields:
          $ref: '#/components/schemas/QueryFields'
        data:
          type: array
          items:
            $ref: '#/components/schemas/QueryRow'
        cursor:
          type: string
    StepFields:
      type: object
      description: Map of step field slugs to values.
      additionalProperties:
        type: object
        description: Values can be either a string or a Location
    QueryFields:
      type: object
      description: Map of query field slugs to values.
      additionalProperties:
        type: object
        description: Values can be either a string, Location, or QuerySubresult
    Limit:
      type: integer
      description: Maximum number of items to be returned.
      format: int32
      default: 50
      minimum: 0
    IftttSource:
      description: Information about the personal Applet on IFTTT that triggered this request.
      type: object
      required: [ id, url ]
      properties:
        id:
          type: string
          description: Applet id
        url:
          type: string
          description: Applet URL
    User:
      description: Information about the IFTTT user related to this request.
      type: object
      required: [ timezone ]
      properties:
        timezone:
          type: string
  responses:
    BadRequest:
      description: There was something wrong with incoming data
      content:
        'application/json':
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Invalid OAuth2 token
      content:
        'application/json':
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: URL doesn't exist
      content:
        'application/json':
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal server error
      content:
        'application/json':
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServiceUnavailable:
      description: Service is not ready to handle the request, try again later
      content:
        'application/json':
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    serviceAuth:
      type: apiKey
      in: header
      name: IFTTT-Service-Key
    userAuth:
      type: http
      scheme: bearer
      bearerFormat: OAuth2 Access Token