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:

{
  "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:

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:

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 Query Dataset
• API Data Source