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.

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.

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")  # -> bytes: the response content

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 Content-Type and auth-derived headers (e.g. the API key header):

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

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"))

Full response: call() returns response.content by default. Pass content_only=False to get the full requests.Response object instead (status code, headers, etc.):

response = backend.call("get", content_only=False)
response.status_code

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