Buy

API client

Free & Premium

The API client sends HTTP requests to an API and shows you the response: status, duration, size, body and headers. It runs in the app, not in a browser, so there are no CORS hurdles. It reaches your local sites directly, over HTTPS with WebDonkey's certificates too. Tests check every response by themselves.

What you do here

Page layout

Area Content
Head title, on the right the badge of the active environment, if one is active
Left the list Saved requests with New collection, below it Environment. The list folds away. With Premium the narrow strip then shows your collections with the number of their requests
Top centre the Request tabs bar: one tab per request, with method and title, + (New tab) opens another
Address row Method, Address, the time limit in seconds, Send and Save
Request the tabs Params, Headers, Body, Auth and Tests. The number in brackets counts the entries. On the right the button Enlarge request area
Response status, duration and size, plus the views Body, Headers and Tests

You drag the divider between request and response with the mouse. As long as you have not chosen a height, the request area sizes itself and makes room for the response after sending. Automatic height brings that back.

A first request

  1. Enter a URL under Address, for example https://api.example.com/v1/users. While the field is empty, the response area suggests up to two of your sites under To try it out, one of your local sites:. A click puts the address in.
  2. Choose the Method: GET fetches something, POST sends something new, PUT and PATCH change it, DELETE removes it. HEAD and OPTIONS are there too.
  3. Click Send or press Enter in the address field. While the request runs, Send becomes Cancel.
  4. Read the response below.

What happens in the background

  • The app sends the request itself, with the user agent WebDonkey-API-Client. It trusts WebDonkey's local certificate authority, so it checks local HTTPS sites like any other site.
  • It reads responses up to 64 MB. Binary responses such as images or PDFs are summarised instead of shown as gibberish.
  • Your tabs with everything you entered survive a restart of the app. Responses only last until you quit.
  • Saved requests, collections and environments live in the app's database on your Mac.

Free and Premium

Free Premium
Build and send requests, read the response yes yes
Tests yes yes
Up to 20 tabs, also after a restart yes yes
Save requests, collections no yes
Environments with variables no yes

On the Free plan the Save button is missing. Instead, the left side says Saving requests, collections and environments is Premium. Sending and tests are free.

Params Free

Params add details to the address, the query string. limit = 10 becomes ?limit=10, which many APIs read as "ten results only". In the Params tab you keep them as a list and switch single ones on and off without rewriting the address.

Where to find it

Sidebar Tools › API client, in the request area the tab Params. The number in brackets counts the rows.

How to do it

  1. Click Add in the Params tab. A new row appears.
  2. Enter the name on the left (param), for example limit.
  3. Enter the value on the right (value), for example 10.
  4. Click Send.

Fields and options

Element Meaning
Checkbox Enabled on: the row goes along. off: it stays in the list but does not go along. That is how you park a param you only need now and then
param the param's name
value the param's value
X at the end removes the row
Add new row, switched on

As long as there is no row, a short note explains the tab.

What happens in the background

  • On sending, the app appends every enabled row to the address and encodes special characters such as spaces or & itself.
  • Names and values may contain variables of the active environment, such as {{page_size}}. The app puts the value in on sending. If the environment does not know a name, the text goes out as written.
  • Params you write straight into the address stay there and do not show in the list. Both together work.

Troubleshooting

What you see Why What you do
The server ignores the param The Enabled checkbox is off, or the name is misspelt Check the box, compare the name with the API documentation
A param arrives twice It is in the address and in the list Remove it in one place
{{name}} reaches the server literally No environment is active or the name is missing in it Choose the environment or add the variable there

See also

Headers Free

Headers are extra details that travel with the request. Accept = application/json asks the server to answer in JSON, X-Shop-Id = 42 tells an API which shop is meant. In the Headers tab you keep them as a list.

Where to find it

Sidebar Tools › API client, in the request area the tab Headers. The number in brackets counts the rows.

How to do it

  1. Click Add in the Headers tab.
  2. Enter the name on the left (Header), for example Accept.
  3. Enter the value on the right (value), for example application/json.
  4. Click Send.

Fields and options

Element Meaning
Checkbox Enabled on: the header goes along. off: it stays in the list but does not go along
Header the header's name
value the header's value
X at the end removes the row
Add new row, switched on

