.png)
3 hours ago
1
Absolutely! Here’s a comprehensive, step-by-step README.md for your MetaObject Protocol/DSL API framework. You can copy and adapt this for your GitHub repo. It covers:
- What this is
- How it works
- How to install/run
- How to write routes.dsl
- Example client/server use
- Technical details
- How to contribute
- License
# MetaObject Protocol & DSL API Framework
A universal, extensible platform for defining, introspecting, and calling APIs using meta-objects and a simple domain-specific language (DSL).
> **Write APIs and data objects in a single DSL file, expose them instantly as endpoints, and use a browser playground to test, introspect, and round-trip object data.**
---
## 🚀 What is This?
MetaObject Protocol & DSL API Framework is a minimal but powerful toolkit for:
- Defining APIs and meta-objects with a single, readable DSL (`routes.dsl`)
- Exposing endpoints automatically (GET/POST with any parameters or objects)
- Serializing, sending, and reconstructing complex objects between browser and server
- Introspecting object structure and field values dynamically
- Building auto-documenting, schema-driven applications with zero lock-in
It works with **vanilla PHP and JavaScript**—no frameworks, no bloat, 100% open source.
---
## 📂 Project Structure
- `main.html` (or `index.html`): Interactive web client playground and API tester
- `MetaCompiler.php`: The universal meta-object engine and DSL runtime (backend)
- `routes.dsl`: Your API and object definitions in a human-friendly DSL
- `index.php` (or `router.php`): The router/server entry point
- `README.md`: (this file!)
- `LICENSE`: MIT license file
---
## 🔥 Quick Demo
### 1. Clone this repo and put it on a PHP server
### 2. Open `main.html` in your browser
You’ll see a DSL editor and API tester.
### 3. Try This DSL:
```dsl
let hello = (name) => "Hello, " . $name;
tag hello as api, get, path:/api_v1/hello;
let add = (a, b) => $a + $b;
tag add as api, post, path:/api_v1/add;
let greet_person = (person) => {
$obj = $person->get();
$name = $obj->get("name");
$age = $obj->get("age");
return [ "greeting" => "Hello $name, age $age" ];
};
tag greet_person as api, post, path:/api_v1/greet_person;
- /index.php?path=/api_v1/hello&name=Alice → Hello, Alice
- POST to /index.php?path=/api_v1/add with { "a": 2, "b": 3 } → 5
- POST to /index.php?path=/api_v1/greet_person with { "person": { "name": "Alice", "age": 30 } } → Hello Alice, age 30
-
Define a function: let name = (param1, param2) => { ... };
-
Expose as API: tag name as api, get, path:/api_v1/name; or tag name as api, post, path:/api_v1/name;
-
Handle objects: The argument will be a MetaVar (with its value a MetaObject). Use $obj = $param->get(); $obj->get("field") to access fields.
-
Return values or arrays: Anything returned will be JSON-encoded for the client.
let register = (user) => {
$obj = $user->get();
$username = $obj->get("username");
$email = $obj->get("email");
return [ "registered" => true, "user" => $username, "email" => $email ];
};
tag register as api, post, path:/api_v1/register;
- Loads all DSL/API definitions using MetaCompiler.php
- Receives HTTP requests (GET/POST) at /index.php?path=<route>
- Finds the matching endpoint
- Maps parameters/objects to MetaVars/MetaObjects
- Calls your DSL function
- Returns structured JSON, including meta-object descriptions
- Reads/parses your DSL, discovers all APIs
- Lets you fill out and submit arguments for each API
- Sends the request, displays JSON response and reconstructed object
- You can edit, resubmit, or auto-generate forms based on the introspected schema
- Supports nested/recursive objects (objects as fields)
- Objects can be described, introspected, and mutated live in JS or PHP
- Easy to extend: add permissions, validation, plugins, etc.
- Fork the repo, open issues/PRs!
- Improve docs, add examples, or port to other languages.
- Discuss new features in the Issues tab.
MIT License. (c) 2024 Shahaf Zemah
See LICENSE file for details.
- Project by [Shahaf Zemah]
- Build an admin panel with live object editing and validation
- Create a no-code business platform or rapid prototyping tool
- Use as a backend for multiplayer games or collaborative apps
- Create educational tools, auto-generated forms, or knowledge graphs
Simple GET:
let ping = () => "pong";
tag ping as api, get, path:/api_v1/ping;
POST with array:
let sum = (x, y) => $x + $y;
tag sum as api, post, path:/api_v1/sum;
POST with object:
let register = (user) => {
$u = $user->get();
return [ "username" => $u->get("username") ];
};
tag register as api, post, path:/api_v1/register;
If you like this project, give it a ⭐ on GitHub and share it with other makers and learners!
---
**How to use:**
- Copy-paste into your `README.md`
- Fill in the repo URL, your email, and (optional) more features/examples
This README should be enough for **anyone to use, extend, and understand your framework**.
If you want even more detail, visual diagrams, or a quickstart video, let me know!
