ApiEndpointSection() — supabase Function Reference

Source Code

apps/docs/features/docs/Reference.sections.tsx lines 283–441

async function ApiEndpointSection({ link, section, servicePath }: ApiEndpointSectionProps) {
  const endpointDetails = servicePath
    ? await getSelfHostedApiEndpointById(servicePath, section.id)
    : await getApiEndpointById(section.id)
  if (!endpointDetails) return null

  const endpointFgaPermissionGroups =
    endpointDetails.security
      ?.filter((sec) => 'fga_permissions' in sec)
      .map((sec) => sec.fga_permissions) ?? []
  const pathParameters = (endpointDetails.parameters ?? []).filter((param) => param.in === 'path')
  const queryParameters = (endpointDetails.parameters ?? []).filter((param) => param.in === 'query')
  const bodyParameters =
    endpointDetails.requestBody ??
    (endpointDetails.parameters ?? [])
      .filter((param) => param.in === 'body')
      .map(
        (bodyParam) =>
          ({
            content: {
              'application/json': {
                schema: bodyParam.schema,
              },
            },
          }) satisfies IApiEndPoint['requestBody']
      )[0]

  const first2xxCode = Object.keys(endpointDetails.responses ?? {})
    .filter((code) => code.startsWith('2'))
    .sort()[0]

  return (
    <RefSubLayout.Section columns="double" link={link} {...section}>
      <StickyHeader
        title={
          <>
            {endpointDetails.summary}
            {endpointDetails.deprecated && (
              <Badge variant="warning" className="ml-2">
                deprecated
              </Badge>
            )}
          </>
        }
        className="col-[1_/_-1]"
      />
      <div className="flex flex-col gap-12">
        <div className="flex items-center gap-2">
          <span
            className={cn(
              'uppercase text-sm whitespace-nowrap bg-foreground text-background rounded-full font-mono font-medium px-2 py-0.5',
              endpointDetails.deprecated && 'line-through'
            )}
          >
            {endpointDetails.method}
          </span>
          <code
            className={cn(
              'text-foreground-lighter break-all',
              endpointDetails.deprecated && 'line-through'
            )}
          >
            {endpointDetails.path}
          </code>
        </div>
        {endpointDetails.description && (
          <ReactMarkdown className="prose break-words mb-8">
            {endpointDetails.description}
          </ReactMarkdown>
        )}
        {endpointDetails['x-oauth-scope'] && (
          <section>
            <h3 className="mb-3 text-base text-foreground">OAuth scopes</h3>
            <ul>
              <li key={endpointDetails['x-oauth-scope']} className="list-['-'] ml-2 pl-2">
                <span className="font-mono text-sm font-medium text-foreground">
                  {endpointDetails['x-oauth-scope']}
                </span>
              </li>
            </ul>
          </section>
        )}
        {endpointFgaPermissionGroups.length > 0 && (
          <section>
            <h3 className="mb-3 text-base text-foreground">
              The fine-grained token must include the following permissions to access this endpoint:
            </h3>
            <ul>
              {endpointFgaPermissionGroups.map((group, groupIndex) => (
                <Fragment key={groupIndex}>
                  {groupIndex > 0 && (
                    <li className="my-2 text-foreground-lighter text-sm italic">or</li>
                  )}
                  {group.map((perm, permIndex) => (
                    <li key={permIndex} className="list-['-'] ml-2 pl-2">
                      <span className="font-mono text-sm font-medium text-foreground">{perm}</span>
                    </li>
                  ))}
                </Fragment>
              ))}
            </ul>
          </section>
        )}
        {pathParameters.length > 0 && (
          <section>
            <h3 className="mb-3 text-base text-foreground">Path parameters</h3>
            <ul>
              {pathParameters.map((param, index) => (
                <ApiSchemaParamDetails key={index} param={param} />
              ))}
            </ul>
          </section>
        )}
        {queryParameters.length > 0 && (
          <section>
            <h3 className="mb-3 text-base text-foreground">Query parameters</h3>
            <ul>
              {queryParameters.map((param, index) => (
                <ApiSchemaParamDetails key={index} param={param} />
              ))}
            </ul>
          </section>
        )}
        {bodyParameters && (
          <section>
            <ApiOperationBodySchemeSelector requestBody={bodyParameters} className="mb-3" />
            <ApiOperationRequestBodyDetails requestBody={bodyParameters} />
          </section>
        )}
        {endpointDetails.responses && (
          <section>
            <h3 className="mb-3 text-base text-foreground">Response codes</h3>
            <ul>
              {Object.keys(endpointDetails.responses).map((code) => (
                <li key={code} className="list-['-'] ml-2 pl-2">
                  <span className="font-mono text-sm font-medium text-foreground">{code}</span>
                </li>
              ))}
            </ul>
          </section>
        )}
      </div>
      {endpointDetails.responses && first2xxCode && (
        <div className="overflow-auto">
          <h3 className="mb-3 text-base text-foreground">{`Response (${first2xxCode})`}</h3>
          <ApiSchema
            id={`${section.id}-2xx-response`}
            schema={
              endpointDetails.responses[first2xxCode].content?.['application/json']?.schema ??
              // @ts-ignore - schema is here in older versions
              endpointDetails.responses[first2xxCode].schema ??
              {}
            }
          />
        </div>
      )}
    </RefSubLayout.Section>
  )
}