Loading

Creating a Client and Its Actions

A client holds the connection; actions hold the calls. Configure in that order.

Where to find it

Architect Panel → Integration & Connections:

  • API Clients — clients and their actions

Architect Panel → Configuration:

  • Site Settings — outbound call logging, for commissioning

The client

Give it a name that identifies the external system, the host it calls, the protocol, and its authentication details. Everything beneath inherits these.

The actions

Each action is one operation:

  • A name — what it does, in your language rather than theirs.
  • A path, relative to the client's host.
  • An HTTP method — GET, POST, PUT, DELETE or PATCH.
  • A request body where the method takes one.

Name actions for what they achieve

"Book a collection", not "POST /v2/consignments". The path is already recorded in the action; the name is for the person deciding which action to call two years from now, who does not know the supplier's URL scheme.

Work from their documentation, and a real response

Build the action from the supplier's specification, then call it once and look at what actually comes back. Documentation describes the intended shape; the response tells you the real one, and they differ often enough that assuming is a poor bet.

Use their test environment

Most suppliers have one. Commission there, because a mistake against a live API is somebody else's real system — a test booking that becomes a real collection, a duplicate submission somebody has to unpick at their end.

Where there is no test environment, be correspondingly careful with the first live call and pick an operation that is easy to reverse.

Turn logging on to commission, and off afterwards

Outbound logging captures the full request and response, which is exactly what you need while getting an action right and exactly what you should not accumulate afterwards. See the logging article — it is the more important half of this.

Test the failure path

Call the action with something that will be rejected and see what happens. Most commissioning proves only the happy path, and the failure path is the one your support team will actually meet.

Keep secrets out of action definitions

Authentication belongs on the client, where it is handled as a credential. A token pasted into an action's path or body is a credential in a place nobody thinks to rotate.

Record what you built

Note which supplier, which environment, who owns the credential and where their documentation lives. Outbound integrations are consulted rarely and always urgently, and the person doing it is often not the person who built it.

Worked example

A team configures a client against a supplier's sandbox, builds three actions, and turns on outbound logging. The booking action fails until the logged response shows the supplier expects a date format their documentation did not mention. It is corrected, the failure path is tested with a deliberately invalid postcode, logging is turned off, and the client is repointed at production.

Recommendations

  • Commission against a test environment.
  • Build from a real response, not only the documentation.
  • Name actions for what they achieve.
  • Keep credentials on the client, never in an action.