Resource Descriptions

Attainable APIs are made from resource descriptions that are simple structures using familiar concepts and data types.

The design 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 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

Most APIs manage data that includes a form of relationship. 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 data 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 queryable.

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