---
url: /v6.2/en-us/api-data-service-faq.md
---
# Data Service and API

Many API questions are not about missing capability. The real problem is that teams have not first separated **API Service**, **API Query Dataset**, and **API Data Source**. This page explains those boundaries first.

## What is the difference between API Service, API Query Dataset, and API Data Source?

They solve three different problems:

|Capability|Best for|
|-|-|
|API Service|Publishing charts, datasets, or connection-backed results from HENGSHI as callable APIs|
|API Query Dataset|Turning one HTTP JSON API directly into an analyzable dataset|
|API Data Source|Connecting an external API platform as a reusable data connection|

If your goal is "expose results from HENGSHI to external systems," start with **API Service**.\
If your goal is "pull an external HTTP API into HENGSHI," start with **API Query Dataset** or **API Data Source**.

## Why does token application fail with `unauthorized`?

A very common reason is that you are **sending the token request while still carrying a logged-in cookie**.

Typical error:

```json
{
  "error": "unauthorized",
  "error_description": "There is no client authentication. Try adding an appropriate authentication filter."
}
```

Check first:

1. Whether the request to `/api/oauth2/server/tokens` still carries an active cookie
2. Whether the request environment was copied directly from a browser login session

The fastest fix is usually: **remove the cookie header or log out before requesting the token**.

## Is there an API for adding custom fields to a dataset?

Yes.

You can add dataset fields through:

```text
POST /api/apps/${appid}/datasets/${datasetid}/fields
```

Typical uses:

* automatically creating formula fields
* batch field creation
* external-system-driven dataset enrichment

If your real requirement is "programmatically add fields at scale," this API is usually better than manual page editing.

## When should I use API Query Dataset versus API Data Source?

Use this shortcut:

|Scenario|Better fit|
|-|-|
|Quickly turn one HTTP JSON endpoint into a dataset|API Query Dataset|
|Connect an external API platform as a long-term reusable source|API Data Source|
|Expose HENGSHI internal results outward|API Service|

If you mainly need to configure Header, Query, Body, pagination, and quickly start analysis, **API Query Dataset** is usually the shorter path.\
If you need a long-lived normalized connection to an API platform, that is closer to **API Data Source**.

## Do custom API data sources always require Groovy?

Only when built-in API data sources are not enough.

And note: **since 5.1, page-entered Groovy script is disabled by default**. If you need to create a custom API data source through page-level Groovy, enable it explicitly:

```properties
ENABLE_GROOVY_SCRIPT=true
```

A restart is required after the change.\
If you upload Groovy scripts to the server and manage them through `EXT_API_PATH`, that path is not controlled by the page-level switch.

## What is the minimum structure for an API data source definition?

At minimum it should implement these four functions:

* `getApiName`
* `setOptions`
* `getPathTables`
* `fetchTableData`

If these basics are incomplete, selecting the API Name in the UI will not be enough to produce a usable connection.

## When should I use registered APIs instead of writing a backend from scratch?

Registered APIs are a good fit when you mainly want to **wrap a third-party API as a controlled standard interface** and reuse HENGSHI features such as publish, authorization, rate limiting, and monitoring.

Good fits:

* standardizing an API entry point
* passing parameters through or fixing some parameters
* adding a controlled gateway layer to third-party APIs

If the real requirement has become complex orchestration, long-running business state, or heavy backend computation, a registered API is no longer the whole answer.

## What should I check first when troubleshooting API issues?

Split by layer first:

|Symptom|Check first|
|-|-|
|Token request fails|Auth parameters, cookie state, client configuration|
|External HTTP API cannot be pulled in|Header / Query / Body / pagination / auth method|
|Custom API data source does not work|Groovy switch, script structure, `API Config` parsing logic|
|Published API returns unexpected results|Bound datasets/charts, default parameters, published version|

If you have not even separated which API capability you are using, troubleshooting usually becomes noisy and slow.

Further reading:

* [API Service](api.md)
* [API Query Dataset](dataset-api.md)
* [API Data Source](connecting-ext-api.md)