Metal API

Metal offers a REST API specifically crafted to execute a range of functions:

Conducting CRUD operations (including select, update, delete, insert)
Facilitating data transformation
Implementing a data caching mechanism for a specified duration

Endpoint Starting	Usage	Metal version
`/user/`...	User operations	^0.1
`/server/`...	Server operations	^0.1
`/schema/`...	Schemas operations	^0.1
`/plan/`...	Plans operations	^0.1
`/cache/`...	Cache operations	^0.1

`/user/`...

This endpoint serves as the entry point for User operations. The table below describes available endpoints and methods to use for request :

Endpoint	Method	Usage	Metal version
`/user/login`	POST	Authenticate a Metal user	^0.1
`/user/logout`	POST	Log out current Metal user	^0.1
`/user/info`	GET	Get informations about the current Metal user	^0.1

`/user/login`

The login endpoint is used to authenticate a user in the Metal system.

Metal has its own user authentication mechanism that is separate from the credentials provided by data providers.

To enable user authentication in Metal, you need to configure server.authentication in the configuration file.

For more information about authentication, see Understanding Authentication, Users, and Roles in Metal Server

Endpoint

POST /user/login

Body Parameters

Name	Type	Requried	Description
username	string	Y	User name
password	string	Y	User password

Example

Request

http

POST  http://localhost:3000/user/login
Content-Type: application/json

{
    "username":"admin",
    "password": 123456
}

Response

http

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6ImFkbWluIiwiaWF0IjoxNjg0MTU4NDY2LCJleHAiOjE2ODQxNjIwNjZ9.Ha76OxFe1Bxn-8PnpjmXeWDvhsjQu9BnOIoBpkWJdw0"
}

Response Errors

HTTP Code	Message
400	Bad Request
401	Invalid username or password
500	Something Went Wrong

`/user/logout`

The logout functionality allows the current logged-in Metal user to end their session.

When a user logs out, it terminates their current session and invalidates the associated authentication token.

Endpoint

POST /user/logout

Example

Request

http

POST  http://localhost:3000/user/logout

Response

http

HTTP/1.1 204 No Content

Response Errors

HTTP Code	Message
400	Bad Request
401	Invalid username or password
500	Something Went Wrong

`/user/info`

This feature provides access to detailed information about the currently logged-in user in the Metal system.

Endpoint

GET /user/info

Example

Request

http

GET  http://localhost:3000/user/info

Response

http

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "username": "admin"
}

Response Errors

HTTP Code	Message
400	Bad Request
401	Invalid username or password
403	Forbidden
500	Something Went Wrong

`/server/`...

This endpoint serves as the entry point for Server operations. The table below describes available endpoints and methods to use for request :

Endpoint	Method	Usage	Metal version
`/server/info`	GET	Get informations about Metal server	^0.1
`/server/reload`	POST	Reload configuration file and apply it	^0.1

`/server/info`

Get informations about Metal server

Endpoint

GET /server/info

Example

Request

http

GET http://localhost:3000/server/info

Response

http

HTTP/1.1 200 OK
Content-Type: application/json

{
	"server" : "Metal",
	"version" : "0.3"
}

Response Errors

HTTP Code	Message
400	Bad Request
401	Invalid username or password
403	Forbidden
500	Something Went Wrong

`/server/reload`

Reloads server configuration file config.yml and applies settings

⚠️ IMPORTANT

When reloading, all connections will be reset.

Endpoint

POST /server/reload

Example

Request

http

POST http://localhost:3000/server/reload

Response

http

HTTP/1.1 200 OK
Content-Type: application/json

{
  "message": "Server reloaded"
}

Response Errors

HTTP Code	Message
400	Bad Request
401	Invalid username or password
403	Forbidden
500	Something Went Wrong

`/schema`/...

This endpoint serves as the entry point for Entities operations. The table below describes available endpoints and methods to use for request :

Endpoint	Method	Usage	Metal version
`/schema`/`:schema`	GET	Lists entities in the `:schema`	^0.3
`/schema`/`:schema`/`:entity`	GET, POST, PATCH, DELETE	Performs CRUD operations for one or many items in the `:entity` existing in the `:schema`	^0.1

`/schema/:schema`

HTTP Method	Usage
GET	Returns list of entities in the schema

GET

Returns list of the entities of the schema provided in URL parameters.

Endpoint

GET /schema/:schema

Path Parameters

Name	type	Required	Description
`:schema`	string	Y	name of the selected schema

Example

To list all entities from the schema my-schema:
Request
http
GET http://localhost:3000/schema/my-schema
Response
http
HTTP/1.1 200 OK
Content-Type: application/json

{
}

Response Errors

HTTP Code	Message
400	Bad Request
401	Invalid username or password
403	Forbidden
404	Not found
500	Something Went Wrong

