Skip to content
  • Official
  • Beginner
  • English
  • 11 steps · 2 quizzes

APIs Explained for Non-Developers: A Hands-On Lesson

API training for non-technical teams: send requests to a pretend help-desk API, read JSON, decode status codes, keys, rate limits and webhooks.

  • Free
  • No account needed
  • Stop any time, pick up where you left off
Workshopy.io

WorkshopyOfficial

78 lessons · used by 2 teachers

For teachers

Teaching this? Run it live with your class.

  • Students join with a code — no accounts
  • See who’s done and who’s stuck, step by step
  • It’s your copy — change anything before class

Sign in to copy it to your workspace. It’s free.

Your path

11 steps · 2 quizzes · open any step, or read it here

  1. Start here: what is an API actually doing?Start hereThis APIs explained lesson for non-developers starts with something you see every day: you press Sync, Save or Connect in one tool, and data shows up in another.InteractiveHands-on
    Read this step

    This APIs explained lesson for non-developers starts with something you see every day: you press Sync, Save or Connect in one tool, and data shows up in another. Behind that button, one program sent another a request and got a response back, and that exchange is what people mean by "the API".

    Interactive · What really happens when an app asks another app for data — try it in the lesson

    You just watched one request travel to a server and its response travel back. By the end of this lesson you'll be able to write that request yourself and read the answer.

    What you'll do

    • Send requests to a pretend help-desk API and watch each one travel and come back
    • Build a request part by part: method, endpoint, headers and body
    • Read JSON responses and find the value you need in them
    • Decode status codes, API keys, rate limits and webhooks, the words that come up when an integration breaks

    By the end you can

    • read an API's documentation and make a call from it
    • tell from a status code whether to fix your request, wait, or report a problem
    • talk to developers about an integration in their words

    Everything runs in this page: no coding background and no software needed.

  2. What an API is: one program asks, another answersAn API (application programming interface) is the set of requests a program agrees to answer, and the shape of each answer. When your CRM shows a customer's open support tickets, the CRM is not looking at the help desk's screen.InteractiveHands-on
    Read this step

    An API (application programming interface) is the set of requests a program agrees to answer, and the shape of each answer. When your CRM shows a customer's open support tickets, the CRM is not looking at the help desk's screen. It sends the help desk's API a request, such as "give me the tickets of customer 7", and gets the data back in a fixed format.

    You may have heard the waiter comparison: you (the app) don't walk into the kitchen (the server), you order from a menu (the API). It's a fair start, but three things matter more at work:

    • The menu is a contract. The API's documentation lists exactly what you may ask for and what the answer will look like. Ask for something not on it and you get an error, not a guess.
    • Every request is answered. Even a failure comes back with a status code that says what went wrong.
    • Nobody is looking at screens. No buttons, no layout: just data, so another program can use it.

    Most APIs you'll meet at work are web APIs: the request and the response travel over HTTP, the same protocol your browser uses to load pages.

    Try it: send all four requests below. Read the request on the left before you look at the response on the right.

    Interactive · Send a request to a pretend help desk and read what comes back — try it in the lesson

    Two of the four came back purple. Neither broke anything: the API answered with what went wrong.

    Takeaway: an API call is a request (what you want, sent by one program) and a response (a status and data, sent back by another).

  3. Anatomy of a request: method, endpoint, headers, bodyEvery web API request is built from the same few parts. Learn them once and you can read any API's documentation.InteractiveHands-on
    Read this step

    Every web API request is built from the same few parts. Learn them once and you can read any API's documentation.

    Part What it says Example
    Method What you want done GET (read), POST (create)
    Endpoint Which thing you mean: the API's base address plus a path https://api.deskly.example/v1 + /tickets/42
    Query (optional) Filters, after a ?, as name=value pairs joined by & ?status=open&priority=high
    Headers Notes on the envelope: who you are, what format you send Authorization: Bearer sk_live_…
    Body (optional) The data you send along, usually JSON { "subject": "Printer jammed" }

    A path usually names a collection (/tickets, all tickets) or one item in it (/tickets/42, the ticket with id 42). The v1 in the base address is the API's version: when the API changes in a way that would break old integrations, the owners often publish a v2 and keep v1 running for a while.

    Try it: build the three requests in the task list. Watch the request text change as you change each part.

    Interactive · Build a request, part by part — try it in the lesson

    Takeaway: method + endpoint say what you want and where; headers say who you are; the body carries data you send.

  4. Reading JSON: the language responses come back inMost web APIs answer in JSON (JavaScript Object Notation): plain text that people and programs can both read. It has only a few pieces: Objects in curly braces { }: pairs of a name in double quotes, a colon and a value, separated by commas.InteractiveHands-on
    Read this step

    Most web APIs answer in JSON (JavaScript Object Notation): plain text that people and programs can both read. It has only a few pieces:

    • Objects in curly braces { }: pairs of a name in double quotes, a colon and a value, separated by commas.
    • Lists (arrays) in square brackets [ ]: values in order, separated by commas.
    • Values: text in double quotes ("open"), numbers without quotes (42), true or false, and null, which means "nothing here".

    Objects and lists nest inside each other. A ticket can hold a customer object, and a list of comments where each comment is an object. Tools and docs point at a value with its path: customer.email is the email inside the customer object; comments[1].author is the author of the second comment, because lists count from 0.

    Try it: answer the four questions by pressing the right value in the response.

    Interactive · Find the answers in a JSON response — try it in the lesson

    Takeaway: read JSON from the outside in: find the object, then the name, then the value; in a list, the position counts from 0.

  5. HTTP methods: GET, POST, PUT, PATCH and DELETEThe method is the verb of the request. Five cover almost everythingInteractiveHands-on
    Read this step

    The method is the verb of the request. Five cover almost everything:

    Method What it does Typical answer
    GET Reads. Changes nothing on the server 200 OK
    POST Creates something new (or starts an action) 201 Created
    PUT Replaces a whole item with what you send 200 OK
    PATCH Changes only the fields you send 200 OK
    DELETE Removes an item 204 No Content

    Two ideas help when you plan an integration or read an incident report:

    • Safe: GET only reads, so calling it never changes data.
    • Idempotent: sending the same request twice ends in the same state as sending it once. GET, PUT and DELETE are; POST is not. That's why a "Create invoice" call retried after a timeout can make two invoices, and why many APIs let you send an idempotency key with a POST.

    Try it: press each method once, then press POST and DELETE a second time. Then compare PUT and PATCH on ticket 42.

    Interactive · Five methods on one list of tickets — try it in the lesson

    Takeaway: GET reads, POST creates, PUT replaces, PATCH edits, DELETE removes; repeat a POST and you may create twice.

  6. Check: requests, JSON and methodsQuiz · 4 questions
    Read the questions

    Question 1. In `GET https://api.deskly.example/v1/tickets?status=open`, which part is the filter?

    • `GET`
    • `/tickets`
    • `?status=open`

    Question 2. Which part of a request usually carries the API key?

    • The body
    • A header, such as Authorization
    • The method

    Question 3. In this response, what is the value of `customer.name`?

    • 7
    • Lena Park
    • billing

    Question 4. You want to change a ticket's priority and leave everything else as it is. Which method fits best?

    • `PUT`
    • `PATCH`
    • `POST`
  7. Status codes: what the three digits tell youEvery response starts with a three-digit status code. The first digit is the family, and the family already tells you who has to act: 2xx: it worked. 200 OK (here is your answer), 201 Created (something new exists), 204 No Content (done, nothing to send back).InteractiveHands-on
    Read this step

    Every response starts with a three-digit status code. The first digit is the family, and the family already tells you who has to act:

    • 2xx: it worked. 200 OK (here is your answer), 201 Created (something new exists), 204 No Content (done, nothing to send back).
    • 4xx: the request has a problem. 400 Bad Request (the server can't use what you sent, such as broken JSON or a missing field), 401 Unauthorized (missing or wrong key: the server doesn't know who you are), 403 Forbidden (it knows who you are, and you're not allowed), 404 Not Found (nothing at that address), 429 Too Many Requests (slow down).
    • 5xx: the server has a problem. 500 Internal Server Error means something broke on their side; your request may be fine.

    There are also 1xx (information) and 3xx (redirection) codes, which tools handle for you. When an integration fails, the code is the first thing to put in your message to a developer or to the vendor's support team, with the time it happened.

    Try it: sort the nine codes by what you'd do next.

    Interactive · Sort the status codes by what you do next — try it in the lesson

    Takeaway: 2xx worked, 4xx: change the request (or wait, for 429), 5xx: tell the API's owner.

  8. API keys: who is asking, and what they may doAn API needs to know who is calling before it answers. The most common way is an API key: a long secret string your account generates, sent in a header with every request (often Authorization: Bearer <key>; some APIs use a header such as X-API-Key).InteractiveHands-on
    Read this step

    An API needs to know who is calling before it answers. The most common way is an API key: a long secret string your account generates, sent in a header with every request (often Authorization: Bearer <key>; some APIs use a header such as X-API-Key). Some integrations use OAuth instead: you click "Allow" once, and the tool gets a token that works like a key with limits.

    A key is a password for a program. Whoever holds it can do everything the key allows, in your name. So:

    • Never paste a key into a chat, an email, a ticket, a shared document, a screenshot or a slide. Use your company's password manager or secrets vault to share one.
    • Give each key the least it needs. A dashboard that only reads needs a read-only key.
    • Replace (rotate) a key that leaked, straight away, in the API's settings. The old key stops working the moment it's replaced.

    Try it: send both requests with every key and fill in the table. Watch for the difference between 401 and 403.

    Interactive · Which key may do what: 401 or 403? — try it in the lesson

    Takeaway: 401 means "who are you?", 403 means "not for you"; treat every key like a password and replace one that leaked.

  9. Rate limits: why an API says 429 Too Many RequestsAPIs limit how many requests one key may send in a time window, such as 100 a minute or 10,000 a day. Limits protect the service from overload and share it fairly between customers.InteractiveHands-on
    Read this step

    APIs limit how many requests one key may send in a time window, such as 100 a minute or 10,000 a day. Limits protect the service from overload and share it fairly between customers. Go over the limit and you get 429 Too Many Requests, often with a Retry-After header that says how long to wait (usually a number of seconds). Many APIs also send headers that tell you how many requests you have left in the window; their names vary, so check the docs.

    At work this shows up as "the sync stopped halfway" or "the import failed for the last 300 rows". The fix is rarely a bigger limit: it's sending fewer requests (asking for lists instead of one item at a time) and waiting when told.

    Try it: send 20 requests a minute against a limit of 10 and press Run. Then tick Wait when told and run it again. Finally try a rate under the limit.

    Interactive · A rate limit of 10 requests a minute, two minutes of traffic — try it in the lesson

    Takeaway: a rate limit is a budget per time window; a tool that waits when told gets the same work done without a pile of refused calls.

  10. Webhooks vs polling: asking again or being toldHow does your tool find out that something happened in another tool, such as a payment arriving? Two ways: Polling: your tool asks the API again and again, "anything new?" Simple, but most answers are "no", and news waits until the next time you ask.InteractiveHands-on
    Read this step

    How does your tool find out that something happened in another tool, such as a payment arriving? Two ways:

    • Polling: your tool asks the API again and again, "anything new?" Simple, but most answers are "no", and news waits until the next time you ask.
    • Webhooks: you give the other service an address (a URL of your tool), and it sends a request to that address the moment the event happens. One call per event, no waiting.

    Webhooks are why a payment can post to a channel within seconds. The price: your tool needs an address the service can reach, and it should check that each call really came from that service (many services sign their webhooks with a shared secret for this).

    Try it: move the slider to set how often your tool polls, and press Play the hour to watch three payments arrive.

    Interactive · One hour, three payments: polling against a webhook — try it in the lesson

    Takeaway: polling trades empty requests against delay; a webhook tells you once, when it happens.

Comments

You’ll sign in with Google before it’s posted.Comments are public — don’t name your students.
0 / 1,500

No comments yet. Be the first to say how it went.

Using it

Workshopy shares this lesson under CC BY 4.0. Anyone may use and change it, with credit to you. Anyone can learn it here, free. A copy in your workspace is yours to change and run live; your students never need an account.

Versions

  1. 1

    Version 1Current

    · First published

Copies are made from the current version. A copy you already have doesn’t change.

More from Workshopy

All 78 lessons