# API Request Lab — Learning handbook DiscoveryVIP · October 8, 2026 Practice in a fictional browser-only task API. No real service is contacted. Use only the public teaching tokens provided in the lab. Generated code is a starting example with an example.invalid endpoint; adapt it to the actual provider’s documentation. ## 1. A request is a structured message Foundations An API gives software a defined way to request information or operations. HTTP requests carry a method, a resource path, headers and sometimes a body. The server interprets them according to its own contract. An endpoint existing does not mean every method or field is allowed. **In the lab:** In the lab, GET /tasks reads a fictional collection. POST /tasks creates an item only when the body and teaching credential meet the contract. Neither action contacts the internet. **Try it:** Send GET /tasks and inspect every part of the exchange. **Check your understanding:** Which part describes the requested operation? 1. HTTP method 2. Text color 3. File extension **Answer:** HTTP method. GET and POST express different operations on the same collection. ## 2. Resources and paths Foundations A resource path identifies what a request addresses. A collection path and an individual-item path usually serve different needs. These conventions are common, but the actual API documentation determines the routes. Do not guess a provider’s behavior from a path name alone. **In the lab:** /tasks lists items; /tasks/1 addresses task 1. /unknown returns 404 in this simulator. The route and the item can fail independently: /tasks/999 is a valid route with a missing item. **Try it:** Compare GET /tasks/1 with GET /tasks/999. **Check your understanding:** Which path selects task 1 in this lab? 1. /tasks?page=1 2. /tasks/1 3. /task-title **Answer:** /tasks/1. The numeric path segment identifies the individual task. ## 3. Query parameters narrow a read Foundations Query parameters follow a question mark and use key=value pairs. They often control filtering, sorting and pagination. Values in a real URL may require encoding. A filter changes the returned view; it does not necessarily change the stored resource. **In the lab:** /tasks?status=open returns unfinished tasks. Adding &limit=1 limits the first page to one item. The total field describes the filtered collection before pagination. **Try it:** Retrieve only Open tasks, then inspect the unchanged database panel. **Check your understanding:** Filtering by status normally changes… 1. Every stored task 2. The server password 3. The returned view **Answer:** The returned view. A read filter selects results without editing the collection. ## 4. Headers carry metadata Foundations Headers describe how a request should be interpreted. Content-Type identifies the representation of the request body. Authorization supplies credentials according to the service’s scheme. Header names are case-insensitive in HTTP; values follow the rules of their particular header. **In the lab:** The lab header editor accepts a JSON object of string pairs. This editor format is a convenience; HTTP headers on the wire are not inherently a JSON object. **Try it:** Try a POST without Content-Type and inspect the 415 response. **Check your understanding:** What describes a JSON request body? 1. Content-Type: application/json 2. Accept: image/png 3. Location: /tasks **Answer:** Content-Type: application/json. Content-Type describes the body being sent. ## 5. JSON has types and structure Requests JSON encodes objects, arrays, strings, numbers, Booleans and null. It does not allow single-quoted strings, comments or trailing commas. Valid JSON is only a syntax check: a server must still validate required fields and their meaning. **In the lab:** {"completed":true} contains a Boolean. {"completed":"true"} contains a string and fails the lab’s PATCH validation. Both can be syntactically valid JSON. **Try it:** Send a wrong-type value and repair it without changing the endpoint. **Check your understanding:** Is the string "true" the same JSON type as true? 1. Yes 2. No 3. Only in PATCH **Answer:** No. A quoted value is text; the unquoted literal is Boolean. ## 6. Read with GET Requests GET retrieves a representation. It is defined as a safe method: the client is not requesting a state change. A server can still log the request or update internal statistics. Do not build a client that relies on a GET body unless the specific environment explicitly supports the design. **In the lab:** Our simulator ignores the body for GET and shows filtered items. The UI keeps the body editor disabled for this method so the operation is clear. **Try it:** Read task 2 and note whether it is completed. **Check your understanding:** Which action is the expected purpose of GET? 1. Delete a task 2. Create a task 3. Retrieve a representation **Answer:** Retrieve a representation. Reads and writes should follow the service contract. ## 7. Create with POST Requests POST asks the resource to process the supplied representation. In this lab it creates a task. A successful creation returns 201 and a Location header identifying the new resource. Repeating an unprotected create request can create another item. **In the lab:** Create a task with a title and a Boolean completed field. Inspect the returned ID, then issue GET for that ID. Confirm the stored result rather than assuming the request body is proof of a write. **Try it:** Create a task, then read it by its returned ID. **Check your understanding:** What proves creation in this exercise? 1. A 201 response and the stored task 2. Only the text you typed 3. A green editor border **Answer:** A 201 response and the stored task. Verify both the server response and resulting state. ## 8. Update only the needed fields Requests PATCH applies a partial modification according to the server’s patch format. There are several patch formats; this lab uses a simple object containing fields to replace. It is not a universal implementation of JSON Patch or Merge Patch. **In the lab:** PATCH /tasks/1 with {"completed":true} preserves the title. A misspelled field is rejected rather than silently modifying a different property. **Try it:** Complete task 1 and inspect its unchanged title. **Check your understanding:** The lab PATCH body must include… 1. Every task in the collection 2. Only supported fields to change 3. The whole database **Answer:** Only supported fields to change. This teaching contract supports partial field updates. ## 9. Delete and handle an empty body Requests A successful DELETE may return 204 No Content. A 204 response has no response content, so blindly parsing it as JSON is an error in many clients. Other APIs can use different successful status codes; follow their contract. **In the lab:** The lab removes one task and returns a null internal body marker rendered as “No content”. A second DELETE of the same ID returns 404. The status changed, but the desired absent state remains. **Try it:** Delete a task, then repeat the request and compare status and state. **Check your understanding:** Should a client always call response.json() after 204? 1. Yes 2. Only for DELETE 3. No **Answer:** No. Handle a no-content response without attempting to parse JSON. ## 10. Status and transport are different Responses HTTP error responses still come from a responding server. A network failure can occur before an HTTP response exists. Browser fetch generally resolves for HTTP errors such as 404; it rejects for certain transport failures. Check response.ok or status before trusting the body. **In the lab:** The lab’s network-fault option uses status 0 as an internal display marker meaning “no HTTP response”. It is not an HTTP status sent by a server. The 503 fault represents an actual simulated HTTP failure. **Try it:** Compare the network fault with the service-unavailable fault. **Check your understanding:** Does fetch automatically reject every HTTP 404? 1. No 2. Yes 3. Only if the body is JSON **Answer:** No. A received HTTP error response must be checked by the client. ## 11. Authentication and authorization Responses Authentication identifies or verifies a caller; authorization decides what that caller may do. A credential being present does not imply permission for every operation. Never place a real secret into a public tutorial or client-side demo. **In the lab:** Bearer demo-token is a public fictional write credential here. Bearer readonly-token triggers a 403 for writes. Missing or different credentials produce 401. Real providers may use different details. **Try it:** Compare writes with no token, the read-only token and the demo write token. **Check your understanding:** A known read-only caller denied a write is primarily… 1. A JSON syntax problem 2. An authorization problem 3. A pagination problem **Answer:** An authorization problem. The caller lacks the required permission for that action. ## 12. Validation explains the repair Responses Client-side validation helps catch obvious mistakes, but the server must validate independently. Distinguish a malformed representation from a well-formed body that violates the API’s rules. Read the response’s error details and change the relevant field. **In the lab:** The lab uses 400 for malformed JSON, 415 for an unsupported content type and 422 for invalid task fields. These are teaching choices consistent with this contract, not a promise that every service uses the same codes. **Try it:** Create a blank title, inspect the error and repair it. **Check your understanding:** A syntactically valid blank title fails which layer? 1. Network transport 2. CSS styling 3. Field validation **Answer:** Field validation. The JSON parses, but the required field value is unacceptable. ## 13. Pagination changes what you see Reliability An API may divide a collection into pages. One response is not necessarily the whole dataset. Understand whether pagination uses page numbers, offsets or cursors; avoid assuming they are interchangeable. Concurrent updates can also affect what pages contain. **In the lab:** This fixture uses page and limit, plus nextPage. With three tasks and limit=2, page 1 returns two items and page 2 returns the third. That is a deliberately simple static paging model. **Try it:** Request page 2 with limit 2 and compare items with total. **Check your understanding:** Two returned items prove the collection contains only two items… 1. No 2. Yes 3. Only with GET **Answer:** No. Inspect pagination metadata rather than equating page size with total size. ## 14. Retry with a reason Reliability Retries can help recover from transient failures but can also amplify load or duplicate writes. Classify the failure first, use limits and follow relevant response guidance. A missing credential or invalid body usually needs a repair, not an identical retry. **In the lab:** The simulated 429 includes Retry-After: 30. The lab does not wait or automatically retry; it lets you inspect the decision. A timeout after a real write can leave the result uncertain, unlike this lab’s pre-processing network fault. **Try it:** Inspect the rate-limit response and describe a bounded retry policy. **Check your understanding:** A malformed body should usually be… 1. Retried forever 2. Corrected before retrying 3. Sent ten times quickly **Answer:** Corrected before retrying. Repeating invalid input does not fix the contract violation. ## 15. Make duplicate behavior explicit Reliability Idempotency means repeated requests have the intended effect of one request, as defined for the operation. Some APIs support an idempotency key for creations, but this is a server feature with specific retention and comparison rules. A client cannot make an unsupported key work by merely adding it. **In the lab:** This lab stores POST creation results by Idempotency-Key. Reusing the same key with the same content replays the result; changing the content produces 409. The cache lasts until the lab is reset. **Try it:** Repeat a POST with the same key, then change the title without changing the key. **Check your understanding:** An idempotency header works on every API automatically… 1. Yes 2. Only with JSON 3. No **Answer:** No. The server must implement and document the feature. ## 16. Build a dependable client Reliability A useful client separates request construction, transport, status checks, parsing, validation and presentation. Keep credentials out of shared source and logs. Handle empty responses and error details deliberately rather than assuming every response is a successful JSON object. **In the lab:** The export panel produces fetch and Apps Script examples for the displayed request. They target example.invalid until you adapt them to an approved real API. The snippets illustrate structure; they are not production integrations or complete authentication implementations. **Try it:** Export a successful exchange and an error exchange for your learning notes. **Check your understanding:** Before adapting an exported request, you should… 1. Read the real API contract and configure an approved endpoint 2. Assume the simulator is a real server 3. Paste a secret into the public demo **Answer:** Read the real API contract and configure an approved endpoint. Real endpoints, credentials, authorization, CORS and error behavior must be verified separately. ## Practice missions ### 1. Read the collection Send GET /tasks and inspect its pagination metadata. ### 2. Filter Open tasks Send GET /tasks?status=open and confirm every returned item is unfinished. ### 3. Reach page two Send GET /tasks?page=2&limit=2 using the initial sample collection. ### 4. Create a task Use POST /tasks with JSON, the demo write credential and a non-empty title. ### 5. Handle permission denial Attempt a write using Bearer readonly-token and observe a 403 with no mutation. ### 6. Update a field Use PATCH /tasks/1 with {"completed":true}; preserve the title. ### 7. Delete without JSON Use DELETE on an existing task and inspect a 204 with no content. ### 8. Prevent a duplicate creation Repeat the same successful POST using the same Idempotency-Key and receive a replayed result. ## Continue learning - [HTTP overview](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/Overview) - [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) - [Apps Script UrlFetchApp](https://developers.google.com/apps-script/reference/url-fetch/url-fetch-app) ## Your progress Lesson checks, mission completions and notes are saved in this browser when storage is available. Export progress for a portable backup. The fictional database and request history reset on reload. Saved guides in the directory are bookmarks, not completion records.