`/schema/:schema/:entity`

HTTP Method	Usage
GET	Return data of the entity
POST	Insert data in the entity
PATCH	Update data in the entity
DELETE	Delete data in the entity

GET

Returns data from the entity of the schema provided in URL parameters. By default, select return all available data in the entity :

Endpoint

GET /schema/:schema/:entity

Path Parameters

Name	type	Required	Description
`:schema`	string	Y	name of the selected schema
`:entity`	string	Y	name of the entity in the selected schema

Query Parameters

Name	type	Required	Description	Metal version
`:fields`	string	N	fields to keep, comma seperated. (see: Optional Parameters)	^0.1
`:filter`	JSON object	N	condition `key:value` to filter data. (see: Optional Parameters)	^0.1
`:filter-expression`	string	N	free form condition to filter data. (see: Optional Parameters)	^0.1
`:sort`	string	N	sort data, can be `asc` or `desc`. (see: Optional Parameters)	^0.1
`:cache`	number	N	time in seconds to cache data. (see: Optional Parameters)	^0.1

ℹ️ NOTE

For detailed description of fields, filter, filter-expression, sort, cache usage, please refer to Optional Parameters

Example

To select all datas from the schema my-schema and the entity my-entity where color = red:
Request
http
GET http://localhost:3000/schema/my-schema/my-entity?filter={color:"red"}
Response
http
HTTP/1.1 200 OK
Content-Type: application/json

{
}

Response Errors

HTTP Code	Message
400	Bad Request
401	Invalid username or password
403	Forbidden
404	Not found
500	Something Went Wrong

POST

Insert one or more objects in the entity of the schema provided in URL parameters:

Endpoint

POST /schema/:schema/:entity
Content-Type: application/json
{
`"data"`: **`:data`**
}

Parameters

Name	type	Required	Description
`:schema`	string	Y	name of schema
`:entity`	string	Y	name of entity in the `:schema`
`:data`	JSON array	Y	data to be inserted in the `:entity`. (see: Optional Parameters)

ℹ️ NOTE

For detailed description of data usage, please refer to Optional Parameters

Example

To insert the data below in the schema my-schema and the entity my-entity:
name color
Facebook blue
YouTube red
Request
http
POST http://localhost:3000/schema/my-schema/my-entity
Content-Type: application/json

{
	"data": [
		{  "name":"Facebook",	"color": "blue"	},
		{  "name":"YouTube",	"color": "red"	}
	]
}
Response
http
HTTP/1.1 201 Created

name	color
Facebook	blue
YouTube	red

Response Errors

HTTP Code	Message
400	Bad Request
401	Invalid username or password
403	Forbidden
404	Not found
500	Something Went Wrong

PATCH

Modify data in the entity of the schema provided in URL parameters.

🛑 BE CAREFULL

If no filtering is supplied in the body with filter or filter-expression, ALL DATA IN THE ENTITY WILL BE MODIFIED !

Endpoint

PATCH /schema/:schema/:entity
Content-Type: application/json
{
`"filter"`: **`:filter`**

`"filter-expression"`: **`:filter-expression`**

`"data"`: **`:data`**
}

Parameters

Name	Type	Required	Description
`:schema`	String	Y	The name of the selected schema.
`:entity`	String	Y	The name of the entity in the selected schema.
`:filter`	JSON Object	N	A condition in the format `field:value` to filter data. (see: Optional Parameters)
`:filter-expression`	String	N	A free-form condition to filter data. (see: Optional Parameters)
`:data`	JSON Object	Y	JSON data in the format `field:newvalue` to modify in the `:entity`. (see: Optional Parameters)

ℹ️ NOTE

For detailed description of data, filter and filter-expression usage, please refer to Optional Parameters

Example

To modify status = disabled in the entity my-entity of the schema my-schema where color = red:
Request
http
PATCH http://localhost:3000/schema/my-schema/my-entity
Content-Type: application/json

{
	"filter": {
		"color": "red"
	},
	"data": {
		"status": "disabled"
	}
}
Response
http
HTTP/1.1 204 No Content

Response Errors

HTTP Code	Message
400	Bad Request
401	Invalid username or password
403	Forbidden
404	Not found
500	Something Went Wrong

DELETE

Deletes data from the entity in the schema provided in URL parameters.

🛑 BE CAREFULL

If no filtering is supplied in the body with filter or filter-expression, ALL DATA IN THE ENTITY WILL BE DELETED !

Endpoint

DELETE /schema/:schema/:entity
Content-Type: application/json
{
`"filter"`: **`:filter`**

`"filter-expression"`: **`:filter-expression`**
}

Parameters

Name	type	Required	Description
`:schema`	string	Y	name of the selected schema
`:entity`	string	Y	name of the entity in the selected schema
`:filter`	JSON object	N	condition `key:value` to filter data. (see: Optional Parameters)
`:filter-expression`	string	N	free form condition to filter data. (see: Optional Parameters)

ℹ️ NOTE

For detailed description of filter and filter-expression usage, please refer to Optional Parameters

Example

To delete data from the entity my-entity in the schema my-schema where color = red:
Request
http
DELETE http://localhost:3000/schema/my-schema/my-entity
Content-Type: application/json

{
	"filter": {
		"color": "red"
	}
}
Response
http
HTTP/1.1 204 No Content

Response Errors

HTTP Code	Message
400	Bad Request
401	Invalid username or password
403	Forbidden
404	Not found
500	Something Went Wrong

`/plan/`...

This endpoint serves as the entry point for Plans operations. The table below describes available endpoints and methods to use for request :

Endpoint	Method	Usage	Metal version
`/plan`/`:plan`/`reload`	POST	Reload the plan `:plan` definition as described in the configuration file	^0.1

`/plan`/`:plan`/`reload`

Reload the plan :plan definition as described in the configuration file.

Endpoint

POST /plan/:plan/reload

Path Parameters

Name	type	Required	Description
`:plan`	string	Y	name of the selected plan

Example

Request

http

POST  http://localhost:3000/plan/my-plan/reload
Content-Type: application/json

Response

http

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
   "plan": "my-plan",
   "message": "Plan reloaded"
}

Response Errors

HTTP Code	Message
400	Bad Request
401	Invalid username or password
403	Forbidden
404	Not found
500	Something Went Wrong

`/cache/`...

This endpoint serves as the entry point for Cache operations. The table below provides an overview of the available endpoints and the corresponding methods to be used for each request:

Endpoint	Method	Description	Metal version
`/cache/view`	GET	Retrieve and display cached data	^0.1
`/cache/clean`	POST	Remove expired cached data	^0.1
`/cache/purge`	POST	Delete all cached data	^0.1

`/cache/view`

This endpoint allows you to retrieve and display the cached data. It returns the cached data in a readable format, providing insights into the stored information.

Endpoint

GET /cache/view

Example

Request

http

GET http://localhost:3000/cache/view

Response

http

HTTP/1.1 200 OK
Content-Type: application/json

{
}

Response Errors

HTTP Code	Message
400	Bad Request
401	Invalid username or password
403	Forbidden
404	Not found
500	Something Went Wrong

`/cache/clean`

With this endpoint, you can remove any expired cached data. It helps in maintaining the cache server's efficiency by eliminating outdated or irrelevant information.

Endpoint

POST /cache/clean

Example

Request

http

POST http://localhost:3000/cache/clean
Content-Type: application/json

Response

http

HTTP/1.1 200 OK
Content-Type: application/json

{
  "message": "Cache cleaned"
}

Response Errors

HTTP Code	Message
400	Bad Request
401	Invalid username or password
403	Forbidden
500	Something Went Wrong

`/cache/purge`

It enables you to delete all the cached data in one go. This action can be useful when you need to clear the cache completely, such as during system maintenance or when starting fresh.

Endpoint

POST /cache/purge

Example

Request

http

POST http://localhost:3000/cache/purge
Content-Type: application/json

Response

http

HTTP/1.1 200 OK
Content-Type: application/json

{
  "message": "Cache purged"
}

Response Errors

HTTP Code	Message
400	Bad Request
401	Invalid username or password
403	Forbidden
500	Something Went Wrong

Optional Parameters

Optional Parameters are usefull for applying filtering, sorting or limit fields to return. They are the same whether they are used as query string for a GET Request or in the body for POST,PATCH and DELETE

All parameters are described in the table below:

Option	Usage	GET	POST	PATCH	DELETE
`filter`	simple filter	✅	❌	✅	✅
`filter-expression`	complex filter expression	✅	❌	✅	✅
`fields`	select fields to return	✅	❌	❌	❌
`sort`	sort data with a given order	✅	❌	❌	❌
`cache`	cache returned data for a given time	✅	❌	❌	❌
`data`	data to send to server	❌	✅	✅	❌

⚠️ IMPORTANT

All parameters are passed to the data provider except for cache directive that is handled by Metal Server.

`filter`

Simple filtering feature by providing fields and values:

Example

To filter people with name = John and location = USA:

GET Request

http

GET /schema/my-schema/my-entity
    ?filter={"Name":"John","Location":"USA"}

PATCH Request

http

PATCH /schema/my-schema/my-entity
Content-Type: application/json

{
	"filter": {
		"Name": "John",
		"Location": "USA"
	}
}

DELETE Request

http

DELETE /schema/my-schema/my-entity
Content-Type: application/json

{
	"filter": {
		"Name": "John",
		"Location": "USA"
	}
}

ℹ️ TIP

