# 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.