About the two APIs
Picked has two HTTP APIs, and a new reader often reaches for the wrong one. This page covers which is which and why they are separate.
The split
| Delivery API | Management API | |
|---|---|---|
| Style | REST | GraphQL |
| Access | Public, anonymous | Authenticated |
| Operations | Read-only | Read and write |
| Base | https://api.picked.app/api/v1 | POST https://api.picked.app/api/graphql |
| Use it to | Serve published configuration and content to your application | Control your projects, experiences, and content |
The short rule is this: the Delivery API serves your visitors, and the management API serves you.
Why they are not one API
Three properties of the delivery path make it a different kind of API.
It is anonymous. A crawler must read your published page content with no credential at all. An API that requires a token cannot serve a search engine, and an API that serves a search engine cannot require one.
It is cacheable. A published response is the same for every reader, so a shared cache
can hold it. The Delivery API sends s-maxage for an SDK request, and it sends
Vary: Picked-Client. A GraphQL endpoint that takes any query over a POST has none of
those properties.
It is read-only. Nothing that a reader reaches without a credential can change your data. Every write stays on a separate authenticated surface, so that property holds by design.
What the Delivery API serves
Two endpoints, and the SDK calls both:
- Project config returns the published configuration of a project: its experiences and steps, and the content link on each step.
- Experience content returns the content entries behind an experience.
Your server usually calls the first and lets serialize() call the second. See
About server-side rendering.
How a preview stays out of the search index
A preview needs unpublished content, and by the definition of it that content is not
public. The Delivery API takes a preview_token query parameter for exactly that. It then
treats the result differently. versionId comes back null, the response is no-store,
and robots.txt does not allow the preview path.
That last part matters more than it looks. A draft that anybody can read over an anonymous URL is a draft that a search engine can find. A campaign page that is only part complete can then appear in the search results of a customer.
Related
- Delivery API — the endpoints and their responses.
- Management API — authentication and scopes.
- Preview, cache, and crawlers — the
exact cache rules and
robots.txtrules.