# Connect your tools through APIs · practice guide

Version 1 · Original teaching material · Fictional case · EN

## What you will prepare

A request worksheet, a mapping, the complete pending-order list and a connection decision. Work with files: there is no server, real account or importable automation. The method can transfer to the platform and services agreed for an edition; access and execution are checked separately.

You need experience with a simple workflow and field mapping, or equivalent. Coding is not required. Open JSON, HTTP and Markdown in a text editor and CSV in a spreadsheet. If access or a format blocks you, record the issue: the trainer agrees a text alternative without claiming an executed connection.

## The brief

Operations reviews a fictional supplier’s pending orders daily. Its available connector does not provide this query. The classroom documentation defines a read request, two pages and three fields. Preserve each identifier, show what is missing and explain what to do when an error occurs. Do not send notifications, purchase anything or change records.

## Session 1 · 120 minutes

| Minutes | Activity |
|---:|---|
| 10 | Agree the need and case boundaries |
| 25 | Read `api-reference.md`: endpoint, method and parameters |
| 30 | Review `requests.http` and `responses.json`; complete `mapping-blank.csv` |
| 5 | Break |
| 25 | Identify authentication and access preparation, without entering secrets |
| 15 | Review individual mapping and receive short feedback |
| 10 | Recap what the first page does and does not establish |

Read the reference first. Distinguish the path and parameters from output fields. Explain why GET fits the query brief and why this contract does not need a request body. Complete a rule for `id`, `status` and `delivery_date`. Locate the null value: it is different from a date and does not permit copying another order’s value.

Discuss the example’s authentication conceptually. Do not paste keys or passwords into worksheets. Identify who would check the service, its access method and credential storage in the chosen platform. The prepared 401 error lets you discuss invalid access without creating or requesting a real credential.

## Session 2 · 120 minutes

| Minutes | Activity |
|---:|---|
| 10 | Recall the brief and review a request |
| 25 | Follow `next_cursor` and complete `orders-blank.csv` |
| 30 | Review 401, 429 and 500 using `tests-blank.csv` |
| 5 | Break |
| 25 | Complete `decision-blank.md`: connector, HTTP or technical help |
| 20 | Individual evidence, checking and feedback |
| 5 | Record the next step and close |

Follow OK-1’s cursor using the `page_2` request. Keep `status=pending` and `limit=2`. The second page ends with `next_cursor: null`. Combine pages by identifier; page size is neither the total number of orders nor the request limit per time period.

Record expected results and your response to each error before opening the worked example. A 401 needs access review with its owner; a 429 requires the stated wait and agreed limit; a 500 is not fixed by changing data blindly. In this simulation, any permitted query retry has at most two total attempts, including the initial attempt; if the error persists, stop and escalate. Do not configure loops or make calls.

Also review FORMAT-200: a 200 is not enough if the structure violates the contract. That case is not a valid empty list. Finally, explain what a connector might cover, what needs HTTP and what needs development or provider information.

## Handover and review

Submit your mapping, list, test record and decision. Explain one missing field and one error with a file reference. The trainer checks: coherent request; complete list and preserved data; bounded diagnosis; justified decision. Feedback is inside the four hours. No mandatory between-session assignment or additional out-of-hours assessment is added.

`expected.md` and `worked-example` files are fictional self-check solutions, not learner evidence or completed executions. Consult them after your attempt. Correct missing information and explain why.

## Before moving to a tool

Client and trainer agree the platform, service, test account, plan, permissions and usage. Check current documentation and endpoint support; do not assume all platforms work alike. If only these files are reviewed, the evidence concerns HTTP/JSON reasoning, not an executed connection. Production preparation or implementation has a separate scope.

Internal pending step: trainer rehearsal of clarity, timings and setup before a real edition.

[Download ZIP pack](api-en-v1.zip)