In this guide, we are going to use Onesait Platform CloudLab will be used, a free-of-charge cloud-base facility of the platform where developers and potential users can carry out their tests.

Step 1: Registration and access to the Platform

Access to CloudLab environment and user creation

Open in a browser the CloudLab’s Environment URL: https://lab.onesaitplatform.com/controlpanel

First of all, you need to create a user. To do this, on the login screen, you must select the Sign Up option to create a user by entering an id, password, name, and e-mail.

Open

If you want to access the platform as a developer, you must select the Developer option.

Open

If the creation process has been correct, you will be redirected to the login page, asking you to you check your email to complete the registration.

You will receive an email like this one. To complete the registration, just click on the link:

After doing so, this will appear:

and now you will be able to access with your username and password.

Control Panel Access

Once you access the Control Panel with your user, you will find a UI like this one:

The main page shows:

• An options menu on the left side of the screen with all the options for the user. This menu is organized into submenus.

• A header where you can access your profile, language, log out and also access the platform management APIs or search the Developer Portal.

• Access to My Environment, with all concepts managed by platform. When you have just finished creating the user, you will only have an entity, Audit_<username> , in which the platform automatically records all the user's actions:

Step 2: Create an Entity/Ontology in the Platform

Onesait Platform is a Data Centric platform, where data is the main and permanent asset, while applications come and go. In these architectures, the data model precedes the implementation of any given application and will be valid long after they are superseded. In Platform these data or entities are called Ontologies.

The first step to develop on a platform will be to model the Entity (Ontology). To do this, select the menu option DEVELOPMENT>My Ontologies.

After this, a list with your Entities/Ontologies will be displayed (if you want to view the ontologies to which you have authorizations or are public, you must uncheck the Show only my ontologies option located on the list).

To create a new ontology, select the Create option, located at the top right.

Next, a UI will appear with various options, where you will select Creation Step by Step:

A continuación nos aparecerá una UI con diversas opciones, donde seleccionaré Creation Step by Step:

On the next screen, complete the initial information necessary to create the Ontology:

that is:

• Name: to give a unique name to the Entity/Ontology. You can't create ontologies with an already existing name (so you can add your username as a suffix, for example)

• Meta-Information: to assign keywords to classify the ontologies.

• Active: to mark the entity as Active and be able to use it (deactivated ontologies cannot be used).

• Public: if you mark the entity as public, all users will be able to consult its data (but not modify the entity or insert data).

• Description: to give a description that can help identify the objective of the ontology.

For this example, create the Ontology with these data:

You can move through the options when creating the Entity. If you go to ADVANCED SETTINGS, you can see several options, among them that the Entity/Ontology will be stored in a MONGO database managed by platform. Don't touch any of this for now.

Once the initial information of the Entity has been completed, continue completing the information to create it. The next step is to create this Entity from a Template. This allows reusing standardized Data Models (such as the GSMA Data Model) so that an Entity that represents an Element (for example a Parking Lot) is always modeled in the same way.

In this case, as you want to model a simple Entity, start from the EmptyBase Template found in the GENERAL tab, which is an empty base template to model the custom Entity. If you click twice on the element, a drop-down will appear to CONFIRM that you want to use that template or Data Model.

You can see that an empty definition appears. The next step is to add the properties of your Entity:

For the example, model your Entity/Ontology with three properties:

• idDevice (STRING): it represents the identifier of the device for which the measurement is taken.

• type (STRING): it represents the type of measurement, for example HUMIDITY, TEMPERATURE.

• measure (NUMBER): it represents the measurement in numeric format.

• timestamp (DATE): it represents the date and time when the measurement was taken.

When you have finished adding the properties, press the UPDATE SCHEMA option. This shows you the representation of that Entity in Platform. The Platform uses JSON-Schema to represent the structure of the entities, regardless of where they are being persisted (for example, even if this Entity/Ontology were stored in a relational DB, the representation would be the same):

You can edit your Entity's structure from here as well.

If tou click the GENERATE INSTANCE button, the structure of an Ontology instance on the platform is displayed. Just as JSON-Schema is used to represent these Entities/Ontologies, JSON is used to represent the instances of each Entity/Ontology, regardless of the persistence behind it (again, although underneath the ontology is stored in a relational database, the platform will handle it like this)

An example of JSON with the structure defined would be this:

To finish, save the Entity/Ontology created by clicking the NEW button located at the bottom of the page.

Step 3: REST API to access your Entity/Ontology

Create REST API

Once the Entity/Ontology that represents the information you want to manage in the system has been created, you can do different processing on the platform: you can create visualizations with the Dashboard Engine, create a Client to access this Entity through the Platform Broker, or create a REST API to access this data in a simple and standardized way.

To do this, you can go to the Create New REST API for this Ontology option that appears when creating an Entity or from the corresponding menu option, DEVELOPMENT> My APIs.

