# Try it out

Source: https://apigenie.pl/docs/reference/doc-components/try-it-out
Part of the reference of [@mykulyak/apigenie-docs](https://apigenie.pl/docs/reference/doc-components.md).
Its other pages: [apg-api-reference and apg-spec](https://apigenie.pl/docs/reference/doc-components/reference-and-spec.md), [OpenAPI elements](https://apigenie.pl/docs/reference/doc-components/openapi.md), [Swagger 2.0 elements](https://apigenie.pl/docs/reference/doc-components/swagger.md), [AsyncAPI elements](https://apigenie.pl/docs/reference/doc-components/asyncapi.md), [Protobuf and gRPC elements](https://apigenie.pl/docs/reference/doc-components/protobuf.md), [GraphQL elements](https://apigenie.pl/docs/reference/doc-components/graphql.md), [Building blocks](https://apigenie.pl/docs/reference/doc-components/building-blocks.md), [Theming](https://apigenie.pl/docs/reference/doc-components/theming.md), [Server-side rendering](https://apigenie.pl/docs/reference/doc-components/server-side-rendering.md), [apigenie-docs build](https://apigenie.pl/docs/reference/doc-components/docs-build.md).

`<apg-try-it>` and the Try it out of `<apg-operation>`, `<apg-swagger-operation>` and
`<apg-graphql-try-it>` send requests from the page with `fetch`, so the API must allow the page's
origin (CORS). These settings go on `<apg-spec>` or `<apg-api-reference>` and apply to every
element inside:

| Attribute or property | |
| --- | --- |
| `proxy-url` | CORS proxy. `{url}` is replaced by the encoded request URL (`https://proxy.example/?url={url}`); otherwise the URL is appended. `dev-server/cors-proxy.ts` in the package's repository is an allowlisting proxy. |
| `credentials` | The fetch credentials mode: `omit`, `same-origin` (default) or `include`. |
| `timeout`, `max-response-bytes` | 30 s and 5 MB by default. |
| `persist-auth` | Keep credentials in `session` or `local` storage (default: memory only). |
| `oauth2-client-id`, `oauth2-redirect-url`, `.authConfig` | OAuth 2.0 client settings; `authConfig` maps scheme names to `{ clientId, clientSecret, scopes, redirectUrl, usePkce, additionalParams }`. |
| `.fetch`, `.requestInterceptor`, `.responseInterceptor` | Replace `fetch`, or change requests and responses. |
| `ApiContext.updateSettings({ proxyHint, redirectWhenPopupBlocked })` | For pages that embed the elements in an application: `proxyHint` says where that page sets its CORS proxy (the hint names `proxy-url` otherwise); `redirectWhenPopupBlocked: false` keeps the page when popups are blocked, and the flow fails with advice to allow them. |

## Bodies

JSON and text editors with the document's examples, URL-encoded and multipart forms, and file
uploads (file inputs and drag and drop) for multipart fields and binary bodies.

## Responses

Status, timing, size and headers. JSON is highlighted, images are previewed and binary bodies can
be downloaded. `text/event-stream` (server-sent events) and NDJSON, JSON Lines and JSON text
sequences are shown as they arrive, and can be cancelled.

## Authentication

API keys, HTTP Basic and Bearer; OAuth 2.0 authorization code with PKCE, client credentials, and
the deprecated implicit and password flows, with token refresh; OpenID Connect discovery. A token
can always be pasted instead.

Authorization runs in a popup, and falls back to redirecting the page when popups are blocked.
Serve `oauth2-redirect.html` (in the package's `dist/`) from the documentation's origin and
register its URL with the authorization server; the OAuth form shows the URL to register.

## CORS

When a request fails before reaching the server, the response panel explains CORS and the proxy
option, and says what the server must send for this request: the page's origin in
`Access-Control-Allow-Origin`, what makes the browser send a preflight (the method, the headers,
`Content-Type`), and whether the browser blocks it as mixed content or asks for private network
access. Browsers do not let pages set `Cookie`; through a proxy it is sent as `X-Apg-Cookie`, which
the reference proxy turns back into `Cookie`.

## Events

The page can inspect, change or cancel every request through the cancelable `apg-request` event
(`detail.request` may be replaced); `apg-response` reports the result. Code samples mask
credentials.