Discoverability & Pagination

One of the main characteristics of nodb, besides easily manageable REST API via entities, is discoverability or self-documenting of your data. This means that you don't really need docs for your API, you can discover it yourself.

So far nodb supports meta data on single entity level and on entitiy lists for pagination.

Meta data on a single entity

As of now, meta data for single entity supports:

1. Link to itself
2. Links to sub-entities, if there are any.

Example of what's inside the result of a GET request:

{
  "id": "7cqbamkt",
  "fruit": "Apple",
  "__meta": {
    "self": "/my-app/dev/fruits/7cqbamkt?token=5hixdgejlvjyq0",
    "subtypes": {
      "varieties": "/my-app/dev/fruits/7cqbamkt/varieties?token=5hixdgejlvjyq0"
    }
  }
}

To traverse through the data, using '__meta' you can get links from the response in your code instead of calculating them yourself.

Meta data on lists (Pagination)

Similarly, there's meta data for lists which is mainly used for pagination.

Example of a paginated result:

{
  "fruits": [
    {
      "id": "7cqbamkt",
      "fruit": "Apple",
      "__meta": {
        "self": "/my-app/dev/fruits/7cqbamkt?token=5hixdgejlvjyq0",
        "subtypes": {
          "varieties": "/my-app/dev/fruits/7cqbamkt/varieties?token=5hixdgejlvjyq0"
        }
      }
    },
    {
      "id": "a2ebymi1",
      "fruit": "Kiwi",
      "__meta": {
        "self": "/my-app/dev/fruits/a2ebymi1?token=5hixdgejlvjyq0",
        "subtypes": {}
      }
    },
    {
      "id": "tov3rre4",
      "fruit": "Lime",
      "__meta": {
        "self": "/my-app/dev/fruits/tov3rre4?token=5hixdgejlvjyq0",
        "subtypes": {}
      }
    }
  ],
  "__meta": {
    "total": 23,
    "items": 3,
    "page": 2,
    "next": 3,
    "previous": 1,
    "pages": 8,
    "first_page": "/my-app/dev/fruits?__page=1&__per_page=3&token=5hixdgejlvjyq0",
    "last_page": "/my-app/dev/fruits?__page=8&__per_page=3&token=5hixdgejlvjyq0",
    "next_page": "/my-app/dev/fruits?__page=3&__per_page=3&token=5hixdgejlvjyq0",
    "previous_page": "/my-app/dev/fruits?__page=1&__per_page=3&token=5hixdgejlvjyq0"
  }
}

Where:

1. "total" is amount of items for that entity name (fruits)
2. "items" is amount of items on the current page
3. "page" is current page number
4. "next" is next page number
5. "previous" is previous page number
6. "pages" is amount of pages
7. The rest are links to various pages.

Custom pagination query params

Pagination supports two query params __page and __per_page.

1. __page query param tells nodb which page to query
2. __page_page query param tells nodb how many items per page to display.

info

Double underscore notation is reserved for nodb keywords. It might happen that an entity has a "page" property. Putting two underscores in front reduces this conflict.