Defining Resources

Resources are the core building blocks of your api.vision API. This guide explains how to define resources, their fields, and the options available to you.

What is a Resource?

A resource represents an entity or object in your API, such as a user, product, or post. In RESTful terms, resources are the nouns in your API that clients can interact with via CRUD operations (Create, Read, Update, Delete).

Each resource in api.vision:

Has a unique name (usually plural, like "users" or "products")
Contains a set of fields that define its structure
Can have relationships with other resources
Automatically gets RESTful endpoints for CRUD operations

Basic Resource Definition

To define a resource, you need to specify its name and fields:

{
  "name": "products",
  "fields": [
    {
      "name": "id",
      "type": "number",
      "defaultValue": "$increment"
    },
    {
      "name": "name",
      "type": "string",
      "required": true
    },
    {
      "name": "price",
      "type": "number",
      "required": true,
      "min": 0
    },
    {
      "name": "description",
      "type": "string"
    },
    {
      "name": "inStock",
      "type": "boolean",
      "defaultValue": true
    }
  ]
}

Resource Properties

Property	Type	Required	Description
`name`	String	Yes	The resource name (plural recommended)
`fields`	Array	Yes	Array of field definitions
`relationships`	Array	No	Array of relationship definitions
`description`	String	No	Human-readable description of the resource

Naming Conventions

Following proper naming conventions helps create a consistent, intuitive API. Here are some recommendations:

Use Plural Nouns for Resources

Good:

users, products, orders

Avoid:

user, product, order

Use camelCase for Field Names

Good:

firstName, createdAt, phoneNumber

Avoid:

first_name, created_at, PhoneNumber

Use Descriptive, Clear Names

Good:

shippingAddress, isActive, paymentMethod

Avoid:

addr, flag, pmt

Field Definitions

Fields define the properties of your resources. Each field requires a name and type, plus optional constraints:

Property	Type	Required	Description
`name`	String	Yes	The field name (camelCase)
`type`	String	Yes	Data type (string, number, boolean, date, object, array)
`required`	Boolean	No	Whether the field is required (default: false)
`defaultValue`	Any	No	Default value if not specified
`unique`	Boolean	No	Whether the field value must be unique across all records
`description`	String	No	Human-readable description of the field

Additionally, different field types support their own specific validation properties:

String Fields

Property	Type	Description
`minLength`	Number	Minimum string length
`maxLength`	Number	Maximum string length
`pattern`	String	Regular expression pattern for validation
`enum`	Array	List of allowed values

Number Fields

Property	Type	Description
`min`	Number	Minimum value
`max`	Number	Maximum value
`multipleOf`	Number	Value must be a multiple of this number

Array Fields

Property	Type	Description
`items`	Object	Schema for array items
`minItems`	Number	Minimum number of items
`maxItems`	Number	Maximum number of items
`uniqueItems`	Boolean	Whether items in the array must be unique

Object Fields

Property	Type	Description
`properties`	Object	Schema for object properties
`required`	Array	List of required property names

Example Resource Definitions

User Resource

{
  "name": "users",
  "fields": [
    {
      "name": "id",
      "type": "number",
      "defaultValue": "$increment"
    },
    {
      "name": "username",
      "type": "string",
      "required": true,
      "minLength": 3,
      "maxLength": 30,
      "unique": true
    },
    {
      "name": "email",
      "type": "string",
      "required": true,
      "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$",
      "unique": true
    },
    {
      "name": "password",
      "type": "string",
      "required": true,
      "minLength": 8
    },
    {
      "name": "role",
      "type": "string",
      "enum": ["user", "admin"],
      "defaultValue": "user"
    },
    {
      "name": "createdAt",
      "type": "date",
      "defaultValue": "$now"
    },
    {
      "name": "isActive",
      "type": "boolean",
      "defaultValue": true
    }
  ]
}

Product Resource

{
  "name": "products",
  "fields": [
    {
      "name": "id",
      "type": "number",
      "defaultValue": "$increment"
    },
    {
      "name": "name",
      "type": "string",
      "required": true
    },
    {
      "name": "description",
      "type": "string"
    },
    {
      "name": "price",
      "type": "number",
      "required": true,
      "min": 0
    },
    {
      "name": "category",
      "type": "string",
      "enum": ["electronics", "clothing", "books", "furniture", "other"],
      "required": true
    },
    {
      "name": "tags",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    {
      "name": "inStock",
      "type": "boolean",
      "defaultValue": true
    },
    {
      "name": "attributes",
      "type": "object",
      "properties": {
        "color": { "type": "string" },
        "size": { "type": "string" },
        "weight": { "type": "number" },
        "dimensions": {
          "type": "object",
          "properties": {
            "length": { "type": "number" },
            "width": { "type": "number" },
            "height": { "type": "number" }
          }
        }
      }
    }
  ]
}

Best Practices for Resource Design

Include ID Fields

Always include an ID field for each resource, preferably using auto-increment or UUID generation. This makes resource referencing and relationships easier.

Use Timestamps

Including createdAt and updatedAt fields helps track when resources were created or modified, which is useful for debugging and filtering.

Define Validation Constraints

Always add appropriate validation rules to fields to ensure data integrity and realistic behavior in your API.

Keep Resources Focused

Each resource should represent a single concept. Break down complex entities into multiple related resources rather than creating monolithic resources.

Next Steps

Now that you understand how to define resources, you can:

Learn more about field types and options in detail
Explore how to set up relationships between resources
Discover querying capabilities for interacting with your API resources

Tip: Resource Templates

api.vision provides pre-built resource templates for common entities like users, products, and posts. You can use these as starting points and customize them for your specific needs.