Your First Five Minutes: Creating and Relating Entities with Nouns.do

Tired of juggling complex database schemas, writing endless boilerplate code for ORMs, and struggling to keep your data models in sync with your business logic? In a modern software stack, your business data—your customers, products, orders, and projects—is often fragmented across different services and databases. This creates a tangled web that's difficult to manage, query, and evolve.

What if you could model your entire business world—all the people, places, things, and ideas—as simple, interconnected objects?

Welcome to Nouns.do. We provide a universal entity management API that lets you define, relate, and manage any business entity as code. This isn't just a database; it's a higher-level, business-aware layer for your data.

In the next five minutes, we'll walk you through the core power of Nouns.do: creating your first entities and, more importantly, relating them to each other.

The Goal: Modeling a Simple E-commerce Scenario

To demonstrate the power of Nouns.do, we'll model a fundamental business process: a customer placing an order for a product. This involves three core "nouns" or entities:

1. A Product: The item for sale.
2. A Customer: The person buying the item.
3. An Order: The transaction that connects the Customer and the Product.

Let's get started.

Step 1: Create a 'Product' Entity

First, let's define a product. In Nouns.do, an entity is just a JSON object with a type you define and a properties block for its attributes.

To create our first product, we'll send a POST request to the /v1/entities endpoint.

Request:
POST /v1/entities

Payload:

{
  "type": "Product",
  "properties": {
    "name": "The Pragmatic Programmer",
    "sku": "BK-PRG-20",
    "price": 3995,
    "currency": "USD"
  }
}

The API will process this request and return a new entity object, complete with a unique ID.

Response:

{
  "id": "prod_1a2b3c4d5e6f7g8h",
  "object": "entity",
  "type": "Product",
  "properties": {
    "name": "The Pragmatic Programmer",
    "sku": "BK-PRG-20",
    "price": 3995,
    "currency": "USD"
  },
  "relationships": {}
}

Excellent. We now have a Product entity in our system. Take note of its id: prod_1a2b3c4d5e6f7g8h. We'll need it in a moment.

Step 2: Create a 'Customer' Entity

Next, let's create a customer using the same process. This entity has different properties, but the structure of the API call is identical. This is the power of a universal system—you use the same simple pattern for everything.

Request:
POST /v1/entities

Payload:

{
  "type": "Customer",
  "properties": {
    "name": "Jane Doe",
    "email": "jane.doe@example.com",
    "status": "active"
  }
}

Response:

{
  "id": "cus_9i8j7k6l5m4n3o2p",
  "object": "entity",
  "type": "Customer",
  "properties": {
    "name": "Jane Doe",
    "email": "jane.doe@example.com",
    "status": "active"
  },
  "relationships": {}
}

We now have a Customer entity. Its ID is cus_9i8j7k6l5m4n3o2p.

Step 3: Relate Them with an 'Order' Entity

So far, we have a product and a customer. They exist independently. Now for the magic. Let's create an Order entity that connects them.

This is where the relationships block comes into play. We'll create our Order and use the IDs from the previous steps to formally link it to our customer and the product they're buying.

Request:
POST /v1/entities

Payload:

{
  "type": "Order",
  "properties": {
    "status": "pending",
    "amount": 3995,
    "currency": "USD",
    "createdAt": "2023-10-28T14:30:00Z"
  },
  "relationships": {
    "customer": "/v1/entities/cus_9i8j7k6l5m4n3o2p",
    "product": "/v1/entities/prod_1a2b3c4d5e6f7g8h"
  }
}

Response:

{
  "id": "ord_7q6r5s4t3u2v1w0x",
  "object": "entity",
  "type": "Order",
  "properties": {
    "status": "pending",
    "amount": 3995,
    "currency": "USD",
    "createdAt": "2023-10-28T14:30:00Z"
  },
  "relationships": {
    "customer": "/v1/entities/cus_9i8j7k6l5m4n3o2p",
    "product": "/v1/entities/prod_1a2b3c4d5e6f7g8h"
  }
}

And just like that, you've modeled a complex business relationship.

Why This is a Game-Changer

In just a few minutes and with three simple API calls, you've achieved something that would typically require:

• Designing three different SQL tables (products, customers, orders).
• Setting up foreign key constraints and join tables.
• Writing application-level code (an ORM) to map these tables to objects.
• Creating custom API endpoints to expose each object.

With Nouns.do, you simply described your business nouns and how they relate. Our API handles the storage, indexing, and relational logic. You can now make powerful queries, like fetching an order and easily navigating to the related customer and product details through the API, without ever writing a JOIN statement.

What's Next?

You just defined your first few entities as code. Now, think about the rest of your business. What are your nouns?

• Users and Teams?
• Projects, Tasks, and Comments?
• Locations, Events, and Attendees?

With Nouns.do, you can model them all using the same simple, powerful API.

Ready to stop wrestling with your database and start modeling your business? Sign up for Nouns.do today and bring your business world into code.