Skip to main content
View as Markdown

Request metadata

The optional request_meta object carries controls for one API request. It is separate from the resource you are creating or changing. Use it to supply a stable idempotency key or to ask a supported endpoint for a smaller response.

Prerequisites

  • Authenticate your API requests.
  • Check the endpoint's request parameters to confirm that it accepts request metadata.
  • Read Idempotent requests before implementing retries for a write operation.
  • Read the endpoint's response properties before selecting a response shape.

Shape and SDK naming

The JSON wire name is request_meta. SDKs expose typed request-metadata, response, and property-selection objects using the selected language's naming conventions.

TypeScript SDK requestCreateOrderRequestv14.1.1
  • Name
    idempotencyKey
    Type
    string
    Description

    Optional stable key for safely repeating the same logical write. Supply it here or in the Idempotency-Key request header. If you send both, their values must match.

  • responseRequestResponseClick or tap to expand

    Optional preferences for the successful response. Its projection maps endpoint-defined response resource names to one typed pick or omit selection.

An idempotency key must be a non-empty string no longer than 255 characters. Reuse the same key only when repeating the same operation with the same request payload. A changed payload represents a different operation and must use a new key.

Select the response shape

Use response.projection when your integration needs only part of a successful response. The projection is a map keyed by response resource name. For each resource, supply exactly one non-empty selection:

  • pick includes only the listed property paths. Inttegro keeps the ancestors needed to contain a selected property. Picking a parent property includes its public subtree.
  • omit removes the listed property paths and their descendants.

Resources that are not present in the projection keep their complete caller-visible representation. The endpoint validates resource names and property paths against its public response contract. An unknown or unavailable resource or path returns invalid_response_projection.

The following order-creation fragment asks for only the order ID, status, and customer name, while omitting the payment's latest error:

Request metadata with a response projection

{
  requestMeta: {
    response: {
      projection: {
        order: {
          pick: [
            "id",
            "status",
            "customer.name",
          ],
        },
        payment: {
          omit: [
            "latest_error",
          ],
        },
      },
    },
  },
}

Resource names and property-path strings are API JSON identifiers. Keep them in their documented wire form, such as customer.name and latest_error, even when the selected SDK uses another naming convention for ordinary object properties.

Include metadata only when documented

Request metadata is not a universal parameter. Some endpoint request types expose it, while others do not. The endpoint reference is authoritative: if request_meta is absent from its request parameters, omit the object rather than assuming support from another endpoint.

For example, Create an order accepts an idempotency key inside request_meta. The following request fragment follows the selected SDK's naming and type conventions:

Request metadata for order creation

{
  requestMeta: {
    idempotencyKey: "checkout_cart_123",
  },
}

You may instead send checkout_cart_123 in the Idempotency-Key header.

Request metadata is not custom data

Use request metadata only for the request controls documented by the endpoint. Use custom data for small application-specific string values that belong with a resource. Do not place arbitrary business data, secrets, or undocumented properties inside request_meta.

  • Idempotent requests - Choose stable keys and retry a supported operation safely.
  • Create an order - See request metadata in an endpoint contract.
  • Error codes - Handle invalid_response_projection and other request errors.
  • Custom data - Attach supported application-specific string values to resources.