MARS Engine Docs

Appearance

Hello MARS Engine Tour ​

Welcome to MARS Engine!
This lightning‑tour walks you through building and testing the classic “Hello, World!” API, while showing off a few MARS super‑powers.

1  Create a new project ​

  1. Log in to your MARS workspace and click ➕ New Project.
  2. Pick a name (e.g. hello‑world‑tour) and hit Create.

Your project appears with an empty filesystem to the left.

Right click in the filesystem area, Add new folder, name it api and press Enter to create the folder.

2  Add your first API file ​

  1. Right‑click api ▸ New File ▸ API.
  2. Name it hello (the extension doesn’t matter).

Paste the snippet below and press Ctrl + S to save.

js
// /api/hello
write('message', 'Hello, World!');   // 👋 simplest possible response

What just happened? ​

  • write() is MARS’ universal output function.
    With two arguments write(key, value) builds a JSON response:

    json
    { "message": "Hello, World!" }

  • Every API file runs inside an implicit transaction and auto‑commits when it finishes without errors.

3  Run the API ​

Click the ▶︎ Run button (or open http(s)://<your‑host>/api/hello) and you should see:

json
{ "message": "Hello, World!" }

4  Personalise with param() ​

Let’s greet the caller by name:

js
// /api/hello
const name = param('name', 'World');      // fallback if not supplied
write('message', `Hello, ${name}!`);

Call /api/hello?name=Alex → { "message": "Hello, Alex!" }

  • param() fetches parameters no matter how they were sent
    (query‑string, JSON body, form‑data, etc.).
  • The second argument is an optional default.

5  Plain‑text output & custom headers ​

js
header('content-type', 'text/plain');     // must come before write()
write(param('name', 'World'));

Now /api/hello returns raw text/plain.

6  Persist greetings in the database ​

js
const name = param('name', 'World');
const inserted = db.query(
  'INSERT INTO greetings (gre_name) VALUES (?)',
  name
);

write('status', 'OK');
write('inserted', inserted);
  • db.query() runs prepared statements automatically.
  • For INSERT and UPDATE, db returns an array of affected row IDs, such as [{ id: 1 }, { id: 2 }].

7  Quick extras ​

FeatureOne‑linerDocs
Abort earlyexit();Terminate execution
Hash a passwordconst hash = bcrypt(pass);Bcrypt
WebSocketFile type WebSocket with onMessage()WebSockets

8  Next steps ​

  • Explore Input, Output, Database, and Sessions sections in the left sidebar.
  • Clone this project and add authentication, validation, or Firebase push notifications.
  • Join the community forum if you get stuck- we’re friendly!

Happy coding with MARS Engine 🚀