Skip to main content


Custom entity helps with metadata management for the control plane. Custom entities come with auto-generated REST APIs (could be used to provide public APIs for control plane users), real time lifecycle events needed for control plane/data plane integration.

Data Model Concepts


In the Nile model, Entities have a Schema. So a normal development flow will have two steps:

⚠️ The APIs below are to illustrate the concepts and are subject to change ⚠️

  1. Define a schema or modify the schema for an entity. The schema definition language is JSON Schema with some unique extensions that we will explain farther below:

    Example The schema for a cluster that is provisioned by a control plane would look like something below

    POST /entities
    "name": "cluster",
    "schema": {
    "type": "object",
    "properties": {
    "system" : {
    "creator": {"type": "string"},
    "created": {"type": "string"},
    "updated": {"type": "string"},
    "cluster_name": {"type": "string"},
    "status": {"type": "string"},
    "ARN": {"type": "string"},
    "Endpoint": {"type": "string"}
    "required": ["cluster_name"]
  2. Create entity instances with this schema. If an entity is like a database table, entity instances are equivalent to rows. If an entity is like a model, entity instances are equivalent to records:

    POST /cluster

Nile enforces the schema, so this will fail:

"cluster_name": "test_cluster",
"status": 56

"message": "Invalid type. Expected String but got a Number",
"error_code": "schema_validation_failed",
"status_code": 400

Note that in addition to the schema that you define for custom entities, there are default fields that exist for all entities in Nile - including custom entities.

Additional keywords in schema definitions (coming soon)

  • A property can be defined as unique and Nile will enforce unique constraint on this property For example:

      "cluster_name": {
    "type": "string",
    "unique": true
  • A field can refer to an existing entity. For example:

    "creator": {
    "type": "string"
    "foreignKey": ""

    When retrieving entity instances, by default only the id of the foreign key will be returned, and a link will be provided in the headers (see below for more details about Nile's use of HTTP link headers). For example:

     "data": {
    "creator": ""

    If expand=true is specified when retrieving the entity, the referred resources will be embedded in the response. For example:

    "data": {
    "creator": ""
    "expand": {
    "user": {
    "": {
    "id": "user-sofui8903",
    "email": "",
    "org": "org-slkdfjsokf"
    // ...AdditionalProperties


Entities are unlike DB tables in an important way: There are no transactions on entities. Not for multiple instances in an entity and not for changing multiple entities.

API Concepts

Nile entities have two types of APIs:

  • Data APIs that are used to create, read, update, and delete instances of entities. For Example: GET /users will return a list of all the users that the requester is allowed to view in their current context.
  • Developer APIs that Nile Developers use to read or update the entities themselves. For example: GET /admin/users will return the schema for the entity Users.

Nile APIs are flat and use query params as filters. For example /users?orgId=1 returns all users that belong to organization 1. More details on how to query entities is included in the API documentation (Link TBD).

Getting an entity will return all information about the entity. For example /users/1 will return all the information for user 1, including the ids of all the organizations it belongs to. Nile is considering adding fieldmasks to include/exclude fields and an option to expand fields, but we believe the simple approach is preferred at this point.

The APIs for built-in entities are documented in detail in the Concepts documentation for each entity and in Nile's API reference (Link TBD). Refer to user-defined entities for more details on APIs that are auto-generated when you create new entities.

Configurable Rate Limits


Events (Coming soon)

All entities publish events when entity instances are created, updated and deleted. Built-in entities may publish additional events. Clients can subscribe to these events via Nile's SDK. Refer to events concept page to learn more about Nile events in general.

Metrics (Coming soon)

Each entity has built-in metrics for API usage rates by API and response status code.

Enriched Functionality