REST 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
`/user/`...	User operations
`/server/`...	Server operations
`/schema/`...	Schemas operations
`/plan/`...	Plans operations
`/cache/`...	Cache operations

`/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
`/user/login`	POST	Authenticate a Metal user
`/user/logout`	GET	Log out current Metal user
`/user/info`	GET	Get informations about the current Metal user

`/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 activate it in the configuration file by using the authentication server parameter. Once activated, Metal will retrieve the list of users from the users object and authenticate the users against it.

The login request should be made as a POST method to the /user/login endpoint. The request body should be in JSON format and include two fields: username and password. These fields should contain the credentials of the user attempting to log in.

Upon successful authentication, the server will respond with an HTTP status code 200. The response body will be in JSON format and will contain a token field. This token is a JSON Web Token (JWT) that serves as a means of authentication and authorization within the system.

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
403	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

GET /user/logout

Example

Request

http

GET  http://localhost:3000/user/logout

Response

http

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

{
  "message": "Logged out successfully"
}

Response Errors

HTTP Code	Message
400	Invalid username
403	Forbidden (not authenticated)
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
403	Forbidden (not authenticated)
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
`/server/info`	GET	Get informations about Metal server
`/server/reload`	POST	Reload configuration file and apply it

`/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.2"
}

Response Errors

HTTP Code	Message
403	Forbidden (not authenticated)
500	Something Went Wrong

`/server/reload`

Reloads server configuration file config.yml and applies settings

⚠️ IMPORTANT

When reloading, all connections will be reset.

Endpoint

GET /server/reload

Example

Request

http

GET http://localhost:3000/server/reload

Response

http

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

{
  "server": "Metal",
  "message": "Server reloaded"
}

Response Errors

HTTP Code	Message
403	Forbidden (not authenticated)
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
`/schema`/`:schemaName`/`:entityName`	GET, POST, PATCH, DELETE	performs CRUD operation for one or many items via the endpoint, where the `:schemaName` is declared in the configuration file and `:entityName` exists in the mapped source

Method	Usage
GET	Returns 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/:schemaName/:entityName

Path Parameters

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

Query Parameters

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

ℹ️ NOTE

For detailed description of fields, filter, filterExpression, 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
403	Forbidden (not authenticated)
404	Entity 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/:schemaName/:entityName
Content-Type: application/json
{
"data": :data
}

Parameters

Name	type	Required	Description
`:schemaName`	string	Y	name of schema
`:entityName`	string	Y	name of entity in the `:schemaName`
`:data`	JSON array	Y	data to be inserted in the `:entityName`. (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
Content-Type: application/json

{
}

Response Errors

HTTP Code	Message
400	Bad request
403	Forbidden (not authenticated)
404	Entity not found
409	Conflict
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 filterExpression, ALL DATA IN THE ENTITY WILL BE MODIFIED !

Endpoint

PATCH /schema/:schemaName/:entityName
Content-Type: application/json
{
"filter": :filter
"filterExpression": :filterExpression
"data": :data
}

Parameters

Name	Type	Required	Description
`:schemaName`	String	Y	The name of the selected schema.
`:entityName`	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)
`:filterExpression`	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 `:entityName`. (see: Optional Parameters)

ℹ️ NOTE

For detailed description of data, filter and filterExpression 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 200 OK
Content-Type: application/json

{
}

Response Errors

HTTP Code	Message
400	Bad request
403	Forbidden (not authenticated)
404	Entity 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 filterExpression, ALL DATA IN THE ENTITY WILL BE DELETED !

Endpoint

DELETE /schema/:schemaName/:entityName
Content-Type: application/json
{
"filter": :filter
"filterExpression": :filterExpression
}

Parameters

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

ℹ️ NOTE

For detailed description of filter and filterExpression 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 200 OK
Content-Type: application/json

{
}

Response Errors

HTTP Code	Message
400	Bad request
403	Forbidden (not authenticated)
404	Entity 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
`/plan`/`:planName`/`reload`	POST	Reload the plan `:planName` definition as described in the configuration file

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

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

Endpoint

POST /plan/:planName/reload

Path Parameters

Name	type	Required	Description
`:planName`	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
403	Invalid username or password
404	Plan 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
`/cache/view`	GET	Retrieve and display cached data
`/cache/clean`	POST	Remove expired cached data
`/cache/purge`	POST	Delete all cached data

`/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

{
  "message": "Cache data"
}

Response Errors

HTTP Code	Message
400	Invalid username
403	Forbidden (not authenticated)
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	Invalid username
403	Forbidden (not authenticated)
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	Invalid username
403	Forbidden (not authenticated)
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	✅	❌	✅	✅
`filterExpression`	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:

http

POST /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

`filterExpression`

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

Example

http

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

{
	"filterExpression": "name LIKE '%ing' "
}

ℹ️ NOTE

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

Example:

filterExpression=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

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

{
	"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

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

{
	"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

http

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

{
	"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
Content-Type: application/json

{
}

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
Content-Type: application/json

{
}

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 between double curly braces:

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

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

In this instance, the filterExpression 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.

REST API ​

/user/... ​

/user/login ​

/user/logout ​

/user/info ​

/server/... ​

/server/info ​

/server/reload ​

/schema/... ​

GET ​

POST ​

PATCH ​

DELETE ​

/plan/... ​

/plan/:planName/reload ​

/cache/... ​

/cache/view ​

/cache/clean ​

/cache/purge ​

Optional Parameters ​

filter ​

filterExpression ​

fields ​

sort ​

cache ​

data ​

Inserting data ​

Updating data ​

Using dynamic JS code ​

REST API

`/user/`...

`/user/login`

`/user/logout`

`/user/info`

`/server/`...

`/server/info`

`/server/reload`

`/schema`/...

GET

POST

PATCH

DELETE

`/plan/`...

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

`/cache/`...

`/cache/view`

`/cache/clean`

`/cache/purge`

Optional Parameters

`filter`

`filterExpression`

`fields`

`sort`

`cache`

`data`

Inserting data

Updating data

Using dynamic JS code