REST
Most modern systems expose their data over a REST interface. If yours does, connecting it is a configuration exercise rather than a development project.
Most modern systems expose their data over a REST interface. If yours does, connecting it is a configuration exercise rather than a development project.
What a REST interface exposes, and why that matters here
REST is the dominant pattern for application interfaces. A system that speaks it exposes named resources that can be requested individually — an order, a customer, a case — which happens to map very neatly onto the questions an assistant needs to answer.
The practical significance is that no bespoke connector is needed. If a system has a REST interface and you can issue credentials for it, it can be connected within the same scoped, read-first discipline as any named integration.
- Named resources — the specific objects a system exposes.
- Authentication — credentials you issue and can revoke.
- Scoping — the narrow set of operations agreed at deployment.
- Responses — structured data the assistant turns into sentences.
- Error states — what the system says when something is unavailable.
Questions Elbi can answer over a REST API
Where is this record?
A specific object retrieved and described in plain language.
What is its status?
Current state from the live system rather than a cached copy.
Does this exist?
Existence, which resolves a surprising share of internal queries.
What is associated with it?
Related records, where the interface exposes them.
Has it changed?
Current state compared against what someone expected.
Create this record
Where you deliberately enable a write operation, optionally behind confirmation.
How Elbi works with a REST API
- An allow-list of methods and pathsScope is written as specific operations, such as GET on an order by its reference, rather than "the API". Anything not on the list, whether another path or another method on the same path, is never called.
- Reads are GET requestsLookups use GET, which HTTP defines as a request that does not change anything on the server. Writes, a POST to create a record or a PATCH to update one, are separate entries on the list, each enabled deliberately and each able to wait for a person's confirmation.
- Authentication your team issuesDepending on the system, the connection uses an API key, a bearer token obtained through an OAuth client-credentials grant, or mutual TLS where the API expects a client certificate. Each is issued on your side and can be rotated or revoked without us.
- Parameters come from the conversationElbi collects the reference, date or identifier an operation needs, checks its format and fills the path or query parameters. The asker's verified identity can be passed as well, so the API itself can refuse a record that is not theirs.
- Status codes become sentencesA 404 means "there is no order with that reference", not "the system is broken". A 401 or 403 means the credential or permission is wrong, and goes to a person rather than being retried. A 429 is the API asking callers to slow down, and is respected. Server errors and timeouts become a plain "I can't reach that system right now".
- Only the fields that matter are usedJSON responses often carry far more than an answer needs. The mapping picks the few fields a sentence requires, such as status, date and amount, and the rest is discarded.
REST operations, credentials and what stays yours
| Direction of access | GET on the listed resources by default. Read access never implies POST, PUT, PATCH or DELETE; each write operation is listed separately, and DELETE is rarely worth listing at all. |
|---|---|
| Who can see what | The API's own authorisation decides what the credential may reach. Where the API can act for a user or filter by customer, the asker's identity is passed so it enforces per-person limits itself; otherwise answers are restricted to the asker's own records. |
| Credentials | Keys, client secrets and certificates are created in your API gateway or in the system itself, limited to the listed operations where the platform allows. Revoking them ends the connection at once. |
| Where data goes | Responses are read at the moment of the question, trimmed to the fields needed and not stored as a copy. Message content from the conversation is destroyed within 24 hours, usually when it ends, and no external AI service ever receives it. |
| Audit | Each call is logged with its method, path, status code, conversation and agent, which lines up with your gateway's own access logs. |
| If it is unavailable | Timeouts, server errors and rate limiting are reported as unavailability and a person is offered. A cached response is never presented as live. |
What this replaces
The value of a general interface connection is reach. Most organisations have systems nobody builds connectors for — a bespoke application, a regional product, something built internally a decade ago. If it speaks REST, it is reachable.
The discipline is identical to any named integration and matters more here, because a general capability invites broad connection. Named operations, read-first, scoped credentials, logged lookups. A connection defined as "the assistant can call this API" is far harder to reason about than one defined as "the assistant can look up an order by reference".
The failure to avoid is treating the interface as the design. The questions come first; the operations that answer them follow. Systems expose far more than anyone needs.
Where a REST connection is the usual route
Bespoke internal systems
Applications built in-house with no off-the-shelf connector.
Regional products
Systems widely used locally but not internationally.
Legacy applications
Older systems with an interface added later.
Any modern system
The default integration path for contemporary software.
Getting value from a REST API
Look at what the API already does well. Most REST APIs are built around fetching one resource by its identifier, and that is exactly the shape of the questions that dominate contact: this order, this application, this invoice. Connect those lookups first.
If the system publishes an OpenAPI description, start from it. It lists paths, parameters and response fields, and the scope document almost writes itself. If it does not, a handful of real responses from a test environment serve the same purpose.
Leave listing and search endpoints for later. An endpoint that returns every order matching a filter is useful to staff and risky in a conversation; one that returns a single order for a verified customer is what an assistant needs.
What connecting a REST API involves
- Pick the questions, then the endpointsFrom real contact, choose the questions worth answering, then find the one endpoint that answers each. If no endpoint fits, that is a finding, not a reason to widen the scope.
- Write the allow-listMethod, path, parameters and the response fields used, for every operation. This is the document your security team signs and your auditor reads.
- Issue the credentialYour team creates the API key, OAuth client or client certificate, ideally restricted to the listed operations at the gateway. It stays yours to rotate or revoke.
- Map responses and errorsField names, codes and enumerated values are mapped to plain Arabic and English, together with what each error status should produce in conversation.
- Test against a non-production environmentUnknown references, an expired credential, rate limiting, a slow response, a record belonging to someone else. Each should give a predictable and honest answer.
- Launch on reads, then add writesGo live with GET operations, read a month of real traffic, then add the first POST if it has earned its place.
Personal data in API responses
API responses tend to over-share: a customer endpoint returns the national ID, date of birth and full address because some other consumer once needed them. Under the Saudi Personal Data Protection Law what counts is what is processed, so the field mapping is a privacy control as much as a technical one, and everything a sentence does not need is discarded.
Where the API supports field selection or a narrower view, use it, so the extra data never leaves your system at all. What does reach Elbi serves the answer in front of it, and the conversation holding that answer is destroyed within 24 hours.
What organisations typically see
REST and the alternatives
REST is the default for modern systems and the simplest route when an API already exposes the record a question is about. It is not the only one. Where a system offers GraphQL, one query can return exactly the fields needed across related records. Where it speaks SOAP, as many banking, telecom and government systems still do, a formal contract describes each operation. Where there is no API at all, a read-only database view or a scheduled file exchange may be the realistic option.
Many organisations also put an API gateway in front of internal services. Connecting through the gateway rather than to each service keeps authentication, rate limits and logging in one place your team already runs.
The recurring mistake is issuing a credential that can call everything because it was quicker. The allow-list is short for a reason.
Common questions
Any system with a REST interface and credentials you can issue. The specifics are established during deployment.
Usually not on your side beyond issuing scoped credentials. The mapping is deployment work.
No, and it should not. Named operations agreed at deployment, not general access to an interface.
Elbi uses a credential your team issues for the listed operations, and only for those calls. You can rotate or revoke it at your gateway or in the system at any time, without going through us.
Many do not: methods used loosely, errors returned with a success status, custom authentication headers. These quirks are mapped during deployment, and error handling follows what your API actually does rather than what the convention says.
Where you list a POST or PATCH operation, yes, optionally behind a person's confirmation. If the API supports idempotency keys, using them stops a retried request from creating a duplicate record.
Connect Elbi to your REST API
Named operations on your own systems, answered in Arabic and English.