#
Getting Started
Let's create a simple TiloRes instance with a lightweight schema and run the API locally.
We will briefly cover these topics:
- creating a new TiloRes application
- customize the schema
- test the schema locally
- provide resources for the next steps
Following the steps provides you with a fake implementation of TiloRes. It is meant to showcase how you can customize the TiloRes API. Currently, the real implementation can only be tested in your own AWS account. Contact sales (service@tilotech.io) for further details and to request your personal credentials.
#
Prerequisites
We will use the TiloRes CLI to create our first TiloRes instance. However, this
requires, that go
is installed.
For installing go
, please refer to the official installation guide:
https://golang.org/doc/install
Verify your go
installation afterwards by running
go version
TiloRes CLI does not support Windows. Windows users may consider installing a linux subsystem.
#
Install TiloRes CLI
Afterwards, install and verify the TiloRes CLI:
go install github.com/tilotech/tilores-cli@latest
tilores-cli version
For Mac OS make sure $GOPATH
is set and the go binary path is added to $PATH
. To do so run the following:
export GOPATH=~/go
export PATH=$PATH:$GOPATH/bin
To make this work for new terminal sessions it needs to be added to the dotfile e.g ~/.bashrc
or ~/.zshrc
etc.,
depending on which terminal you use.
#
Initialize Project
You can now initialize the project. This will create the required files for your custom GraphQL API.
mkdir my-tilores-project
cd my-tilores-project
tilores-cli init
#
Start Local API
Now, you can already start the local API webserver and try it out.
tilores-cli run
After the server started, open http://localhost:8080 to access the UI for API testing.
#
Submit And Search First Record
Let's verify that the previous steps worked by submitting a new record using the UI for API testing.
mutation {
submit(input: {
records: [
{
id: "my-id",
myCustomField: "some-value"
}
]
}) {
recordsAdded
}
}
And afterwards query that record and its entity again.
query {
search(input: {
parameters: {
myCustomField: "some-value"
}
}) {
entities {
id
records {
id
myCustomField
}
}
}
}
#
Customize Schema
The schema for records are defined via its GraphQL schema, which can be found in
your TiloRes project under schema/record.graphqls
.
To add a new field simply add it to the RecordInput
(used for adding data) and
the Record
(used for querying data).
input RecordInput {
id: ID!
myCustomField: String!
newCustomField: String!
}
type Record {
id: ID!
myCustomField: String!
newCustomField: String!
}
#
Test The Modified Schema
After restarting the local API server, you can use the new field. Note, that this field will not be used for matching. Please refer to the rules configuration for details on how to match or search using the new field.
Stop and start the server again.
tilores-cli run
Open the UI again and submit the modified record.
mutation {
submit(input: {
records: [
{
id: "my-id",
myCustomField: "some-value"
newCustomField: "other-value"
}
]
}) {
recordsAdded
}
}
And query the field too.
query {
search(input: {
parameters: {
myCustomField: "some-value"
}
}) {
entities {
id
records {
id
myCustomField
newCustomField
}
}
}
}
#
Next Steps
Once you have seen this working, you may want to further customize your schema and configure your matching rules.
Or you may want to deploy the API into AWS and understand how the API is secured.