Entities - Intro

Entities are core of nodb, forming the nested JSON structure of your data.

You can create arbitrary data models, similar to document based NoSQL database models.

To work with entities you already need to have (1) an app, (2) environment and (3) access token.

How it works?

In nodb JSON data form restful API paths.

Entities are created by sending a POST request to the named path or named route (for example '/books'). This path will define your entity name.

How to create an entity?

1. The named path comes after app/environment path: /app-name/dev/entity-name
2. Sending a POST request to such path will form entity-name entity.

curl -X POST https://api.nodb.sh/app-name/dev/entity-name?token=1234567abcdefg

[{
  "prop": "value",
  "propNumber": 123
}]

note

To create entities we send array of objects, even if you're saving only one entity.

danger

Remember that 'token' is a reserved query param in nodb to protect access to your API. Meaning that entities shouldn't have a prop with that name.

Fetch entities

Sending a GET request to the same path will return all entities with that name. The result will be paginated with default page limit set to 10 (if omitted).

curl https://api.nodb.sh/app-name/dev/entity-name?token=1234567abcdefg

// Result:
{
  "entity-name": [
    {
      "id": "s6cfniz9",
      "prop": "value",
      "propNumber": 123,
      "__meta": {
        "self": "/app-name/dev/entity-name/s6cfniz9",
        "subtypes": {}
      }
    }
  ],
  "__meta": {
    // Pagination props go here
  }
}

Sending GET request to fetch a single item is possible with the use of autogenerated id:

curl https://api.nodb.sh/app-name/dev/entity-name/s6cfniz9?token=1234567abcdefg

Supported methods

All HTTP methods are supported:

1. GET: fetch single or more entities
2. POST: create single or more entities
3. PUT: replace single or more entities
4. PATCH: update single or more entities
5. DELETE: delete single or more entities

How are POST, PUT & PATCH different?

In traditional restful apps we usually use POST to create things, as seen in HTML Forms. In nodb we use POST to create entities, meaning we don't need id.

For both PUT and PATCH we need an id. They are used to replace and update entities, respectively.

However, since we send array of objects, the following example of 3 items array shows the behavior of each method:

POST  [{ id, ... }, {...}, { id, ... }]  -> replace two, insert one
PUT   [{ id, ... }, {...}, { id, ... }]  -> replace two, ignore one
PATCH [{ id, ... }, {...}, { id, ... }]  -> update two, ignore one

note

PATCH updates (merges) JSON objects with the body payload. PUT replaces the JSON object with the body payload.

Entity name pattern

Entity names are defined by named routes.

Entity name follows the hyphenated url pattern.

Valid entity names: "single-player" or "bottles".