ComputeSphereLearn
Console
Learning paths / Application foundations / APIs

Try it: call a public API, then a local one

Reading · 15 min · Module 2, lesson 4 of 520 min left in this module

Module 2 · APIsLesson 4 of 5

Goal: Use curl to call an API with headers and a JSON body, and read the status line of each response.

You need A terminal with curl, and Node 22.13 or later (Node 24 LTS recommended).

Check your tools, and curl on Windows

Run curl --version and node --version. macOS and Linux include curl; Windows 10 and 11 do too, as curl.exe. Node comes from nodejs.org; if node --version prints something older than v22.13.0, install the current LTS. Lesson 2.3.5 needs the same version.

In Windows PowerShell, curl on its own can run PowerShell's Invoke-WebRequest instead of the real curl, so type curl.exe everywhere this lesson says curl. Where quoting differs too, the step has a Windows tab.

  1. Call a public API

    GitHub's API describes any public repository, no key needed:

    curl https://api.github.com/repos/computesphere-samples/learn

    Find private, visibility and default_branch in the response too. Without a key, GitHub allows 60 calls an hour from your address, which is plenty here.

    You should seea JSON object, including "full_name": "computesphere-samples/learn" and "description": "Lab apps and starter code for ComputeSphere Learn."

  2. Read the status line and headers

    curl -I https://api.github.com/repos/computesphere-samples/learn

    x-ratelimit-remaining counts down with each call.

    You should seeHTTP/2 200, content-type: application/json; charset=utf-8, and x-ratelimit-limit: 60.

  3. Get the notes API and start it

    git clone https://github.com/computesphere-samples/learn.git
cd learn/labs/local-api
node server.js

    It's one file with no dependencies. Leave this terminal running and open a second one for the next steps.

    No git? Other ports?

    Download https://github.com/computesphere-samples/learn/archive/refs/heads/main.zip instead, unzip it, and open learn-main/labs/local-api in a terminal.

    If port 3000 is taken, start it with PORT=3001 node server.js (PowerShell: $env:PORT=3001; node server.js) and use 3001 below.

    You should seeNotes API on http://localhost:3000

  4. List the notes

    curl -i http://localhost:3000/notes

    -i prints the status line and headers above the body.

    You should seeHTTP/1.1 200 OK, Content-Type: application/json, and [{"id":1,"text":"Buy milk"}] after the headers.

  5. Create a note

    -H adds a header and -d sends a body, which also makes the request a POST.

    curl -i http://localhost:3000/notes -H "Content-Type: application/json" -d '{"text":"Call the bank"}'

    Run step 4 again and both notes are there.

    You should seeHTTP/1.1 201 Created and {"id":2,"text":"Call the bank"}

  6. Get two errors on purpose

    Send a note with no text, then ask for a note that doesn't exist:

    curl -i http://localhost:3000/notes -H "Content-Type: application/json" -d "{}"
curl -i http://localhost:3000/notes/99

    Check yourself

    You send the note from step 5 again, but leave out the -H header. What comes back?

    You should seeHTTP/1.1 400 Bad Request with {"error":"A note needs a non-empty \"text\" field"}, then HTTP/1.1 404 Not Found with {"error":"No note with that id"}.

  7. Stop the server

    Press Ctrl+C in the first terminal. The notes live in memory, so the next start begins with just "Buy milk" again.

    You should seeyour prompt again in the first terminal.