When selecting this option, go to the List of APIs to which your user has access. As you can see, you have access to a good number of APIs. This is because the users who created them marked them as PUBLIC and therefore they are accessible to other users of the instance:

In this case, you want to create a new API, so select the CREATE button.

This takes you to an interface like this one:

To create an API, fill in this information:

• Identification: it is the name of the API, it must be unique in the platform instance.

• API type: it represents the API type. The platform allows you to publish a REST API from an Ontology/Entity or create a REST API from a Swagger descriptor to act as a Proxy.

• Ontology: if you selected the type of API Ontology, here you will select the ontology that handles the API.

• Description: it provides a description of the API.

• Category: You can catalog the API in a category, for later viewing and searching.

• Public: Marking an API as public makes it visible to other users who can use it.

• Meta-inf: it allows to assign different tags to the API.

• Image: it allows to assign an image to the API.

In this case, select this information for the API:

If you continue with the UI, you will see the Operations section, which represents the operations that you want to make available in the API.

The platform allows you to automatically create the CRUD operations of an API: INSERT, UPDATE, DELETE, QUERY BY, QUERY ALL, it also allows you to make custom queries.

• QUERY(ALL): GET request, retrieves all the data of an ontology/entity.

• QUERY(ID): GET request, retrieves an instance from the id.

• INSERT: POST request, allows inserting a new instance.

• UPDATE: PUT request, allows updating an instance..

• DELETE(ID): DELETE request, allows to delete an instance based on its id.

• QUERY CUSTOM: GET request, allows you to create a custom query.

In our case, enable the default options (to see how to create a QUERY CUSTOM, you can read this guide: https://onesaitplatform.atlassian.net/wiki/spaces/PT/pages/2043871259 ).

And select NEW.

In the My APIs List UI, you will see the newly-created API:

When creating an API in Platform, it is created in CREATED state. APIs have a specific life cycle (see https://onesaitplatform.atlassian.net/wiki/spaces/PT/pages/2046296087 ). For other users to be able to invoke the API, it must be at least in DEVELOPMENT state; for that just click the corresponding button:

Invoke the REST API created

Invoking the Platform APIs requires an Access Token. The platform allows invocation with two types of Tokens:

• Custom Tokens: these Tokens are generated for each user, and it is the simplest mechanism to invoke an API.

• OAuth2 Tokens: These tokens are generated per platform through the OAuth2 lifecycle.

You can access your Tokens from the My APIs UI found in the USER TOKENS section:

From there you will see a Token. You can also delete that Token or generate several:

NOTE: The OAuth2 Token generated in the Control Panel for the user can be found by clicking on the 3 dots and then on the APIs section:

Once you have the tokens, go back to My APIs and the API you want to invoke and select the SWAGGER button.

After this, you will see a UI like this:

Right now you don't have any measurements recorded, so start by inserting one invoking the POST / for the create. When you select it, this will appear:

If you click the Try it out button, the UI will be enabled to enter a measure. As you saw when creating the Entity, an entry looked like this:

Completing the User Token, the record to insert and clicking EXECUTE:

you will get an output like this, indicating the ID of the inserted record:

Insert a few more measures from this same UI.

After this, try the API method that allows you to retrieve all the measurements, the GET /

When invoking it, you will obtain as output the list with all the measures:

You can see that, for each measurement, in addition to the measurement record, a section called contextData is obtained. This section is completed automatically, indicating in it the user who made the insertion the time it was made, and the source module

The rest of the API methods can be tested in the same way.

Within the Swagger interface, you can also get the request that you must make from a curl or from another client:

Complete the REST API created

Up until now, you had an API with the basic operations. Since you have the API in DEVELOPMENT state, you can still modify it. Now, you will create a method that returns the measurements of a single idDevice.

For that, from My APIs, select EDIT on your API:

In the following UI, navigate to the end and click on QUERY(CUSTOM).

Start by putting a query like this (Select * from MyMeasures_lmgracia_dev as c where c.MyMeasures_lmgracia_dev.idDevice='MyWeatherStation')

If you click on the EXECUTE QUERY button, you can see that you get these measurements:

You can also format the query that you get so that, for example, you don't get the info from the ContextData. To do this, change the query to this:

and with this I get a record like this:

Finally, make this API parameterizable so that the idDevice parameter can be passed as a parameter. To do that, it is enough to include the parameter with {$<parameter_name>} and indicate the type of parameter - in this case, it is a STRING.

If you click the SAVE CHANGES option and then EDIT in the API, then you will already have a new method in your API that you can invoke as before:

and get:

Step 4: Using the Query Tool

To finish this tutorial we will access a very important tool in Platform development. This is the QUERY TOOL, accessible from the TOOLS>Query Tool menu option:

When accessing, you will see a UI like this:

where you can select the Ontology/Entity on which you want to make queries and, in a simple way, be able to consult the information managed by the platform.

The platform transparently manages the repositories where the information is actually stored, for example your Entity is stored in Mongo and yet you can query it in SQL: