integration-code

Writing integration code with real API schemas

Integration code fails on details a model cannot recall: the exact field name, whether a value goes in the body or the query string, which enum the API accepts this year. One's action documentation carries all of it, so look the API up rather than writing from memory.

This is what knowledge-only mode is for. In an editor, execute_one_action is removed, so you can read every API's real schema while writing code and cannot fire a live request against production data by accident.

Before you write the call

1. find_one_actions with one requests entry per operation the feature needs, on any platforms: the platform and an intent naming the operation alone ("create a customer", "list orders since a date"). One call covers every API the feature touches.
2. Read each chosen action's documentation whole: required and optional parameters, types, enums, auth, the request shape, and the response shape. In knowledge-only mode it comes back whole, with how to call it from code; otherwise call find_one_actions again with load: [{ "action_id": "...", "full": true }] for any document that came back as a digest.
3. Write the code from that schema. Field names, casing, nesting, and types come from the documentation, not from what the API probably looks like.

If you write a request body with a field the documentation does not list, you invented it. Go back and check.

Two ways to ship the call

Through One. Keep One in the runtime and call the action through it. The user's connection handles auth, so your code holds no per-platform tokens and no refresh logic. Good when the app already has One in it or when you are integrating several platforms.

Direct to the platform. Use One's documentation as a reference and write a normal HTTP client against the vendor's API. Good when the integration is one platform deep or the runtime cannot take another dependency. You then own OAuth, token refresh, and rotation.

Say which one you are doing and why, in a sentence, before you write the file. Do not mix them in the same module.