API client
Free & PremiumThe 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
- Build a request: Params, Headers, Body and Auth
- Read the response and understand errors: Reading the response
- Let every response be checked automatically: Tests
- Switch values such as
{{base_url}}per environment: Environments - Work in several tabs and keep requests in collections: Saved requests and tabs
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
- 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. - Choose the Method: GET fetches something, POST sends something new, PUT and PATCH change it, DELETE removes it. HEAD and OPTIONS are there too.
- Click Send or press Enter in the address field. While the request runs, Send becomes Cancel.
- 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
- Click Add in the Params tab. A new row appears.
- Enter the name on the left (param), for example
limit. - Enter the value on the right (value), for example
10. - 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
- Click Add in the Headers tab.
- Enter the name on the left (Header), for example
Accept. - Enter the value on the right (value), for example
application/json. - 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 (Authorizationor 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:
- Choose the method POST and enter the address.
- In the Body tab, choose Raw (JSON / text) from the list. Next to it the content type
application/jsonappears. - Write the JSON into the editor, for example
{ "name": "Test" }. - Click Send.
Send form fields
- Choose Form (urlencoded).
- Click Add and enter field and value, one row per field.
- 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-Typeheader 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
- In the Auth tab, choose the kind, for example Bearer token.
- Fill in the fields that appear for it.
- 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
- Send a request with Send or Enter in the address field.
- Read the status at the top left: green for 200 to 399, red for everything else.
- Look at Body to see what the server sent.
- 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-Typeheader, 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,
0means 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
- Click Add test in the Tests tab. A row Status is with
200appears. - Choose another kind if needed and enter the value.
- Click Send.
- 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 200withgot 404orResponse under 1000 mswithtook 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
- Click Manage environments. The dialog opens.
- Click New environment on the left.
- Enter a Name, for example
Local. - Under Variables, click Add variable and enter name and value, for example
base_urlandhttps://shop.test. - Click Save.
Use an environment
- Choose the environment in the picker of the Environment area. No environment switches it off.
- Write
{{base_url}}into the address, such as{{base_url}}/api/products. - 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)
- Build the request, at least with an address.
- Click Save to the right of Send.
- Enter a Request name, for example "List products".
- Choose a Collection if needed. The picker appears once there is one.
- 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 |