Author: meowmeowscratch

An API is how one program asks another program for data or tells it to do something. In this guide, you will see what is inside that conversation and make a real API request—without needing to write a program first.

By the end, you will have created a private temperature API, sent it a reading and read the result back. You will also know what URLs, methods, headers, JSON and status codes are doing in the commands you run.

The shortest useful definition

API stands for application programming interface. The name sounds abstract, but the basic idea is simple: an API is a defined way for software systems to communicate.

Imagine a weather display that needs the latest temperature. The display does not need access to the weather station’s database or source code. It sends a request to an agreed address, and the API returns a response in an agreed format.

• Request: “Give me the latest readings.”
• Endpoint: the API address that receives the request.
• Response: the status and data returned by the API.

That request–response loop is the foundation of weather apps, payment systems, smart-home devices, dashboards and most modern web services.

YOUR CLIENT                         API
(terminal, app or device)           (the service)

      POST /readings/
      headers + JSON
             ──────────────────────►
                                    authenticate
                                    validate
                                    create record
             ◄──────────────────────
      201 Created
      status + JSON

A useful analogy—and where it stops

An API is often compared with ordering at a counter. You choose from a defined menu, make a specific request and receive either what you ordered or an explanation of the problem. You do not walk into the kitchen and operate the equipment yourself. In the same way, an API exposes specific operations without giving a client direct access to the service’s database or internal code.

The analogy stops there. Software does not infer what you meant, overlook a spelling mistake or negotiate an alternative. The URL, method, credentials and data must follow the API’s contract precisely. That strictness is what lets many different clients receive predictable results.

The five parts you can see

An HTTP API request usually has five parts. You do not need to memorise them yet; just learn to recognise them.

Part	What it means	Example
URL	Where the request is sent	/weather-station/readings/
Method	What kind of action you want	GET or POST
Headers	Extra context, including authentication and content type	Authorization: Bearer …
Body	The data sent with a write request	{"temperature":22.5}
Status	The numeric result returned by the API	201 Created

The request contains the first four parts. The status is part of the response. A response will often include a body as well, usually formatted as JSON.

Methods are verbs

The HTTP method tells the API what sort of operation you intend to perform. These are the methods you will see most often:

Method	Purpose	Plain-English example
GET	Read data	Show me the temperature readings.
POST	Create data	Add this new temperature reading.
PUT	Replace a resource	Replace this settings document with the supplied version.
PATCH	Update part of something	Change this reading to 23.
DELETE	Remove something	Delete this reading.

The URL identifies a resource; the method identifies the action. The same record URL can therefore support a GET to read it, a PATCH to change it and a DELETE to remove it.

JSON is the message format

APIs need a predictable way to represent data. Meow Meow Scratch®, like many web APIs, uses JSON. A temperature reading looks like this:

{
  "data": {
    "temperature": 22.5
  }
}

JSON uses named keys and values. Here, data contains an object, and that object has a temperature value of 22.5. Quotes matter, braces must match and numbers are not placed inside quotes.

Build your first API

This exercise creates a private Weather Station app with a Readings collection. Each record will contain one numeric temperature. No Raspberry Pi or other hardware is required.

Before you start

• A Meow Meow Scratch account
• A terminal with curl
• About 10 minutes

The commands below use macOS, Linux, Git Bash or WSL shell syntax. Git Bash is the simplest way to run them unchanged on Windows. PowerShell uses different syntax for environment variables and line continuation.

1. Create the app and collection

Sign in to the web app, then create the following resources. Enter the slugs exactly as shown because they become part of the API URL.

1. Open Apps → New App. Set the name to Weather Station and the slug to weather-station.
2. Open the new app and choose New Endpoint. Set the name to Readings, the slug to readings and the type to Collection.
3. Open the endpoint and choose Add Field. Use the label Temperature, key temperature and type Number. Enable Required.

Keep the app private. Private is the safe default for learning because every request must prove that it has permission.

2. Create a restricted API key

Inside Weather Station, open API Keys → New API Key. Name it API tutorial, enable both Read and Write, then copy the value when it appears. The complete value is shown once.

Use an app API key here—not a platform token. An app key is restricted to one app, so it gives this exercise only the access it needs.

Treat an API key like a password. Do not paste a real token into source code, chat, screenshots or a public repository.

In your terminal, set three reusable values. Replace both placeholders, but keep the quotation marks:

export MEOW_APP_API_KEY="YOUR_APP_API_KEY"
export MEOW_USERNAME="YOUR_USERNAME"
export MEOW_API="https://meowmeowscratch.com/api"

Environment variables save you from repeating the key and username in every command. They last for the current terminal session.

3. Create a temperature reading with POST

Before running the next command, predict what it should do: the method is POST, the URL ends in records/, and the JSON body contains one temperature. It should create one record.

curl -i -X POST \
  "$MEOW_API/apps/weather-station/endpoints/readings/records/" \
  -H "Authorization: Bearer $MEOW_APP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data":{"temperature":22.5}}'

A successful response starts with 201 Created. Its JSON body will have this shape; your UUID and timestamps will be different:

HTTP/... 201 Created

{
  "uuid": "…",
  "data": {
    "temperature": 22.5
  },
  "created_at": "…",
  "updated_at": "…"
}

201 means the API accepted the request and created a new resource. The UUID is the stable identifier for this particular record.

4. Read the collection with GET

Now use the collection’s consumer URL to read the record back. GET is curl’s default method, so the command does not need -X GET.

curl -i \
  "$MEOW_API/v1/$MEOW_USERNAME/weather-station/readings/" \
  -H "Authorization: Bearer $MEOW_APP_API_KEY"

A successful response starts with 200 OK and includes both the collection schema and its records:

HTTP/... 200 OK

{
  "count": 1,
  "fields": [
    {
      "name": "temperature",
      "label": "Temperature",
      "field_type": "number"
    }
  ],
  "records": [
    {
      "uuid": "…",
      "data": {
        "temperature": 22.5
      },
      "created_at": "…"
    }
  ]
}

If your collection already contains other records, count will be higher and the records array will be longer. That is expected.

Read the curl command in plain English

Part	Meaning
curl	Run the command-line HTTP client.
-i	Show response headers and the status as well as the JSON body.
-X POST	Use the POST method.
-H	Add a header to the request.
Authorization: Bearer …	Present your API key so the private endpoint can check your access.
Content-Type: application/json	Tell the API that the request body is JSON.
-d	Send the JSON that follows as the request body.
\	Continue the same shell command on the next line.

Make the API reject bad data

An API is useful not only because it accepts data, but because it applies consistent rules. You defined temperature as a Number. Send the word "warm" instead:

curl -i -X POST \
  "$MEOW_API/apps/weather-station/endpoints/readings/records/" \
  -H "Authorization: Bearer $MEOW_APP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data":{"temperature":"warm"}}'

You should receive a 400 validation response. That is a successful demonstration of the schema doing its job: invalid data was rejected before it could enter the collection.

How to interpret status codes

Status codes are compact summaries. The first digit gives you the broad result:

• 2xx: the request succeeded.
• 4xx: something about the request, credentials or target needs attention.
• 5xx: the server could not complete an otherwise valid request.

Status	Meaning	First thing to check
200 OK	A read or update succeeded	Inspect the returned JSON.
201 Created	A new resource was created	Save the returned UUID if you need the record later.
204 No Content	A delete succeeded	An empty body is expected.
400 Bad Request	The input is invalid	Check the JSON, field names and value types.
401 Unauthorized	Authentication is missing or invalid	Check that the key was copied correctly and the Bearer header is present.
403 Forbidden	The credential is known but not permitted	Check the key’s Read or Write scope and app.
404 Not Found	The resource does not exist at that URL	Check the username, slugs and path.
429 Too Many Requests	The client is being rate limited	Slow down and retry with backoff.

Common mistakes

• Missing the trailing slash: Meow API routes are slash-terminated. Use /records/, not /records, to avoid a redirect—especially with POST, PATCH and DELETE.
• Using the wrong key: an app API key works only with its app and its enabled scopes. Account-wide automation normally uses a platform token.
• Putting a number in quotes: 22.5 is a JSON number; "22.5" is text.
• Changing the example slugs: if you choose different slugs in the web app, you must also change them in every URL.
• Copying spaces into environment variables: write NAME="value", with no spaces around the equals sign.
• Hiding the useful error: keep -i while learning so you can see the HTTP status and headers.

API, website and database: what is the difference?

A website is primarily an interface for people. A database stores structured information. An API is an interface that software can use. A single product often has all three: you configure a collection in a website, its records are stored in a database, and a device reads or writes them through an API.

The API creates a controlled boundary. A client can do only what the documented endpoints, credentials and validation rules allow; it does not receive unrestricted access to the database underneath.

Try three small experiments

1. Send another POST with the temperature set to 18.4, then GET the collection again. Confirm that the count increases.
2. Add ?temperature__gte=20 to the end of the GET URL. Predict which record will remain before running the command.
3. Open Request Logs in the Readings endpoint. Find your GET request and compare its method, status and response time with what curl displayed.

Changing one thing at a time is one of the fastest ways to learn an API. Make a prediction, run the request, then use the status and response body to explain the result.

What you now know

You have defined a schema, used a restricted credential, sent JSON with POST, interpreted a 201 response, read records with GET and inspected a deliberate 400 validation error. Those same ideas carry into Python scripts, Raspberry Pi sensors, dashboards and AI tools.

Keep the Meow Meow Scratch REST API reference nearby when you build. When you are ready to stop writing raw curl commands, the open-source Meow SDK provides a Python client and command-line interface for the same resources.