It is possible to use dynamic JS code in values.

For more information, please refer to Using dynamic JS code

`filter-expression`

Free expression for more complex data filtering expressed in SQL-like syntax.

Example

GET Request

http

GET /schema/my-schema/my-entity
    ?filter-expression="name LIKE '%ing' "

PATCH Request

http

PATCH /schema/my-schema/my-entity
Content-Type: application/json

{
	"filter-expression": "name LIKE '%ing' "
}

DELETE Request

http

DELETE /schema/my-schema/my-entity
Content-Type: application/json

{
	"filter-expression": "name LIKE '%ing' "
}

ℹ️ NOTE

When employing the LIKE operator with the wildcard % in a GET method, remember to escape it using double %%.

Example:

filter-expression=name LIKE '%%ing'

:::

ℹ️ TIP

It is possible to use dynamic JS code in values.

For more information, please refer to Using dynamic JS code

`fields`

Select fields to return

Example

http

GET /schema/my-schema/my-entity
    ?fields="name, country"

`sort`

sort data with given order.

Sorting Operator	Usage	SQL like
`asc`	Ascending order	ASC
`desc`	Descending order	DESC

⚠️ IMPORTANT

The sorting will be executed in the backend server configured as data provider, except for schemas that relie on plan or memory data provider, in this case Metal will performs the sorting according to the passed parameter.

Example

To sort data with name ascending then email descending:
http
GET /schema/my-schema/my-entity
    ?sort={"name":"asc","email":"desc"}

`cache`

Instruct Metal to cache the data returned from the source for a given time in seconds before displaying it to the user end point, meanwhile users that hit again the same query will receive the cached data until it expires.

Example

To cache returned data for 60 seconds:
http
GET /schema/my-schema/my-entity
    ?cache=60

`data`

this paramater is used for inserting or updating data.

Inserting data

:data accept whether a JSON object if it is a single row to insert or a JSON Array if many rows

ℹ️ TIP

It is possible to use dynamic JS code in values.

For more information, please refer to Using dynamic JS code

Example: single row insert

Request

http

POST /schema/my-schema/my-entity
Content-Type: application/json

{
	"data":
	{
		"name":"Facebook",
		"color": "blue"
	}
}

Response

http

HTTP/1.1 201 Created

Example: multiple rows insert

Request

http

POST /schema/my-schema/my-entity
Content-Type: application/json

{
	"data": [
		{ "name":"Facebook", "color": "blue" },
		{ "name":"YouTube",  "color": "red"  }
	]
}

Response

http

HTTP/1.1 201 Created

Updating data

:data accept a JSON object of key:value where key is the field to modify and value is the new value

Example

Request

http

PATCH /schema/my-schema/my-entity
Content-Type: application/json

{
	"data":
	{
		"name":"Facebook",
		"color": "blue"
	}
}

Response

http

HTTP/1.1 200 OK
Content-Type: application/json

{
}

Using Dynamic JS code

By seamlessly integrating dynamic JS code, Metal empowers users to create more versatile and adaptive configurations. To embed JS code within your key values, encapsulate it like this:

javascript

${{ /* JS code here */ }}

Example: Filtering Dates Before Now

Consider the following example, where dynamic JS code is applied to filter dates before the current date:

http

POST /schema/my-schema/my-entity
Content-Type: application/json

{
	"filter-expression": "date < '${{ new Date().toLocaleDateString(\"en-US\") }}' "
}

In this instance, the filter-expression incorporates JS code within the curly braces to dynamically calculate the current date in the specified format.

This flexibility enables precise control and customization, showcasing the versatility that dynamic JS code brings to your Metal implementation.

Metal API ​

/user/... ​

/user/login ​

/user/logout ​

/user/info ​

/server/... ​

/server/info ​

/server/reload ​

/schema/... ​

/schema/:schema ​

GET ​

/schema/:schema/:entity ​

GET ​

POST ​

PATCH ​

DELETE ​

/plan/... ​

/plan/:plan/reload ​

/cache/... ​

/cache/view ​

/cache/clean ​

/cache/purge ​

Optional Parameters ​

filter ​

filter-expression ​

fields ​

sort ​

cache ​

data ​

Inserting data ​

Updating data ​

Using Dynamic JS code ​

Metal API

`/user/`...

`/user/login`

`/user/logout`

`/user/info`

`/server/`...

`/server/info`

`/server/reload`

`/schema`/...

`/schema/:schema`

GET

`/schema/:schema/:entity`

GET

POST

PATCH

DELETE

`/plan/`...

`/plan`/`:plan`/`reload`

`/cache/`...

`/cache/view`

`/cache/clean`

`/cache/purge`

Optional Parameters

`filter`

`filter-expression`

`fields`

`sort`

`cache`

`data`

Inserting data

Updating data

Using Dynamic JS code