Docs/audience language review - #65
Open
olavgg wants to merge 7 commits into
Open
Conversation
Platform branch feat/resource-graph-export-import adds GET /resources/export/{id}
and POST /resources/import: a whole connected component, keyed by externalId,
as one gzip-compressed binary file, with import replaying the file through the
ordinary create pipeline in segments of 50 000 objects and skipping whatever
already exists so a re-upload resumes where a failed one stopped.
Nothing here covered it. Adds a section to the resources reference (what the
file carries and does not, the access each side needs, the skip rules, the
segment semantics, the summary body, the status codes, and a curl pair since
no client wraps the endpoints), a row in the client-coverage table, and the
transfer ceilings on the limits page.
One caution worth reading before trusting the 512 MB figure: the import upload
is not exempt from the general request-body cap, which defaults to 4 MiB and
is deployment-wide, so that is what a default deployment accepts. Written
from the filter code rather than the endpoint's own description.
Verified: npm run build succeeds.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Signed-off-by: Olav Gjerde <olav@intellistream.ai>
Platform branch fix/fetch-nearest-external-id makes POST /resources/fetch-nearest honour the externalId its form always declared; an externalId-only request used to reach the repository with a null id and come back as a 500. The page carried a caution saying the field was accepted but not read, and a table row saying numeric id only. Both are now wrong for the endpoint and for the Java form, so the caution goes and the row matches fetchRelated's. The Python and Rust clients still build the request from a numeric id alone, so the resolve-with-by_ids advice stays, scoped to them, and the example comments say which client the constraint belongs to rather than blaming the endpoint. Verified: npm run build succeeds. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Olav Gjerde <olav@intellistream.ai>
Platform PR #325 (fix(api): event time cannot be updated, so remove it from the update form) takes eventTime out of the event update form. The columnar store partitions events by their time and a row cannot move between partitions, so the api used to accept the field, answer 200 echoing the new value, and then fail to apply it; the field is gone from the form, and with the strict request reader an update naming it is a 400. The update section still listed eventTime among the updatable fields, said it was set from an ISO-8601 string, and counted it among the fields setNull is refused on. All three are replaced by the rule as it stands: eventTime is fixed at creation, an update naming it is refused, and the way to fix a mis-timed event is to delete and rewrite it or to write a correcting event. Verified: npm run build succeeds. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Olav Gjerde <olav@intellistream.ai>
Platform PR #324 (feat(api): reject request bodies naming fields the api does not have) switches the request-body reader from dropping unknown properties to refusing them: a 400 problem document of type .../errors/unreadable-request-body with one errors entry per offender, each a JSON Pointer plus the names its position accepts. Malformed JSON answers with the same type, and a line and column. Two pages here still described the old behaviour as a trap. events.md said a client sending the retired relatedResourceIds names got a 200 with its relations silently dropped; datasets.md said the api drops unknown keys, so a filter still carrying writeProtected looked like it was narrowing and was not. Both now say the request is refused and link to a new section on the client page that documents the response shape once, since it applies to every endpoint that reads a JSON body. Verified: npm run build succeeds. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Olav Gjerde <olav@intellistream.ai>
Platform PR #365 (chore: license the client libraries Apache-2.0) relicenses datahub-java-sdk and datahub-api-model from AGPL to Apache-2.0, aligning them with the Python and Rust SDKs, which were Apache-2.0 already. The reason is the one a developer evaluating the SDK needs to hear: a client library gets linked into someone else's application, and a copyleft one carries its terms into that application. Nothing on this site mentioned a licence at all, so a reader who checked the POM before this change would have chosen the REST API over the SDK, or something else. Adds a short section to the landing page: the SDKs and the wire model are Apache-2.0, the platform is AGPL-3.0, and which side each licence covers. Verified: npm run build succeeds. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Olav Gjerde <olav@intellistream.ai>
Apply the audience-language review to the reference pages, the guides
and the advanced scenarios. docs/industries is untouched: another open
branch rewrites those pages.
Register: reference pages now describe what the API is rather than what
it became. The "What changed" notes and the "used to", "now", "new" and
"previously" narration are gone from events, resources, datasets,
timeseries, edges, client, limits and external-ids. The one behaviour
that breaks an existing request (search.name and search.description)
keeps a one-line caution. Marketing phrases and long sentences were cut
or split.
Precision, checked against the platform and SDK sources of 2026-09-02:
- Events page with cursor/nextCursor; the <millis>_<id> "after" field
that external-ids documented does not exist. An undecodable cursor,
or one sent under a different sort, is a 400 (malformed-cursor), not
a restart from page one. The old relatedResourceIds field names are a
400 as unknown fields, not a silent 200. The filter limit defaults to
1 000. No event endpoint is HTTP-only.
- /assets/search applies its filter block; the search limit spans all
node types and POLICY nodes are searched; GET /functions/{id} answers
404 for an unreadable function; traversal nodes list the fields the
graph mirror holds; relatedResources is empty on /resources/{id},
byids, filter and search.
- Subscriptions: the listen path, the Bearer header on the upgrade, the
wire frame (subscriptionExternalId, messages[].messageId,
payload.eventAction, items[].datapoints with ISO-8601 UTC timestamps)
and what SubscriptionRetriever filters on.
- Time series: the RetrieveFilter fields, the four aggregate names, the
granularity units, the read-side timestamp types, and that values
cross the wire as strings. Python's Page is not a list subclass.
- Units: the seeded Celsius id is temperature_deg_c; the unit object's
fields; unit is free text and unitExternalId the catalogue key.
- MCP: edge_create only upper-cases, edge_create_type and label_create
snake-upper-case. Contributor content removed.
- Files: the one server path rule, per-client id types, failure
statuses, no size cap on PUT /files. Datasets: GET /datasets/policies
and the grant cache TTLs. Client: PROJECT_NAME row dropped (read by
every SDK, used by none); EntraID.md linked. Limits: /events/update
and /events/delete do not enforce the items cap, so the page says so.
Runnable examples: every non-industry guide and advanced page that
reads data opens with the same "Needs a sandbox" banner, one tip
follows it in one order, and pages that ended on a write now read it
back. Predictive maintenance works at the seed's 1 Hz, with the window,
the band and the alarm level derived from the healthy data; k-means
uses k=2 over four assets; attach-files downloads the id it uploaded;
ingestion builds its readings in Java and Rust and verifies the count;
model-assets-graph creates the series it links and reads the graph back
through fetchRelated; the seed helpers tolerate a 409 on a second run.
Naming: "data set", "time series", "organization", "catalogue" and
"relationship" in prose, outside identifiers, endpoint paths and code.
Not done: docs/industries, which another open branch owns; the sweep of
"edge" to "relationship" across the rest of resources.md and edges.md,
since both pages are about the /edges surface and the change would
touch most of their lines; the claim that sorting events by subType or
status cannot be paged, which the code no longer supports but which
needs a platform-side answer on nullable keyset boundaries; and the
Rust SearchForm, which always serialises name and description as null
and may trip the unknown-field rejection, an SDK matter rather than a
docs one.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Signed-off-by: Olav Gjerde <olav@intellistream.ai>
The conflict resolution while rebasing this branch left the note saying the same thing twice. One sentence, with the link to the unknown-field contract. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Signed-off-by: Olav Gjerde <olav@intellistream.ai>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.