What happens in the background

  • Names and values may contain variables of the active environment, for example a key as {{access_key}}. If a variable is missing, a line below the address warns: Not in the environment “…”: … It is sent as it is written.
  • Two headers come from other tabs: the content type (Content-Type) from the Body tab and the sign-in (Authorization or an API key header) from the Auth tab. Do not add them here as well.
  • You read the response's headers below, in the response's Headers view.

Troubleshooting

What you see Why What you do
Response 401 or 403 The sign-in is missing or wrong Check the Auth tab
Response 415 The server expects another content type Adjust the content type in the Body tab
A header arrives twice It is here and is set by another tab Remove the row here

See also

Body Free

The body is the data you send along with the request, for example a new product as JSON. A request that only fetches something (GET) needs none. In the Body tab you choose what goes along: nothing, free text or form fields.

Where to find it

Sidebar Tools › API client, in the request area the tab Body.

How to do it

Send a JSON object:

  1. Choose the method POST and enter the address.
  2. In the Body tab, choose Raw (JSON / text) from the list. Next to it the content type application/json appears.
  3. Write the JSON into the editor, for example { "name": "Test" }.
  4. Click Send.

Send form fields

  1. Choose Form (urlencoded).
  2. Click Add and enter field and value, one row per field.
  3. Click Send. The fields go out like an HTML form.

Fields and options

Kind What goes along
No body nothing. The default for every new request
Raw (JSON / text) the text in the editor, exactly as written. Next to the list you enter the content type, default application/json. If it contains json, the editor colours the text as JSON
Form (urlencoded) a list of field and value, sent as application/x-www-form-urlencoded. The Enabled checkbox switches single fields off, X removes a row

When you change the kind, the new body starts empty. Every tab has its own editor with its own undo.

What happens in the background

  • With Raw (JSON / text), the app sets the Content-Type header to the value next to the list. With form fields it sets it itself.
  • The app replaces variables of the active environment, such as {{base_url}} or a token, in the body too, in raw text as in form fields.
  • The app does not check whether your JSON is valid. What is in the editor goes out.

Troubleshooting

What you see Why What you do
The server reports invalid JSON A comma or a quotation mark is missing Check the text in the editor, the colouring helps
Response 415 The content type does not match what the server expects Adjust the content type next to the list
The body does not arrive No body is chosen, or the method is GET and the server reads no body for GET Choose a kind, check the method

See also

Auth Free

Many APIs want to know who is asking. In the Auth tab you identify yourself to the server, for example with a token the API gave you. Which kind the service expects is in its API documentation.

Where to find it

Sidebar Tools › API client, in the request area the tab Auth.

How to do it

  1. In the Auth tab, choose the kind, for example Bearer token.
  2. Fill in the fields that appear for it.
  3. Click Send.

Fields and options

Kind What you enter What is sent
No auth nothing no credentials. The default
Bearer token Token the header Authorization: Bearer <token>
Basic auth Username and Password the header Authorization: Basic … with both, Base64-encoded
API key (header) the header's name (default X-API-Key) and the value exactly this header

The password for Basic auth is hidden.

What happens in the background

  • Every field may contain variables of the active environment, such as {{access_token}}. That way you switch between local and live without changing the request.
  • If you save the request (Premium), the app saves what is here too. If a token is a variable here, it only lives in the environment.

Troubleshooting

What you see Why What you do
Response 401 Token or password is missing, expired or wrong Check the value, with variables the active environment
Response 403 The sign-in is right, but the account may not do this Check the rights with the API's provider
The server expects the key as a param instead of a header Some APIs read it from the address Choose No auth and enter the key in the Params tab

See also

Reading the response Free

After Send, the response appears below the request: status, duration and size at the top, below that the body, the headers and the result of your tests. Until then the area says what to do next.

Where to find it

Sidebar Tools › API client, the lower area below the request. Every tab has its own response.

How to do it

  1. Send a request with Send or Enter in the address field.
  2. Read the status at the top left: green for 200 to 399, red for everything else.
  3. Look at Body to see what the server sent.
  4. Switch to Headers or Tests if needed.

Fields and options

Header line

Item Meaning
Status code and reason, for example 200 OK or 404 Not Found
Duration milliseconds from sending until the response
Size size of the body in B, KB or MB

Views

