Find By ID

The findById method retrieves a single record by its unique identifier.

Configuration Example

# spec.yml
name: Collection Name
methods:
  findById:
    parametersSchema:
      type: object
      properties:
        includeRelated:
          type: boolean
          default: false
          description: Include related records

Implementation Examples

REST API Mapping Implementation (Recommended)

File: find-by-id.rest.yml

path: /contacts/{id}
method: GET
requestMapping:
  pathParameters:
    id: { $var: $.id }
  query:
    expand: |
      {
        $cond: [
          { $var: $.parameters.includeRelated },
          "relationships",
          null
        ]
      }
responseMapping:
  record: { $var: response.data }

Operation Mapping Implementation

File: find-by-id.yml

implementationType: operation-mapping
mapping:
  operationKey: getContact
  inputMapping:
    contactId: { $var: $.id }
    options:
      includeRelated: { $var: $.parameters.includeRelated }
  outputMapping:
    record: { $var: result.contact }

JavaScript Implementation

File: find-by-id.js

export default async function findById({ apiClient, id, parameters }) {
  try {
    const queryParams = {}

    if (parameters?.includeRelated) {
      queryParams.expand = "relationships"
    }

    const response = await apiClient.get(`/contacts/${id}`, {
      params: queryParams,
    })

    return {
      record: response.data,
    }
  } catch (error) {
    if (error.response?.status === 404) {
      return {
        record: null,
      }
    }
    throw error
  }
}

Input

Property	Type	Description
`id`	string	The ID of the record to retrieve
`credentials`	object	Authentication credentials
`parameters`	object	Method-specific parameters

Return Value

Property	Type	Description
`record`	object	The record in API format (before fieldsFromApi)