emnify Locate Endpoint

arazzo: 1.0.1
info:
  title: emnify Locate Endpoint
  summary: Authenticate, confirm the endpoint, then retrieve its cell-tower-based location.
  description: >-
    A location-lookup flow. The workflow authenticates, confirms the endpoint
    exists, and then requests connectivity information derived from the cell
    tower the device is connected to. emnify validates the request and queries
    the network operator, so this call returns HTTP 200 whenever the request is
    executed even if the network returns no useful location data. Every step
    spells out its request inline, including the Bearer Authorization header
    threaded from the authenticate step.
  version: 1.0.0
sourceDescriptions:
- name: subpackageAuthenticationApi
  url: ../openapi/emnify-subpackage-authentication-api-openapi.yml
  type: openapi
- name: subpackageEndpointApi
  url: ../openapi/emnify-subpackage-endpoint-api-openapi.yml
  type: openapi
workflows:
- workflowId: locate-endpoint
  summary: Retrieve cell-tower-based location information for an endpoint.
  description: >-
    Authenticates, confirms the endpoint, and retrieves its connectivity
    information including network location.
  inputs:
    type: object
    required:
    - applicationToken
    - endpointId
    properties:
      applicationToken:
        type: string
        description: emnify application token used to obtain an auth_token.
      endpointId:
        type: string
        description: The ID of the endpoint to locate.
  steps:
  - stepId: authenticate
    description: Exchange the application token for an auth_token used as a Bearer token.
    operationId: authenticate
    requestBody:
      contentType: application/json
      payload:
        application_token: $inputs.applicationToken
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      authToken: $response.body#/auth_token
  - stepId: getEndpoint
    description: Confirm the endpoint exists before requesting its location.
    operationId: endpoint-by-id-get
    parameters:
    - name: endpoint_id
      in: path
      value: $inputs.endpointId
    - name: Authorization
      in: header
      value: Bearer $steps.authenticate.outputs.authToken
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      endpointName: $response.body#/name
  - stepId: getConnectivityInfo
    description: Retrieve cell-tower-based connectivity and location information for the endpoint.
    operationId: get-connectivity-info-by-endpoint-id
    parameters:
    - name: endpoint_id
      in: path
      value: $inputs.endpointId
    - name: Authorization
      in: header
      value: Bearer $steps.authenticate.outputs.authToken
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      connectivityInfo: $response.body
  outputs:
    endpointName: $steps.getEndpoint.outputs.endpointName
    connectivityInfo: $steps.getConnectivityInfo.outputs.connectivityInfo