Resource Descriptions

You design your API with a resource description, using YAML syntax and familiar data types. The data of your API can be described through “resources” that have named fields.

resource: # the name of the resource
  field: string # name of a property with a data type
  day: datetime # all dates are stored UTC in RFC-3399 standard format
  active: boolean
  object: # a nested structure
    size: number
  associations: << association # a resource can have many associations

association:
  resource: < resource # an association belongs to a resource

Data Types

Describing the data your API manages is simple and familiar. The following data types are available:

String: string
Number: number
Boolean: boolean
Date/Time: datetime
Relationships: << and <
Object: nested structures

Relationships

In many cases resources will have associations to each other. These are typically represented as belongs to and has many descriptions.

< Belongs To: This represents that this resource points to another single resource. You can think of this as “one-to-one” or “foreign key”.
<< Has Many: This represents that this resource has many relationships to another resource. You can relate this to “one-to-many” or “parent child”.

The left-hand side of the field description can be named anything you like (plurality etc.), but the right-hand side must be the name of another resource in the description.

Automatic Fields

Each resource is provided an identifier field along with date fields for when it was created and for every update. These are automatically managed by the API and can be used in URL query options.

Automatically generated fields for each resource:

id: a unique identifier for the resource
createdat: a datetime field representing when the resource was created
updatedat: a datetime field recording the datetime of the last update to the resource