WebService Core

Configuration

Go to Settings > Technical > WebService Backend (requires the Administration / Settings group) and create a new backend:

• Name / Technical Name: a label and a unique technical key you’ll use to look the backend up from code (e.g. env.ref is not used here; search by tech_name instead).
• Protocol: only HTTP Request is available in this module.
• URL: the base URL every call is relative to, e.g. https://api.example.com. It may contain {placeholder} tokens (see Usage), e.g. https://api.example.com/{endpoint}.
• Content-Type: optional default Content-Type header for every call.
• Timeout: optional timeout in seconds for the whole request (connect + read). Left empty, a call waits indefinitely.

Under the Headers and Querystring Params tabs you can configure static defaults, merged into every call (see Usage).

Then configure authentication via Auth Type:

• Public: no credentials needed.
• Username & password: sent as HTTP Basic Auth. Requires Username and Password.
• API Key: sent as a custom header. Requires API Key and API Key header (the header name to send it under, e.g. X-Api-Key).

Required fields depend on the selected auth type; the form only shows and requires the ones that apply, and saving enforces it.

Each webservice.endpoint (see Description) has its own Content-Type, Timeout, Headers and Querystring Params, overriding the backend’s own for that specific endpoint - set only what needs to differ.

Usage

Look up the backend (e.g. by its technical name) and call it:

backend = env["webservice.backend"].search([("tech_name", "=", "my_api")])
result = backend.call("get")  # -> the full requests.Response object

call(method, *args, **kwargs) accepts any of the standard HTTP verbs (get, post, put, delete) and forwards everything else to requests, so any of its keyword arguments work too (data, json, params, files, …):

backend.call("post", data=b"<xml>...</xml>")
backend.call("post", json={"foo": "bar"})

URL: by default the backend’s own url is used. Pass url to hit a different path - relative paths are appended to the backend’s URL, a full http(s):// URL is used as-is:

backend.call("get", url="orders")  # -> <backend url>/orders
backend.call("get", url="https://other.example.com/orders")

If the backend’s URL (or the url passed above) contains {placeholder} tokens, fill them with url_params:

# backend.url == "https://api.example.com/{endpoint}"
backend.call("get", url_params={"endpoint": "orders"})

Headers: pass headers to add/override headers for that call; they are merged on top of the backend’s own static headers (configured in the “Headers” tab), Content-Type and auth-derived headers (e.g. the API key header) - the headers kwarg wins on matching keys:

backend.call("get", headers={"X-Request-Id": "42"})

Querystring params: sent via requests’ params=, not to be confused with url_params above, which fills {placeholder} tokens in the URL path itself. Configure static defaults in the “Querystring Params” tab - a value there may itself contain a {placeholder}, resolved against the same url_params used for the URL. An explicit params kwarg passed to call() wins over the static configuration on matching keys:

backend.call("get", params={"verbose": "1"})

Auth override: pass auth to bypass the backend’s configured auth type for a single call (same format requests itself accepts, e.g. a (user, password) tuple):

backend.call("get", auth=("other_user", "other_password"))

Timeout: pass timeout to override the backend’s own configured timeout (in seconds) for a single call:

backend.call("get", timeout=5)

Response: call() always returns the full requests.Response object (status code, headers, content, …):

response = backend.call("get")
response.status_code
response.content

Bug Tracker

Bugs are tracked on GitHub Issues. In case of trouble, please check there if your issue has already been reported. If you spotted it first, help us to smash it by providing a detailed and welcomed feedback.

Do not contact contributors directly about support or help with technical issues.

Credits