Repository navigation
Document API template paging and child calls in Preview - #772
Open
kilian-tennyson wants to merge 5 commits into
Open
kilian-tennyson wants to merge 5 commits into
kilian-tennyson wants to merge 5 commits into
Conversation
Adds tree.paging (page_number) and tree.child_calls to the api_template schema with their checks, and updates the sync text: whole-tree listing, 404 handling, per-try listing and request limits, how depth counts across child calls, and the X-RateLimit-Reset header.
Templates no longer take variables: values are written into the template, placeholders come only from a call's node_values, and sending variables fails the create request. The examples inline their values and the source no longer returns variables. tree.paging and child call paging accept the page_number, offset and cursor styles, each with its own key. A list without paging whose response says it has more fails the create request and the sync. auth, tree.content_if, body_format and item can be left out, mapping can read everything from the node when there is no item, and a missing mapping.updated_at fails the create request.
Gives paging its own sentence in the api_template overview, lists which failed requests make Intercom retry a sync, and documents the base_url invalid check for a host whose percent-encoding isn't valid UTF-8.
This branch has not been deployed
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
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.
Why?
The Preview API template docs are out of date. They still say a sync sends one tree request and that paging isn't supported, they still describe template
variables, and they mark fields as required that now have defaults. Templates are written against this reference, so wrong docs lead to templates that fail to create or sync.How?
All changes are in the Preview spec (
descriptions/0).tree.pagingandtree.child_calls, with their checks and error codes.paginghas three styles:page_number(withpage_count),offset(withtotal) andcursor(withnext_cursor). The sync text covers whole-tree listing, the per-try limits, how depth counts across child calls, and 404 handling.pagingwhose response says it has more pages fails the sync. If the tree call does this during the token check, the source isn't created. The docs list the response fields that count as "has more".variablesis gone from the template, the create request and the source response. Values are written into the template itself. Sendingvariablesfails with a422. Placeholders are now filled only fromnode_valuesin the item request and child calls.authdefaults toAuthorization: Bearer {token}(no header when a query value is{token}). Withoutcontent_if, every node is content.body_formatdefaults tohtml.itemis optional, and without itmappingreads only fromnode. Onlyname,base_url,treeandmappingare required. A stored template is returned without the defaults filled in.mapping.updated_at, forvariablesbeing sent, and for undeclared paging.Decisions
mapping.updated_atis documented as required at create, because the create check requires it today.mapping.metadatais accepted on create but isn't documented yet, because what it does isn't available yet.latest_syncand the sync endpoint are unchanged. They were already incomplete about403and first-page404responses, and fixing them is outside this change.