Metadata Endpoint

Overview

This endpoint provides information about the entities/tables configured for the current set of credentials — i.e. for the combination of tenant, clientId, and configurationId.

In other words, for the configuration associated with your current credentials, this endpoint gives you access to information about the entities/tables you’re entitled to retrieve data for.

By default, if no specific configuration is provided, the endpoint returns metadata for the default configuration only. If you specify a concrete ConfigurationId, it will return metadata for that configuration alone — the endpoint always returns exactly one configuration per request.

Base URL

https://data.youforce.com/data/v1/metadata

Authentication

All requests require a Bearer token in the Authorization header.

Endpoint

Retrieve entity metadata

GET /data/v1/metadata

Parameters

Type Name Description
Header Authorization Bearer token (required)
Path — None
Query EntityName Explicit name of the entity whose configuration should be retrieved. Several entities may be configured across different configurations.
Query EntityVersion If an entity has multiple versions, this retrieves the configuration for that specific version only.
Query ConfigurationId Id of a specific configuration for the clientId. If omitted, only the default configuration is returned.
Body — None

Request example

curl --location 'https://data.youforce.com/data/v1/metadata?EntityName=sickness-case&EntityVersion=1&ConfigurationId=testing-default-4028868' \
--header 'Authorization: Bearer abc'

Response

200 OK

Field Description
items[].name Name of the entity
items[].version Version of the entity
items[].odsName Name of the underlying table the information is extracted from
items[].configurationId Configuration Id this entity belongs to
items[].fields[].name Name of the field as shown in the output
items[].fields[].odsName Name of the field in the underlying table
items[].fields[].type Data type of the field (e.g. String, Int32)
items[].fields[].isKey Whether the field is part of the entity’s key
items[].fields[].isSelected Whether the field is selected to be included in the output

Response example

{
    "items": [
        {
            "name": "person",
            "version": 1,
            "odsName": "TBL_Person",
            "fields": [
                {
                    "name": "Id",
                    "odsName": "ID",
                    "type": "Int32",
                    "isKey": true,
                    "isSelected": true
                },
                {
                    "name": "PersonBK",
                    "odsName": "Person_BK",
                    "type": "String",
                    "isKey": false,
                    "isSelected": true
                },
                {
                    "name": "FirstName",
                    "odsName": "PersonFirstName",
                    "type": "String",
                    "isKey": false,
                    "isSelected": true
                },
                {
                    "name": "LastName",
                    "odsName": "PersonLastName",
                    "type": "String",
                    "isKey": false,
                    "isSelected": true
                }
            ],
            "configurationId": "testing-default-4028868"
        }
    ],
    "totalCount": 7,
    "currentPage": 1,
    "pageSize": 10,
    "totalPages": 1,
    "hasPreviousPage": false,
    "hasNextPage": false
}

Pagination

The Metadata endpoint returns paginated results. The following fields describe the pagination state:

Field Type Description
pageSize integer Number of configured mappings included in the response. Default: 10.
totalCount integer Total number of configured mappings in the database.
totalPages integer Total number of pages, given the current pageSize and totalCount.
currentPage integer The page number being retrieved. Must be less than or equal to totalPages. Default: 1.
hasPreviousPage boolean Whether a page exists before the current one.
hasNextPage boolean Whether a page exists after the current one.

How to page through results

1. First request, no pagination parameters specified

  • currentPage defaults to 1.
  • pageSize defaults to 10.
  • Check the response’s totalPages to see how many pages are available, and hasNextPage to see if there’s more data after this page.

2. First request, with pagination parameters specified

  • Choose your desired currentPage (default 1) and pageSize (default 10).
  • Check the response’s totalPages, hasPreviousPage, and hasNextPage to understand your position in the result set.

3. Looping through all pages

  • While hasNextPage is true, increment currentPage by 1 and repeat the request.
  • Once hasNextPage is false, you’ve reached the last page and can stop.

Summary of Key Behaviors

Scenario Result
No ConfigurationId specified Only the default configuration’s metadata is returned
ConfigurationId specified Only that specific configuration’s metadata is returned
No pagination parameters specified currentPage: 1, pageSize: 10 are used by default
hasNextPage: true More pages are available; increment currentPage and request again
hasNextPage: false Last page reached; stop looping