REST interface for Flecs applications. This module allows introspection of entities through a REST interface. Applications can enable the REST interface by importing the module and instantiating the EcsRestServer component:
ECS_IMPORT(world, FlecsRest);
ecs_entity_t server = ecs_set(world, 0, EcsRestServer, {port: 8080});
The REST module has the following dependencies:
- https://github.com/flecs-hub/flecs-components-http
- https://github.com/flecs-hub/flecs-components-meta
- https://github.com/flecs-hub/flecs-systems-civetweb
- https://github.com/flecs-hub/flecs-json
- https://github.com/SanderMertens/flecs
To build & run the code either embed the source files of these modules into your project, or use bake (https://github.com/SanderMertens/bake):
git clone https://github.com/SanderMertens/bake
make -C bake/build-$(uname)
bake/bake setup
Then clone the repositories in the same directory:
git clone https://github.com/SanderMertens/flecs --branch bleeding_edge
git clone https://github.com/flecs-hub/flecs-components-http
git clone https://github.com/flecs-hub/flecs-components-meta
git clone https://github.com/flecs-hub/flecs-json
git clone https://github.com/flecs-hub/flecs-systems-civetweb
git clone https://github.com/flecs-hub/flecs-systems-rest
And then run bake in that directory:
bake
To run the entity browser example, do (after building):
cd flecs-systems-rest/examples/c/entity_browser
bake run
Get data for a single entity.
http://localhost/entity/MyEntity
Which will return a response something similar to:
{
"type": ["Name", "Position"],
"entity": 330,
"data": {
"Name": {
"value": "MyEntity"
},
"Position": {
"x": 30.000000,
"y": 40.000000
}
}
}
To only return a specific set of components, use the select parameter followed by a comma separated list of components:
http://localhost/entity/MyEntity?select=Position
Which will return a response similar to:
{
"type": ["Name", "Position"],
"entity": 330,
"data": {
"Position": {
"x": 30.000000,
"y": 40.000000
}
}
}
If no entity with the specified name is found, a 404 status is returned.
Delete a single entity or component.
To delete an entity, just provide an entity identifier:
http://localhost/entity/MyEntity
To remove one or more components, use the select parameter followed by a comma separated list of components:
http://localhost/entity/MyEntity?select=Position
If no entity with the specified name is found, a 404 status is returned.
Create a new entity with the specified name.
http://localhost:8080/entity/MyEntity
Add one or more components to an entity.
http://localhost/entity/MyEntity?select=Position
Get data for entities matching a filter.
To filter on a component, add it to the include parameter which accepts a comma-separated list of components:
http://localhost/filter?include=Position
Which will return a response similar to:
[{
"type": ["Name", "Position", "Velocity"],
"entities": [330, 331],
"data": {
"Name": [{
"value": "E1"
}, {
"value": "E2"
}],
"Position": [{
"x": 10.000000,
"y": 20.000000
}, {
"x": 30.000000,
"y": 40.000000
}],
"Velocity": [{
"x": 1.000000,
"y": 1.000000
}, {
"x": 1.000000,
"y": 1.000000
}]
}
}, {
"type": ["Name", "Position", "Velocity", ["CHILDOF", "E2"]],
"entities": [332],
"data": {
"Name": [{
"value": "E3"
}],
"Position": [{
"x": 30.000000,
"y": 40.000000
}],
"Velocity": [{
"x": 1.000000,
"y": 1.000000
}]
}
}]
Note how entities in different types are split up in different sections. The exclude parameter can also be used in the same way as the include parameter.
To only return a specific set of components, use the select parameter followed by a comma separated list of components:
[{
"type": ["Name", "Position", "Velocity"],
"entities": [330, 331],
"data": {
"Position": [{
"x": 10.000000,
"y": 20.000000
}, {
"x": 30.000000,
"y": 40.000000
}]
}
}, {
"type": ["Name", "Position", "Velocity", ["CHILDOF", "E2"]],
"entities": [332],
"data": {
"Position": [{
"x": 30.000000,
"y": 40.000000
}]
}
}]
Similar to /filter
, but returns entities for a specific scope.
http://localhost/scope/MyScope?include=Position&select=Velocity
Which will return a response similar to:
[{
"type": ["Name", "Position", "Velocity", ["CHILDOF", "MyScope"]],
"entities": [330, 331],
"data": {
"Velocity": [{
"x": 1.000000,
"y": 1.000000
}, {
"x": 1.000000,
"y": 1.000000
}]
}
}]
Get information for entities in a scope.
http://localhost/browse/MyScope
Which will return a response similar to:
[{
"id": 330,
"type": ["Name", "Position", "Velocity", ["CHILDOF", "MyScope"]],
"name": "E1",
"path": "MyScope.E1",
"child_count": 0
}, {
"id": 331,
"type": ["Name", "Position", "Velocity", ["CHILDOF", "MyScope"]],
"name": "E2",
"path": "MyScope.E2",
"child_count": 1
}]
The include parameter can be used to filter entities.
Get information for a single entity
http://localhost/browse/MyScope/E1
{
"id": 330,
"type": ["Name", "Position", "Velocity", ["CHILDOF", "MyScope"]],
"name": "E1",
"path": "MyScope.E1",
"child_count": 0
}