View Shows
Body the body in a read-only editor. The app indents JSON automatically. For binary responses such as images, PDFs or ZIP files, it only says how many bytes there are
Headers every header of the response, the number in brackets counts them
Tests per test a green tick or a red cross with the reason, the number next to it shows passed out of total, such as 3/4. Without tests: No tests defined.

Before you send

As long as the tab has not sent anything, the response area says The response appears here. If the address is empty, it suggests up to two of your switched-on sites under To try it out, one of your local sites:. A click puts the address in.

What happens in the background

  • The response belongs to the tab you sent from. If you switch tab or page meanwhile, it still lands there. Several tabs may send at the same time.
  • The app reads the character set from the Content-Type header, many older sites send ISO-8859-1 instead of UTF-8.
  • The app reads at most 64 MB of a response.
  • The time limit next to the address aborts the request after that many seconds. The default is 30 seconds, 0 means no limit.

Local HTTPS

Local sites with WebDonkey's HTTPS work without an extra step, the app trusts WebDonkey's local certificate authority. For a site with a certificate your Mac does not know, switch on Allow invalid/self-signed TLS certificates (local dev) in the Tests tab. The request then shows Certificate is not checked to the right above the tabs. A click on it turns the check on again. Use this for local sites only.

Troubleshooting

What you see Why What you do
request timed out The time limit was shorter than the response time Raise the time limit or set it to 0
request failed: … mentioning certificates The server's certificate is invalid or unknown For local sites, switch on the TLS option in the Tests tab
request failed: … with "connection refused" Nothing listens at the address Check that the site or service runs, for example with wd sites
A {{name}} in the address reaches the server The variable is missing in the active environment See Environments
No response after Cancel That is intended, cancelled requests show no error Send again

See also

Tests Free

Tests check every response by themselves. "Status is 200", for example, means: the request worked. You set the checks up once, and after every Send the response shows which of them passed. That way you notice at once when an API changes its answer. Tests are free.

Where to find it

Sidebar Tools › API client, in the request area the tab Tests. After sending, the result is in the response's Tests view.

How to do it

  1. Click Add test in the Tests tab. A row Status is with 200 appears.
  2. Choose another kind if needed and enter the value.
  3. Click Send.
  4. Switch to Tests in the response. Every check shows a green tick or a red cross with the reason, next to it the number passed, such as 3/4.

A good start: Status is 200 and JSON path exists for the most important field.

Fields and options

Kind Checks Input
Status is the status code is exactly this one a number, default 200
Time under (ms) the response came within that many milliseconds a number, default 1000
Body contains the response body contains this text, case-sensitive a text
JSON path equals the value at a path such as data.items.0.id is exactly the one expected path and expected
JSON path exists there is a value at this path a path

X at the end of a row removes the test.

JSON paths

You separate levels with dots, a number reaches into a list. From {"data": {"items": [{"id": 7}]}}, data.items.0.id gives the value 7. JSON path equals compares as text: a number 7 equals the expected 7, a string is compared without quotation marks.

The TLS option

Below the tests sits Allow invalid/self-signed TLS certificates (local dev). When it is on, the request does not check the server's certificate. That is meant for local sites with a foreign certificate, see Reading the response.

What happens in the background

  • The app evaluates the tests right when the response arrives, before it is shown.
  • The JSON tests need a response that can be read as JSON. Otherwise they fail with path not found.
  • Label and reason of a result are in English, for example Status is 200 with got 404 or Response under 1000 ms with took 1530 ms.

Troubleshooting

What you see Why What you do
path not found The path is wrong or the response is not JSON Look in the response's Body at how the fields are called
JSON path equals fails with got … The value in the response is written differently from the expected one, such as true instead of 1 Enter the value exactly as it appears in the response
Time under (ms) fails now and then The response time varies Set a more generous value

See also

Environments Premium

An environment holds variables, values such as {{base_url}} or {{access_token}} that you reuse in requests. With one environment Local and one Live, you send the same request to https://shop.test one time and to https://shop.example.com the next, without rewriting it. Environments are Premium.

Where to find it

Sidebar Tools › API client, on the left below the saved requests the Environment area with the picker and the button Manage environments.

How to do it

Create an environment

  1. Click Manage environments. The dialog opens.
  2. Click New environment on the left.
  3. Enter a Name, for example Local.
  4. Under Variables, click Add variable and enter name and value, for example base_url and https://shop.test.
  5. Click Save.

