Learn the basics in 30 minutes.
Prerequisites
This tutorial requires you to have a running karma instance ready. More about how tu run karma here.
Default Karma Models
The following concepts constitute the basic building blocks of karma.run.
Tags
When you create a model, you have the possibility to assign a human-readable name to it. This identifier string lives in a default collection, itself tagged as _tag
and must be unique. A new karma instance has the preconfigured tags _tag
, _model
, _expression
, _user
, _role
and _migration
which point to the corresponding model.
Model
Models are type definitions. They describe how an object of a certain kind looks. Each model you create gets its own collection to store object of its kind. Thy can be found under the tag _model
Expressions
Expressions are KVM (karma virtual machine) programs represented as data. They follow karma's built-in expression model found under tag _expression
. Persistent expressions live in this model's collection.
Users
Contains user which have access to the database. The user model has the tag _user
Roles
Roles are conected to the permission expression for create, read, update, delete. The user model has the tag _role
Migrations
A migration is a small object that binds an expression to two models: from and to. The migration model has tag _migration
.
Example Queries:
let's examine some of these default contents now. For the followin examples, we will communicate directly with the API and use the json
Codec. We assume that karma runs under the URL http://localhost:8080
First we need to authenticate to the karma instance. We do that with the 'admin' user and your instance secret.
To authenticate, send a POST request to:
URL: http://localhost:8080/auth
Method: POST
Headers:
X-Karma-Codec: json
Body:
{
"username": "admin",
"password": "<your instance secret>"
}
When you authenticate successfully, you receive an HTTP status of 200 OK and a single string (encoded by your codec) as response. This string is your signature. You may now access other endpoints by providing this (base64-encoded) signature as X-Karma-Signature
header.
After that we are ready to query against the api. Lets post a Query:
URL: http://localhost:8080/
Method: POST
Headers:
X-Karma-Signature: pupUry8HQFrFv+zfonCA...RCHUOxdEW+6jcOobo5+s=
X-Karma-Codec: json
Body:
[
"all",
[
"tag",
["string", "_tag"]
]
]
For the following examples, we will just show the Query (Body). Make shure to switch to the JSON Format on the right top corner for these examples.
Example:
Query:
"all", "tag", "string", "_tag"
Notes:
yields a list of the mentioned tags.
Example:
Query:
"all", "tag", "string", "_user"
Notes:
yields a list of users. A new karma instance contains only one 'admin' user
CRUD
With the next steps we will create our own model and create, update, read and delete some content.
Example:
Query:
e.create(e.tag(d.string("_model")), f.function(["param"], e.data(m.struct({- myString: m.string(),
- myInt: m.int32(),
- myBool: m.bool(),
}))))
Result:
[
"RdVuJLdTKaxCcBHo",
"eCGXRjxwHUkQnmzC"
]
Notes:
This example persists a new object of the type _model
and yields a ref
e.g. ["PTmcyzYCwsaoKsjy","NuqdLqlTbjUfSjkf"]
to the persisted object
Example:
Query:
e.create(e.tag(d.string("_tag")), f.function(["param"], e.data(d.struct({- tag: d.string("myModel"),
- model: d.expr({
- scope: "myNewModel",
}),
}))))
Result:
[
"FMuBhfUuaTIpSYsF",
"HsdnBnrjGtkGsxEK"
]
Notes:
It's possible to nest expressions. This example creates the same model as above, and additionally a new _tag
called 'myModel' to that model
Example:
Query:
e.get(e.refTo(e.first(e.all(e.tag(d.string("_tag"))))))
Result:
{
"model": [
"RdVuJLdTKaxCcBHo",
"FMuBhfUuaTIpSYsF"
],
"tag": "_tag"
}
Notes:
This example yields the first object of the _tag
type. You may get the same result with a shorter query (eg. all(tag(_tag))) but this example is about the get param
Example:
Query:
e.update({- ref: e.refTo(e.first(e.all(e.tag(d.string("myModel"))))),
- value: e.data(d.struct({
- myString: d.string("my updated string content"),
- myInt: d.int32(777),
- myBool: d.bool(false),
})),
})
Result:
[
"XhLaWkGPNTXywfAQ",
"kLccoTYVQihppuJy"
]
Notes:
This query is based on the examples in the create
expression. Will change the value of the first object of our example model with tag 'myModel'
Example:
Query:
e.delete(e.refTo(e.first(e.all(e.tag(d.string("myModel"))))))
Result:
{
"myBool": false,
"myInt": 777,
"myString": "my updated string content"
}
Notes:
This query is based on the examples in the create
expression. Will delete the first object of our example model with tag 'myModel'