api.macomb.io

Macomb.io REST API — help guide for student assignments. All endpoints return JSON.

⚠ HTTP Only Because of the complexity of handling HTTPS in client applications, this API is currently only available over HTTP. Always use http://api.macomb.io in your code and API testing tools. Do not attempt to use https://api.macomb.io as it will not work and may cause confusion.

⚠ Before you start Any changes made via POST requests are saved in memory only and will be lost when the server restarts.
Please do not submit sensitive information or inappropriate content.

Jokes

The jokes endpoint lets you fetch random jokes and add your own to the server.

Base URL

http://api.macomb.io/jokes

GET Fetch random jokes — optional query params to filter

POST Add a new joke — send a JSON body

Getting jokes

Send a GET request to fetch one or more random jokes. Without any parameters you get one joke chosen at random from all categories.

Request

http://api.macomb.io/jokes

Response

{
  "count": 1,
  "jokes": [
    {
      "id": 7,
      "category": "programming",
      "setup": "Why did the developer go broke?",
      "punchline": "Because they used up all their cache."
    }
  ]
}

Fields to parse

Field	Type	Description
`count`	number	How many jokes were returned
`jokes`	array	The list of jokes
`jokes[i].id`	number	Unique ID of the joke
`jokes[i].category`	string	Category the joke belongs to
`jokes[i].setup`	string	The setup line of the joke
`jokes[i].punchline`	string	The punchline

Query parameters — both optional and combinable

Parameter	Type	Default	Description
`count`	number	1	How many jokes to return. Min 1, max 10.
`category`	string	all	Filter by category.

Available categories: programming, general, math

Example requests

http://api.macomb.io/jokes
http://api.macomb.io/jokes?count=3
http://api.macomb.io/jokes?category=programming
http://api.macomb.io/jokes?count=5&category=math

If you request more jokes than exist in a category, the server returns however many it has — it won't error out.

Adding a joke (POST)

Send a POST request with a JSON body to add your own joke. Once added, it can be returned by future GET requests.

Request body

{
  "category": "programming",
  "setup": "Why did the programmer quit his job?",
  "punchline": "Because he didn't get arrays."
}

Required fields

Field	Type	Valid values
`category`	string	`programming`, `general`, `math`
`setup`	string	Any non-empty string
`punchline`	string	Any non-empty string

Response — success (HTTP 201)

{
  "message": "joke added successfully",
  "joke": {
    "id": 16,
    "category": "programming",
    "setup": "Why did the programmer quit his job?",
    "punchline": "Because he didn't get arrays."
  }
}

The server assigns the id automatically. Check the response to see what ID your joke was given.

Error responses

All errors use the same shape:

{ "error": "description of what went wrong" }

HTTP Status	Reason
400	Missing `category`, `setup`, or `punchline`
400	Invalid `category` value
400	Invalid JSON body
405	Wrong HTTP method

Testing without writing code

Open these in your browser (GET only):

http://api.macomb.io/jokes
http://api.macomb.io/jokes?count=3
http://api.macomb.io/jokes?category=programming

Using curl (Git Bash, WSL, or PowerShell):

curl http://api.macomb.io/jokes
curl "http://api.macomb.io/jokes?count=3"
curl "http://api.macomb.io/jokes?category=programming"
curl -X POST http://api.macomb.io/jokes \
     -H "Content-Type: application/json" \
     -d "{\"category\":\"general\",\"setup\":\"Why did the bike fall over?\",\"punchline\":\"Because it was two tired.\"}"

Things to watch out for

jokes is always an array — even when count is 1, you still need to index into [0]. Never assume the response is a single object.
JSON strings include quote marks — string values are wrapped in " characters you need to strip before displaying or storing them.
Jokes are random — the server shuffles before picking, so you will get different jokes each time. Don't write code that assumes a specific joke will come back.
In-memory only — jokes added via POST disappear if the server restarts. This is expected.

Trivia

The trivia endpoint lets you fetch random multiple choice questions and add your own questions to the server.

Base URL

http://api.macomb.io/trivia

GET Fetch random questions — optional query params to filter

POST Add a new question — send a JSON body

Getting questions

Send a GET request to fetch one or more random trivia questions. Without any parameters you get one question chosen at random from all categories and difficulty levels.

Request

http://api.macomb.io/trivia

Response

{
  "count": 1,
  "questions": [
    {
      "id": 4,
      "category": "programming",
      "difficulty": "medium",
      "question": "What is the output of: int x = 5; cout << x++;",
      "answer": "5",
      "choices": [ "6", "Undefined", "5", "4" ]
    }
  ]
}