Use an environment

  1. Choose the environment in the picker of the Environment area. No environment switches it off.
  2. Write {{base_url}} into the address, such as {{base_url}}/api/products.
  3. Click Send. The app puts the value in.

The top right of the page now shows a badge with the active environment's name.

Fields and options

In the Environment area

Element Meaning
Picker the active environment or No environment
Pencil Edit “…”: opens the dialog at the active environment
Show its variables unfolds the active environment's variables with their values, the number in brackets counts them
Manage environments opens the dialog

In the dialog Manage environments

Element Meaning
List on the left every environment, the active one carries active. New environment creates one
Name required. Without a name the dialog says The environment needs a name.
Variables the variables as Rows (name and value per row) or as JSON, such as {"base_url": "https://example.test"}. You can switch between both views at any time
Add variable new row, the cross at the end removes it
Duplicate opens a copy of the environment under a new name. It exists once you save it
Delete asks Delete “…” with its variables? This cannot be undone.
Discard, Save drop or save the changes

If you close the dialog or switch environment with unsaved changes, it asks: You have changes that are not saved. with Keep editing, Discard and Save.

What happens in the background

  • On sending, the app replaces every {{name}} with the active environment's value: in the address, params, headers, body and auth.
  • If the active environment does not know a name, {{name}} stays and goes out as written. If it is in the address or a header, a line below the address warns before sending: Not in the environment “…”: … It is sent as it is written. If no environment is active, the line says so.
  • Environments live in the app's database on your Mac, their values included.

Free and Premium

Environments are Premium. On the Free plan the Environment area only appears if you have environments from an earlier Premium time. They are kept and can be looked at and deleted in the dialog, but not chosen. A locked environment is not applied when sending.

Troubleshooting

What you see Why What you do
The variable needs a name. A row has a value but no name Enter a name or remove the row
This name is there twice. Only one of the two would be kept. Two rows have the same name Rename or remove one
This is not valid JSON yet: … A character is missing in the JSON view Check braces, commas and quotation marks
Message that it has to be an object of names and values The JSON is a list or a single value Use the form {"name": "value"}

See also

Saved requests and tabs Free & Premium

In the API client you work in up to 20 request tabs side by side, each with its own request and response. With Premium you keep requests permanently in the list Saved requests and sort them into collections, for example all requests for one shop.

Where to find it

Sidebar Tools › API client. The tabs sit above the address row, the saved requests on the left.

How to do it

Save a request (Premium)

  1. Build the request, at least with an address.
  2. Click Save to the right of Send.
  3. Enter a Request name, for example "List products".
  4. Choose a Collection if needed. The picker appears once there is one.
  5. Click Save. The request appears on the left, the tab carries its name.

If you change something afterwards, the tab shows a dot for Unsaved changes, and Save puts the change into the saved request. If nothing changed, it says Saved with a tick.

Save straight into a collection

If the open tab is not saved yet, every unfolded collection shows Save the open request here. A click only asks for the name.

Open a saved request

Click the request on the left. It opens in the tab that already holds it, otherwise in the open tab if that one is empty, otherwise in a new one. If it is already open, the app switches to that tab and lets it light up briefly.

Fields and options

Request tabs

Action How
New tab + at the end of the bar (New tab)
Switch tab click the tab
Rename tab double-click, F2 or Rename tab in the context menu. Enter applies, Escape cancels. Without a name of its own the title follows the request, such as its name or method and path
Duplicate tab Duplicate tab in the context menu
Close tab the cross in the tab, a middle click or Close tab
Close the others Close other tabs in the context menu

You open the context menu with a right-click on the tab. A dot in the tab means Unsaved changes, a symbol of its own shows Request under way. At 20 tabs the app says No more than 20 tabs. Close one to open another.

The list Saved requests

Element Meaning
New collection new collection, with a name only (Name of the collection)
Collection unfoldable, with the number of its requests. The … menu (or a right-click) has Rename and Delete collection only
No collection requests that are in no collection
Request method and name. The … menu has Open, Open as a copy in a new tab, Rename or move and Delete
  • Open as a copy in a new tab leaves the original untouched, the tab is called "… (copy)".
  • Rename or move changes name and collection.
  • Delete collection only removes the folder, the requests in it move to No collection.
  • Delete removes the request without asking. A tab that has it open keeps the text as unsaved work.

