Any REST or SOAP system, without code

How to connect a system SourceLace has no ready-made connector for, when it has a REST API (with or without an OpenAPI document) or a SOAP web service (with a WSDL). An admin describes the API on Manage sources; nobody writes or runs any code. For systems with no web API at all, build your own connector instead.

Status: Preview. New, offered for pilots and provided as is. Neither kind has been used with a customer's live system yet.

At a glance

Add each source with the usual steps. The network answers are explained in What your network needs. If the first test question fails, the error message tells you what to fix: look it up under When something goes wrong below.

How it works

• REST (rest): every operation in the API's description becomes an object. People (and their AI) find operations with search, see each one's parameters, and read with a query that names an operation and its parameters, in the rest_json language: {"operation": "listInvoices", "params": {"status": "open"}}. SourceLace checks every query against the description (the operation exists and is a read, required parameters are there, nothing unknown, values have the right type and allowed values) before anything is sent, and pages through the results itself.
• SOAP (soap): every operation the admin marks as a read becomes an object, queried the same way in the soap_json language: {"operation": "GetCustomers", "params": {"Country": "DE"}}. SourceLace builds the SOAP 1.1 or 1.2 message, reads the answer, and turns SOAP faults into messages that say what to fix.
• Only reads, unless you allow more. For REST, only GET operations are reads. Every other operation (POST, PUT, PATCH, DELETE) is off until an admin switches it on by name. A switched-on operation never runs as a query: it runs only as a change, which the person sees first (the exact request, and the record's current values when the API has a GET on the same path) and confirms. SOAP sources are read-only.
• Answers are data. What the system sends back only ever becomes rows; nothing in it is followed as an instruction.

How people sign in

Shared access: with api_key, bearer, basic or none, everyone who may use the source acts as the same account, so the system cannot tell people apart and cannot apply its own permissions per person. SourceLace says so wherever the source is listed. Give such a key the least access it needs (read-only if possible), and limit who can use the source with access by group.

Secrets (the OAuth client secret, the API key, token or password) are stored encrypted with your organization's key, shown only as "(saved)", never sent anywhere but the system itself, and never written to logs or answers.

Add a REST source (SourceLace admin)

1. If the system offers OAuth, have its admin register an OAuth app (client) for SourceLace, with exactly this redirect URL, https://sourcelace.onrender.com/connect/callback, and only the read scopes people need. Otherwise, create an API key or a service account with the least access needed.
2. On Manage sources → Add a source, choose Any REST API, no code (rest), give it a name (such as rest:billing) and a label.
3. Paste or load the API's OpenAPI 3 or Swagger 2 document (JSON or YAML), or give its address in spec_url: SourceLace fetches it once when you save and keeps it. To refresh it later, empty the document box and save again. Without an OpenAPI document, list a few endpoints by hand (below).
4. Choose how people sign in, and fill in its options.
5. Save, then press Test connection: SourceLace checks the description, that the address may be called, and (for shared access) reads a few records.
6. To allow changes, turn on Allow changes and name the operations, such as createInvoice, updateInvoice.

Endpoints by hand look like this (only name and path are required; method defaults to GET):

{"base_url": "https://api.corvanta.com/v1",
 "endpoints": [
   {"name": "invoices", "method": "GET", "path": "/invoices", "description": "Invoices, newest first",
    "params": [{"name": "status", "in": "query", "enum": ["open", "paid"]}],
    "rows": "data",
    "paging": {"style": "cursor", "param": "starting_after", "next": "meta.next_cursor"}},
   {"name": "invoice", "path": "/invoices/{id}"},
   {"name": "createInvoice", "method": "POST", "path": "/invoices", "body": ["amount", "customer"]}]}

• params: each with name, in (query, path or header), and optionally required, type (string, integer, number, boolean, array), enum and description. Every {name} in the path is a required path parameter.
• rows: where the records are in the answer, as a dotted path (data, result.items); empty for an answer that is itself the list. Left out, SourceLace looks for a list such as data, items or results.
• paging: style is page (with param, such as page), offset (with param, such as offset, and size_param), cursor (with param and next, the dotted path to the next cursor in the answer), link (the Link: <…>; rel="next" header) or none. size_param and size set how many rows a page asks for. For OpenAPI documents SourceLace works this out from the parameter names; an operation can also say it with x-sourcelace-paging and x-sourcelace-rows.
• body: for changes, the JSON body's field names.

Changes

A change names its operation as the object: POST operations are creates, PUT and PATCH updates, DELETE deletes. Its fields are the operation's parameters (by name) and its JSON body fields; the record id fills the path's last parameter (or several, as a JSON object such as {"customerId": "C-1", "id": "7"}). Each change shows the exact request before the person confirms it.

Add a SOAP source (SourceLace admin)

1. Create a service account with read-only access, or an OAuth client if the service supports it.
2. On Manage sources → Add a source, choose Any SOAP web service, no code (soap), with a name such as soap:customers.
3. Paste or load the WSDL, or give its address in wsdl_url: SourceLace fetches it once when you save and keeps it (empty the box and save again to refresh it).
4. List the operations that only read in read_operations, such as GetCustomers, GetOrders. Nothing else can run.
5. Choose how people sign in (the same choices and options as REST), save, and press Test connection.

Supported: document/literal (including the common "wrapped" style) and rpc/literal. SOAP encoding (use="encoded") is not.

Safety

These sources reach addresses your admin types in, so SourceLace guards every request:

• only https:// (a self-hosted server's operator may allow http:// with SOURCELACE_ALLOW_HTTP_API_SOURCES);
• in SourceLace's cloud, only addresses on the public internet: private, loopback, link-local and other reserved addresses are refused, every address a name resolves to is checked, and the request goes to the address that was checked. Cloud metadata addresses are always refused, on any server;
• redirects are never followed, and next-page links must stay on the API's own address;
• answers are limited to 10 MB, and each query to the organization's query time (queries.timeout_seconds) and row cap;
• each source sends at most queries.api_requests_per_minute requests a minute (120 by default; see Limits);
• nothing of SourceLace's own (cookies, tokens, keys) is ever sent: only the source's own credential;
• XML (the WSDL and every SOAP answer) is read with DTDs and entities refused, so XML attacks such as external entities and "billion laughs" do not work.

When something goes wrong