CRUD

The CRUD libraries allow full customization of mock object schema and RESTful endpoint names. Covalent Data will also seed the mock object database with randomly selected datum from text files.

Schema directory structure

Covalent Data requires a specific directory structure to seed initial mock objects. The schemas and datum directories should be in the root directory of the project. All schema files should be in yaml format, and all datum should be in .txt files.

├── covalent-data/
│   ├── server.go
│   ├── README.md
│   ├── schemas/
│   │   ├── features.yaml
│   │   ├── items.yaml
│   │   ├── users.yaml
│   │   ├── address.yaml
│   ├── datum/
│   │   ├── firstname.txt
│   │   ├── lastname.txt
│   │   ├── company.txt
│   │   ├── streetname.txt
│   │   ├── roadtype.txt
│   │   ├── city.txt
│   │   ├── state.txt

Schema file structure

A typical schema file will have the following structure:

users.yaml

# this is a sample schema file for a user object.
# comments in yaml are denoted with the # sign.
# PROTIP: DON'T use tabs in yaml files! Only spaces.
---
# the following three lines here are to initialize 
# the mock objects and will not be included in the final
# objects.
initial_entries: 5
randomize: false
search_index: database_id

display_name: {{.firstname}} {{.lastname}}
id: {{toLower(.firstname)}}.{{toLower(.lastname)}}
email: {{toLower(.firstname)}}.{{toLower(.lastname)}}@{{.company}}.com
mailing_address:
  {{embed(address.yaml)}}
database_id: {{uuid()}}
site_admin: {{randomNumber(1)}}
...

Note that the schema file is fully yaml compliant.

Every schema file in the /schemas directory is rendered into a RESTful CRUD endpoint specified by the name of the yaml file. In this case, users.yaml will render into the endpoint

http://localhost:8080/users

Schema directives

There are several directive keywords that Covalent Data will search for when parsing schema files:

initial_entries: integer (default: 1)

The initial_entries keyword directs Covalent Data to create that number of objects when seeding the database with mock data.

randomize: boolean (default: true)

randomize directs Covalent Data to either pull data from datum files randomly (true) or in an ordered fashion (false).

search_index: string (default: id)

The search_index directive will set the column that is used when searching for objects in the database when reading, editing, and deleting.

All object searches in this case will be set to database_id.

GET http://localhost:8080/users/{database_id}

Schema variables

All schema variables are enclosed in {{double curly braces}}.

There are three different types of schema variables available:

Datum

Datum variables are denoted with a dot inside of the curly braces. For example, {{.firstname}} denotes a datum variable. Every datum variable must have a corresponding .txt file in the /datum directory. (In this case, there must be a file called datum/firstname.txt.)

Functions

Function variables are denoted with parenthesis following the function name. These are set functions that are supplied with Covalent Data. They can either be used independent of datum variables, or as inputs.

For instance, {{uuid()}} will return a UUID v4 compliant unique ID, and {{toLower(.firstname)}} will return a random firstname datum variable that has been lower cased.

Embeds

Embed variables are a special function type that directs Covalent Data to nest another schema file within the original file. They are always denoted by embed(filename.yaml). In the above example, address.yaml is being embedded into the top level users.yaml file. A look at address.yaml reveals one note of interest:

address.yaml

# embed_me
address_1: {{randomNumber(20000)}} {{.streetname}} {{.roadtype}}
address_2: Apt. {{randomNumber(20)}}
city: {{.city}}
state: {{.state}}
zip: 66049

Notice the first line, a commented directive- embed_me. This directs Covalent Data to skip this file when creating objects and only using it to embed into another top-level schema. Any schema files without the keyword embed_me in the first line will be considered a top level schema, and Covalent Data will create objects and restful endpoints for it.

Datum file structure

A typical datum file will contain all the values used to seed mock data into initial CRUD objects. Datum files are simply .txt files with a specific filename. Each line break is considered one datum object.

firstname.txt

Sam
Buffy
Dean
Cordelia
Rupert

lastname.txt

Winchester
Summers
Winchester
Chase
Giles

Notice that in lastname.txt Winchester is repeated twice. This is deliberate, as the top level schema disables randomization. The effect of this is that two mock data objects will be created- Sam Winchester and Dean Winchester. With randomization enabled, it would be possible to get any combination of first and last names, and the second Winchester could be omitted from lastname.txt.

Running this schema would result in the following object-

  {
    "database_id": "cd56b1e7-0082-499a-badb-6504634c7ac5",
    "display_name": "Sam Winchester",
    "email": "[email protected]",
    "id": "sam.winchester",
    "mailing_address": {
      "address_1": "2506 Esperanza Court",
      "address_2": "Apt. 15",
      "city": "Lawrence",
      "state": "KS",
      "zip":   66049
    },
    "site_admin": 1
  }