Spec Files

A spec file provides the definition of your Restful project. Spec files are the root of our platform, and very similar to other API specification protocols such as OpenAPI, API Blueprint, and SDL. Spec files can be used to automatically generate these other types of documents, providing a high-level abstraction layer around your data.

Creating a spec

Spec files are a valid document of one of two types, JSON or YAML, and named as spec.json or spec.yml respectively within your project's root directory.

Defining your project

A spec file begins by defining the project.

Example (./spec.yml)
---
name: Your Project
slug: your-project
version: 1.0.0

Here are the available properties:

Prop Type Description required default
auth String Please see more about User Accounts here false 'none'
basePath String The base route path to mount the API to. If your API should be mounted to root, please use '/'. false '/api'
db String The MongoDB connection string (please see note below) true N/A
host String The host value for where this API is/will be deployed. false 'http://localhost:3000/api/'
models Array An array of data model objects to be defined in your project. true N/A
name String The name of your API project. true N/A
port String The port number to run the API server on. false '3000'
slug String A slugified version of your API project name, without spaces or special characters. true N/A
ssl Boolean Whether or not to use SSL encryption for client network requests. false false
version String The version of your API project. true N/A

NOTE

Right now, the db property is used to connect your own MongoDB instance to your Restful project. This will change as we ship our 1.0, and projects will come "batteries included" with hosted development DB instances, at which pointed db will become an optional property.

Defining data models

Data models live in the models property of your project.

Example (./spec.yml)
name: Your Project
...
models:
  - name: User
  - props:
    - ...
  - name: Event
  - props:
    - ...

Here are the available properties for data models:

Prop Type Description required
name String The name of the model. See more about model names below. true
props Array An array of model properties. See more about defining model properties below. true

Naming Data Models

Here are a few things to keep in mind when naming models:

  • Names should start with an uppercase letter (i.e. User).
  • Names cannot contain spaces or any special characters besides "_" (underscore).
  • Names should clearly define the data being represented by the model without being redundant.
  • Model names must be unique - you can't name two models the same thing.

Defining model properties

Model properties live in the props property of the data model.

Example (./spec.yml)
...
models:
  - name: User
  - props:
    - key: email
      type: String
      unique: true
      required: true
    - key: name
      props:
        - key: first
          type: String
        - key: last
          type: String

Here are the available model properties:

Prop Type Description required
key String The key of the model. See more about prop keys below. true
type String A Mongo schema type, i.e. String, Number, Boolean, [Object] (array of objects), [model] (array of model records), etc. See more about prop types below. true (unless using props property)
props Array An array of model properties. See more about defining model properties below. true
required Boolean Whether the given prop is required for all model records false
unique Boolean Whether the given prop's value should be unique between model records. false
default String A default value for new model records. See more about prop defaults below. false
model String A reference to another model via name. Use this in conjunction with prop type model to create relationships between data models. false

Prop Keys

Here are a few things to keep in mind when defining prop keys:

  • Keys cannot contain spaces or any special characters besides "_" (underscore).
  • Keys should clearly define the data being represented by the property without being redundant.
  • Prop keys must be unique - you can't use the same key for two different props within the same model (using within other models is fine).

Prop Types

Here are all currently available prop types:

  • String
  • Number
  • Date
  • Boolean
  • Object
  • model (used to define type as another model to create relationships between them)
  • [<nested-type>] i.e. [String], [Object], [model]

Prop Defaults

A prop default can be any string except for a few predefined terms that are used for common default values:

  • timestamp - adds a default value of a DateTime timestamp