The symbol to the right of Saved requests folds the list into a narrow strip, Show saved requests brings it back. The choice survives a restart.

What happens in the background

  • The app stores the tabs with everything you entered on your Mac as you go. They are back after a restart, on the Free plan too. Responses only last until you quit.
  • Saved requests and collections live in the app's database.

Free and Premium

Tabs, sending and tests are free. Saving, collections and environments are Premium. On the Free plan the Save button is missing, and the left side says Saving requests, collections and environments is Premium. Sending and tests are free.

After a switch from Premium to Free, saved requests stay visible but locked: you can rename and delete them, but not open them. Tabs that were bound to a locked request keep their text as unsaved work.

Troubleshooting

What you see Why What you do
No more than 20 tabs. … The tab limit is reached Close a tab
No Save button Free plan Activate Premium or keep the request in the tab
A request does not open It is locked after a downgrade Activate Premium, or rename and delete it

See also

Cookie preferences

This website uses cookies to ensure the best experience possible. Your choice applies to webdonkey.io and the shop at shop.webdonkey.io. More information...

Technically required

Cookies required for this website to function:

Always on
WebDonkey
WebDonkey
Provider: BuI Hinsche GmbH, Neumarkt 7, 06712 Zeitz, Germany
Purpose: Your consent, colour scheme and language for website and shop, price switches; with wd_debug in the address, the measurement events in the developer console for troubleshooting
Cookies and storage: Cookie wd_consent on .webdonkey.io, shared with shop.webdonkey.io (12 months); cookies wd_theme and wd_lang on .webdonkey.io, shared with shop.webdonkey.io, only when you switch colour scheme or language yourself (365 days); localStorage wd:consent, wd:theme, wd:lang; sessionStorage wd:acc, wd:term, wd:debug (only with wd_debug in the address; until the tab closes)

Statistics

Shows us which pages and products people look at on webdonkey.io and in the shop, where visitors come from and how they get to a purchase (with order number, amount and products, without name or email address). Provider: Google. Transfer to the USA possible (EU-US Data Privacy Framework). Your choice applies to webdonkey.io and the shop together.

Google Tag Manager, Google Analytics 4
Google Tag Manager
Provider: Google Ireland Limited, Gordon House, Barrow Street, Dublin 4, Ireland
Purpose: Loads the services you agreed to, here and in the shop. Sets no cookies of its own.
Cookies and storage: none
Privacy policy
Google Analytics 4
Provider: Google Ireland Limited, Gordon House, Barrow Street, Dublin 4, Ireland
Purpose: Usage statistics: page views, clicks, scroll depth, sources, devices, load times; in the shop also basket, checkout, purchases, registration and sign-in
Cookies and storage: _ga, _ga_<ID> (2 years)
Privacy policy

Marketing

Measures whether our ads on Facebook, Instagram and TikTok lead to visits and downloads on webdonkey.io and to registrations and purchases in the shop, and builds audiences for ads. Providers: Meta and TikTok, with whom we are jointly responsible for this. With this consent Google may also set advertising cookies (_gcl_…). Transfer to the USA and other countries outside the EU possible. Your choice applies to webdonkey.io and the shop together.

Google Tag Manager, Meta Pixel (Facebook, Instagram), TikTok Pixel
Google Tag Manager
Provider: Google Ireland Limited, Gordon House, Barrow Street, Dublin 4, Ireland
Purpose: Loads the services you agreed to, here and in the shop. Sets no cookies of its own.
Cookies and storage: none
Privacy policy
Meta Pixel (Facebook, Instagram)
Provider: Meta Platforms Ireland Limited, Merrion Road, Dublin 4, D04 X2K5, Ireland
Purpose: Ad measurement and target groups on Facebook and Instagram, also in the shop (basket, checkout, purchases, registration)
Cookies and storage: _fbp (3 months), _fbc (3 months, only if you arrive through an ad), fr on facebook.com (3 months)
Privacy policy
TikTok Pixel
Provider: TikTok Technology Limited, 10 Earlsfort Terrace, Dublin, D02 T380, Ireland
Purpose: Ad measurement and target groups on TikTok, also in the shop (basket, checkout, purchases, registration)
Cookies and storage: _ttp, _tt_enable_cookie (13 months)
Privacy policy