Start with an operation
A connector should answer a concrete question: what can someone do with this service? Finding nearby stores and reading a menu are separate operations, even if they use the same provider.
Each operation needs a name, documented inputs, a response contract, and a statement of whether it reads or changes data. A captured endpoint alone does not supply that contract.
Make inputs explicit
A nearby-store lookup takes a location. A menu lookup takes a store identifier. Neither should accept an arbitrary upstream URL or a bundle of provider headers.
Restricting inputs makes validation possible before a request leaves the platform. It also keeps transport details out of application code: callers should not have to reproduce a mobile app’s session handling to read a menu.
Preserve the result’s meaning
Similar services do not necessarily return equivalent data. An item that appears in a catalog may not be available at a particular store. A listed price may not include every charge needed to place an order.
The response contract needs to preserve these distinctions. Where a reviewed operation returns provider JSON directly, its documentation should say so. It should not present an inferred field as something the provider actually returned.
Specify failures as well as success
Invalid input, a revoked key, a missing connection, and an upstream failure require different fixes. An integration needs to distinguish them without parsing an unrelated HTML error page.
Retries also depend on the operation. Repeating a read may be acceptable. Repeating a purchase request after a timeout can create a second purchase. A connector must define the behavior for that operation rather than apply one retry rule to everything.
Keep availability narrow
Support for reading a service’s menu does not imply support for its checkout. Publishing an operation should follow validation of that operation’s behavior, credentials, and failure cases.
That is why ajar’s architecture starts with operation contracts. HTTP endpoints and agent tools need to agree on what an operation accepts, what it returns, and what it is allowed to do.