Getting Started with Stellar DataStore

Using the following steps will ensure that you are up and running with Stellar DataStore in no time. You can use this guide to set up your first tables, create your first ClientId & Secret to set up the OAuth flow or simply generate an access token to use to manage data in your newly set up tables.

Setting Up Your Database:

In case you haven't done this yet, begin by creating an account and upon activation, log in via https://stellards.io/application/app

2. Project Overview

After logging in, you'll be directed to the start page where you'll find:

Usage statistics such as request count, number of tables, and connected users.
Recent project activity overview.
Most importantly to get started, you'll find your Project ID displayed beneath the name.

3. Table

Navigate to the tables section to see an overview of all your tables. Create a new table by clicking on "+ Create New Table" button. Give your table a unique name and optionally add a description. After creation, you'll see your new table listed with its ID. To define its structure click on the "Manage" button at the bottom of the card or go via "..." on the right of the card and choose "Manage". Here we have the view for the specific table. It is possible to:

Manipulate the Fields
Set the Permissions for each role
Check the Data in the table

Under the Fields tab, click on "+ Add Field". With the "+ Add New Field" button in the popup you can add multiple fields after one another.

Fopr this example we will create a table called Persons and let's add 3 new fields:

Name (of the type NVarChar and a maximum size of 255).
YearOfBirth (of the type Int.
Married (of the type Boolean.)

Note: When using NVarChar type, ensure the specified maximum value is between 1 and 32767.

Authentication

Authentication with the Stellar DataStore API can be done using either OAuth 2.0 or an Access Token.

1. Access Tokens

1.1. Generate an Access Token:

To quickly start interacting with Stellar DataStore, generate an access token from the Applications page under the Access Tokens tab.

1.2. Add a New Access Token:

Provide a name, duration, span, role, and optionally a domain (for web applications).

Note: Upon creation, copy the access token as it won't be visible afterward.

1.3. Use the Access Token:

With the access token, you can now make your first API call. However, note that using access tokens is not recommended for public applications due to security reasons.

Alternatively, for a more secure approach, you can set up an OAuth 2.0 flow to obtain an access token and refresh token.

2. OAuth2.0

2.2. Add OAuth Application:

Navigate to the OAuth applications tab on the Applications page. Add application details including name, callback URLs, and assign a role. You can specify up to 5 callback URLs.

Open a browser window and navigate to https://stellards.io/oauth with query parameters: Client ID, Response type: Code, and Redirect URI matching one set in the application. After a successful login, you'll receive an auth token in the query parameter of the redirect URI.

2.4. Exchange Auth Token for Access Token & Refresh Token:

Call the following endpoint with required parameters in a x-www-url-formencoded body:

  curl -X 'POST' \
    'https://api.stellards.io/v1/oauth/token' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'grant_type=authorization_code&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=REDIRECT_URI&code=AUTHORIZATION_CODE'

This will return an access token, refresh token, and expiration time for the access token.

2.5. Refreshing Tokens:

An access token is valid for 30 minutes, and a refresh token is valid for 1 month if not used. To refresh a token, make a call to:

  curl -X 'POST' \
    'https://api.stellards.io/v1/oauth/token' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'grant_type=refresh_token&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&refresh_token=REFRESH_TOKEN'

with the grant_type set to refresh_token and other necessary parameters.

By following these steps, you can efficiently set up your database and manage access tokens for interacting with Stellar DataStore.

Note: The authorization is done in the following way: Authorization: Bearer ACCESS_TOKEN

API Calls

For the moment there is no data in our table" so let's add a couple of records with a POST request.

POST Data

Add Data

The data is added in the body with JSON formatting. You can add multiple records in one request:

{
  "records": 
   [
      {
         "Name": "Mark Smith",
         "YearOfBirth": 1970,
         "Married": true
      },
      {
         "Name": "Paula Garcia",
         "YearOfBirth": 1982,
         "Married": false
      },
      {
         "Name": "Eva Jones",
         "YearOfBirth": 1993,
         "Married": true
      }
   ]
}

As you might notice, we didn't add the "id" field as this is an auto-incremented key.

Now we will need our Project ID and Table ID to add them in the URL of our request. We also need the Access Token to add in the Authorization header.

Request

    curl -X 'POST' \
      'https://api.stellards.io/v1/data/table?project={PROJECT_ID}&table={TABLE_ID}' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer ACCESS_TOKEN' \
      -d '{"records":[{"Name":"Mark Smith","YearOfBirth":1970,"Married":true},{"Name":"Paula Garcia","YearOfBirth":1982,"Married":false},{"Name":"Eva Jones","YearOfBirth":1993,"Married":true}]}'

Response

First we can check if the request was successful with the "isSuccess" boolean, otherwise some error messages might be added in the message property. Next to that we'll get the number of records that were added and the data.

{
    "count": 3,
    "data": [
        {
            "id": 3,
            "Name": "Eva Jones",
            "YearOfBirth": 1993,
            "Married": true
        },
        {
            "id": 2,
            "Name": "Paula Garcia",
            "YearOfBirth": 1982,
            "Married": false
        },
        {
            "id": 1,
            "Name": "Mark Smith",
            "YearOfBirth": 1970,
            "Married": true
        }
    ],
    "messages": [],
    "isSuccess": true
}

GET Data

Now let's try to retrieve the information we just posted. Although we have all of the information needed because of the POST request, let's say we have no clue on what our project and table IDs are.

GET Projects

To get our projects we can call the following endpoint.

Request

    curl -X 'POST' \
      'https://api.stellards.io/v1/schema/project' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer ACCESS_TOKEN' \

Response

Here you can see the "isSuccess" and "messages" properties. And the data property contains our project(s).

{
    "data": [
        {
            "id": "223fazf3-9s6dc-4685-ec30-08ec3ez37ds78",
            "name": "My Project",
            "description": "My first project",
            "isMultitenant": false
        }
    ],
    "messages": [],
    "isSuccess": true
}

GET Tables

Now to retrieve our table, we'll need our project ID to do the following request.

Request

    curl -X 'GET' \
      'https://api.stellards.io/v1/schema/table?project=223fazf3-9s6dc-4685-ec30-08ec3ez37ds78' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer ACCESS_TOKEN' \

It is optional to add the table parameter with the correct name of your table.

Response

Here you can see the "isSuccess" and "messages" properties. And the data property contains our table(s).

{
    "data": [
        {
            "id": 100,
            "name": "Persons",
            "description": "Table to help with the user guide",
            "isMultitenant": false
        },
        {
            "id": 106,
            "name": "Other table",
            "description": "An additonal table",
            "isMultitenant": false
        }
    ],
    "messages": [],
    "isSuccess": true
}

GET Records

Now that we know the table ID, we can retrieve the data in it.

Request

    curl -X 'GET' \
      'https://api.stellards.io/v1/data/table?project=223fazf3-9s6dc-4685-ec30-08ec3ez37ds78&table=100' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer ACCESS_TOKEN' \

Response

Here you can see the "isSuccess" and "messages" properties. And the data of the records in the table.

{
    "count": 3,
    "data": [
        {
            "id": 1,
            "Name": "Mark Smith",
            "YearOfBirth": 1970,
            "Married": true
        },
        {
            "id": 2,
            "Name": "Paula Garcia",
            "YearOfBirth": 1982,
            "Married": false
        },
        {
            "id": 3,
            "Name": "Eva Jones",
            "YearOfBirth": 1993,
            "Married": true
        }
    ],
    "messages": [],
    "isSuccess": true
}

Parameters

There a number of additional parameters that you can add to this request.

parameter name	Required	Description
project	true	The id of your project
table	true	The id of the table you want the data from
offset	false	Integer value of how many records to skip
take	false	Integer value of how many records you want to query
sortQuery	false	URL encoded string with the following form: FIELD_NAME;asc / FIELD_NAME;desc. You can sort on multiple fields by separating the query with '&' (FIELD_A;asc&FIELD_B;desc). There is no limit on the amount of fields you can sort on, but every field can only be used once.
whereQuery	false	URL encoded string with the following form: FIELD_NAME;OPERATIONAL_PARAMETER;VALUE. Filters the data you want to query. You can read more about the different operators here.
joinQuery	false	URL encoded string with the following form: TABLE;FOREIGN_KEY_ID=TABLE_TO_JOIN;ID. Enables you to join 2 tables and fetching the data in 1 request.

   curl -X 'GET' \
 'https://api.stellards.io/v1/data/table?project={PROJECT_ID}&table={TABLE_ID}&wherequery={FIELD_A;OPERATOR;%VALUE%%7CFIELD_B;OPERATOR;%VALUE%}&SortQuery={FIELD_A%3Basc%26FIELD_B%3Bdesc}&joinquery={TABLE_A%3BFOREIGN_KEY_ID%3DTABLE_B%3BID}' \
 -H 'accept: application/json' \
 -H 'Authorization: Bearer ACCESS_TOKEN'

Operators
equal
like
in
largerthan, lt
smallerthan, st
or, \|
and, &

GET Advanced Records

As a last GET example we will retrieve all of the married people. For this we will need to create a where clause based on the parameter "whereQuery" and the "Operators" shown above. The parameter value will be Married;like;true but this needs to be url-encoded.

Another example might be to retrieve all the persons that are older than 50, then this would be the query:YearOfBirth;st;1974

Request

    curl -X 'GET' \
      'https://api.stellards.io/v1/data/table?project=223fazf3-9s6dc-4685-ec30-08ec3ez37ds78&table=100&wherequery=Married%3Bequal%3Btrue' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer ACCESS_TOKEN' \

Response

And now we get only 2 records.

{
    "count": 2,
    "data": [
        {
            "id": 1,
            "Name": "Mark Smith",
            "YearOfBirth": 1970,
            "Married": true
        },
        {
            "id": 3,
            "Name": "Eva Jones",
            "YearOfBirth": 1993,
            "Married": true
        }
    ],
    "messages": [],
    "isSuccess": true
}

Update Data (PUT)

Let's say that Paula got married and this needs to be changed in the database. Then we can add the following JSON in the Body of the request. Paula is the record with id 2.

{
    "idList": [2],
    "record": [
        {
            "Married": true
        }
    ]
}

Request

    curl -X 'PUT' \
      'https://api.stellards.io/v1/data/table?project=223fazf3-9s6dc-4685-ec30-08ec3ez37ds78&table=100' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer ACCESS_TOKEN' \
      -d '{"idList": [2],"record":{"Married":true}}'

Response

In the response we get our updated record.

{
    "count": 1,
    "data": [
        {
            "id": 2,
            "Name": "Paula Garcia",
            "YearOfBirth": 1982,
            "Married": true
        }
    ],
    "messages": [],
    "isSuccess": true
}

Conclusion

Following these steps, you can efficiently set up your database and manage access tokens for interacting with Stellar DataStore. For more information on integrating with Delphi, refer to the TMS WEB Core or TMS FNC Cloud Pack documentation. Additionally, all supported endpoints can be found for Postman or Swagger.

Getting Started with Stellar DataStore

Setting Up Your Database:

1. Sign Up and Access Stellar DataStore

2. Project Overview

3. Table

Authentication

1. Access Tokens

1.1. Generate an Access Token:

1.2. Add a New Access Token:

1.3. Use the Access Token:

2. OAuth2.0

2.2. Add OAuth Application:

2.3. Login and Obtain Auth Token:

2.4. Exchange Auth Token for Access Token & Refresh Token:

2.5. Refreshing Tokens:

API Calls

POST Data

Add Data

Request

Response

GET Data

GET Projects

Request

Response

GET Tables

Request

Response

GET Records

Request

Response

Parameters

GET Advanced Records

Request

Response

Update Data (PUT)

Request

Response

Conclusion