Fields to parse

Field	Type	Description
`count`	number	How many questions were returned
`questions`	array	The list of questions
`questions[i].id`	number	Unique ID of the question
`questions[i].category`	string	Category the question belongs to
`questions[i].difficulty`	string	`easy`, `medium`, or `hard`
`questions[i].question`	string	The trivia question text
`questions[i].answer`	string	The correct answer
`questions[i].choices`	array of strings	Four possible answers (order is random)

Query parameters — all optional and combinable

Parameter	Type	Default	Description
`count`	number	1	How many questions to return. Min 1, max 10.
`category`	string	all	Filter by category.
`difficulty`	string	all	Filter by difficulty level.

Available categories: programming, math, science, history
Available difficulties: easy, medium, hard

Example requests

http://api.macomb.io/trivia
http://api.macomb.io/trivia?count=5
http://api.macomb.io/trivia?category=programming
http://api.macomb.io/trivia?difficulty=easy
http://api.macomb.io/trivia?category=science&difficulty=hard
http://api.macomb.io/trivia?category=history&count=3
http://api.macomb.io/trivia?category=math&difficulty=medium&count=2

Adding a question (POST)

Request body

{
  "category": "science",
  "difficulty": "easy",
  "question": "What is the powerhouse of the cell?",
  "answer": "Mitochondria",
  "choices": [ "Mitochondria", "Nucleus", "Ribosome", "Golgi apparatus" ]
}

Required fields

Field	Type	Rules
`category`	string	Must be `programming`, `math`, `science`, or `history`
`difficulty`	string	Must be `easy`, `medium`, or `hard`
`question`	string	Any non-empty string
`answer`	string	Must exactly match one of the entries in `choices`
`choices`	array of strings	Must contain exactly 4 options

Response — success (HTTP 201)

{
  "message": "question added successfully",
  "question": {
    "id": 30,
    "category": "science",
    "difficulty": "easy",
    "question": "What is the powerhouse of the cell?",
    "answer": "Mitochondria",
    "choices": [ "Mitochondria", "Nucleus", "Ribosome", "Golgi apparatus" ]
  }
}

Error responses

{ "error": "description of what went wrong" }

HTTP Status	Reason
400	Missing required fields
400	Invalid `category` or `difficulty` value
400	`choices` does not contain exactly 4 options
400	`answer` does not match any entry in `choices`
400	Invalid JSON body
405	Wrong HTTP method

Testing without writing code

curl http://api.macomb.io/trivia
curl "http://api.macomb.io/trivia?count=5"
curl "http://api.macomb.io/trivia?category=programming&difficulty=easy"
curl -X POST http://api.macomb.io/trivia \
     -H "Content-Type: application/json" \
     -d "{\"category\":\"science\",\"difficulty\":\"easy\",\"question\":\"What is the powerhouse of the cell?\",\"answer\":\"Mitochondria\",\"choices\":[\"Mitochondria\",\"Nucleus\",\"Ribosome\",\"Golgi apparatus\"]}"

Things to watch out for

questions is always an array — even when count is 1, you still need to index into [0].
choices is also an array — you need to loop through it separately after parsing the question object.
choices order is random every time — never assume the correct answer is at a fixed position. Always use the answer field.
answer must match choices exactly on POST — capitalization and spacing must match precisely.
JSON strings include quote marks — strip " characters before displaying or storing values.
In-memory only — questions added via POST disappear if the server restarts. This is expected.

Currency

The currency endpoint lets you look up supported currencies, convert between any two of them, and add your own currency rates to the server.

Base URL

http://api.macomb.io/currency

GET No params: list all currencies | With from + to: convert an amount

POST Add or update a currency rate — send a JSON body

Listing all currencies

Send a plain GET request with no query parameters and you get back every currency the server knows about.

http://api.macomb.io/currency

Response

{
  "count": 20,
  "currencies": [
    { "code": "USD", "name": "US Dollar", "symbol": "$",  "rate_usd": 1.0  },
    { "code": "EUR", "name": "Euro",       "symbol": "€",  "rate_usd": 0.92 }
  ]
}

The rate_usd field tells you how many units of that currency equal one US Dollar. For example, "rate_usd": 0.92 means 1 USD = 0.92 EUR.

Fields to parse

Field	Type	Description
`count`	number	Total number of currencies returned
`currencies`	array	List of currency objects
`currencies[i].code`	string	3-letter currency code (e.g. `USD`, `EUR`)
`currencies[i].name`	string	Full name of the currency
`currencies[i].symbol`	string	Currency symbol (e.g. `$`, `€`, `£`)
`currencies[i].rate_usd`	number	Units of this currency per 1 USD

Supported currencies (20 total)

Code	Currency	Code	Currency
USD	US Dollar	KRW	South Korean Won
EUR	Euro	SEK	Swedish Krona
GBP	British Pound	NOK	Norwegian Krone
JPY	Japanese Yen	DKK	Danish Krone
CAD	Canadian Dollar	NZD	New Zealand Dollar
AUD	Australian Dollar	SGD	Singapore Dollar
CHF	Swiss Franc	HKD	Hong Kong Dollar
CNY	Chinese Yuan	ZAR	South African Rand
INR	Indian Rupee	AED	UAE Dirham
MXN	Mexican Peso	BRL	Brazilian Real

Note: These are approximate fixed rates loaded at server startup — not live market data. Think of them as reasonable estimates for learning purposes.

Converting between currencies

Add from and to query parameters to perform a conversion. amount is optional and defaults to 1. Currency codes are case-insensitive.

Example requests

http://api.macomb.io/currency?from=USD&to=EUR&amount=100
http://api.macomb.io/currency?from=GBP&to=JPY&amount=50
http://api.macomb.io/currency?from=CAD&to=MXN&amount=200
http://api.macomb.io/currency?from=EUR&to=INR

Response

{
  "conversion": {
    "from": "USD",
    "to": "EUR",
    "amount": 100.0,
    "result": 92.0,
    "rate": 0.92,
    "from_symbol": "$",
    "to_symbol": "€"
  }
}

Fields to parse

Field	Type	Description
`conversion.from`	string	Source currency code
`conversion.to`	string	Target currency code
`conversion.amount`	number	The amount you sent in
`conversion.result`	number	The converted amount (4 decimal places)
`conversion.rate`	number	How many `to` units equal 1 `from` unit
`conversion.from_symbol`	string	Symbol for the source currency
`conversion.to_symbol`	string	Symbol for the target currency

How the math works

The server converts everything through USD as a middle step:

amount ÷ from_rate  =  USD equivalent
USD equivalent × to_rate  =  final result

So converting 100 GBP to JPY would be:

100 ÷ 0.79 = 126.58 USD
126.58 × 149.50 = 18,923.71 JPY

You can verify your program got it right by doing this math yourself.

Adding a currency (POST)

You can add a new currency or update the rate of an existing one by sending a POST request with a JSON body.

Request body

{
  "code": "PLN",
  "name": "Polish Zloty",
  "symbol": "zł",
  "rate_usd": 3.94
}

Required fields

Field	Type	Description
`code`	string	3-letter currency code (automatically uppercased)
`name`	string	Full name of the currency
`symbol`	string	Currency symbol
`rate_usd`	number	How many units of this currency equal 1 USD (must be positive)

Response — new currency added (HTTP 201)

{
  "message": "currency added successfully",
  "currency": { "code": "PLN", "name": "Polish Zloty", "symbol": "zł", "rate_usd": 3.94 }
}

Response — existing currency updated (HTTP 201)

{
  "message": "currency rate updated successfully",
  "currency": { "code": "EUR", "name": "Euro", "symbol": "€", "rate_usd": 0.94 }
}

Notice the message field tells you whether a new currency was added or an existing one was updated. Your program should read this field — don't assume one or the other.

Error responses

{ "error": "description of what went wrong" }

HTTP Status	Reason
400	Missing required fields
400	`rate_usd` is zero or negative
400	Invalid JSON body
405	Wrong HTTP method

Testing without writing code

curl http://api.macomb.io/currency
curl "http://api.macomb.io/currency?from=USD&to=EUR&amount=100"
curl "http://api.macomb.io/currency?from=GBP&to=JPY&amount=50"
curl -X POST http://api.macomb.io/currency \
     -H "Content-Type: application/json" \
     -d "{\"code\":\"PLN\",\"name\":\"Polish Zloty\",\"symbol\":\"zł\",\"rate_usd\":3.94}"
curl "http://api.macomb.io/currency?from=USD&to=PLN&amount=10"

Things to watch out for

Two different JSON shapes from the same URL — a GET with no params returns a currencies array; a GET with from/to returns a conversion object. Use separate functions for each.
amount defaults to 1 — if you omit it, the result field will just be the exchange rate itself.
Rates are not live — the server uses fixed approximate rates. Do not use this for anything financial.
In-memory only — currencies added via POST disappear if the server restarts. This is expected.
result is rounded to 4 decimal places, rate to 6 — consider rounding your display output.