Typemark Documentation

Campos de la API

Documenta los parámetros de la solicitud y los campos de la respuesta con marcadores de nombre, tipo y obligatoriedad. Anida campos secundarios y muestra ejemplos de solicitud y respuesta.

Actualizado el 19 nov 20263 min de lectura

Los campos de la API enumeran los parámetros que recibe un endpoint y los campos que devuelve. Cada uno muestra el nombre, su tipo y marcadores como required, con una descripción debajo. Escríbelos a mano en cualquier página. Para una referencia completa generada a partir de un archivo de especificación, consulta OpenAPI.

idpathstringrequired

El ID del usuario que se va a obtener.

expandquerystring[]default: []

Objetos relacionados que se incluyen en la respuesta, como team.

<ParamField path="id" type="string" required>
  The ID of the user to fetch.
</ParamField>

<ParamField query="expand" type="string[]" default="[]">
  Related objects to include in the response, such as `team`.
</ParamField>

Parámetros

<ParamField> documenta algo que envía la solicitud. Indica el nombre del campo con el prop que corresponde a su ubicación: path, query, body o header. Esa ubicación se muestra junto al nombre.

Authorizationheaderstringrequired

Bearer seguido de tu clave de API.

emailbodystringrequired

La dirección de correo electrónico del nuevo usuario.

nicknamebodystringdeprecated

Usa display_name en su lugar.

<ParamField header="Authorization" type="string" required>
  `Bearer` followed by your API key.
</ParamField>

<ParamField body="email" type="string" required>
  The new user's email address.
</ParamField>

<ParamField body="nickname" type="string" deprecated>
  Use `display_name` instead.
</ParamField>

Campos de respuesta

<ResponseField> documenta algo que devuelve la respuesta. Asígnale nombre con name.

idstringrequired

ID único del usuario.

created_atstring

Fecha de creación del usuario, en formato de marca de tiempo ISO 8601.

<ResponseField name="id" type="string" required>
  Unique ID for the user.
</ResponseField>

<ResponseField name="created_at" type="string">
  When the user was created, as an ISO 8601 timestamp.
</ResponseField>

Campos anidados

Envuelve los campos secundarios en <Expandable> dentro del campo padre. Los lectores hacen clic en Show para verlos, de modo que los objetos largos no ocupan toda la página.

teamobject

El equipo al que pertenece el usuario.

Show properties
team.idstring

ID único del equipo.

team.namestring

El nombre visible del equipo.

<ResponseField name="team" type="object">
  The team the user belongs to.

  <Expandable title="properties">
    <ResponseField name="team.id" type="string">
      Unique ID for the team.
    </ResponseField>
    <ResponseField name="team.name" type="string">
      The team's display name.
    </ResponseField>
  </Expandable>
</ResponseField>

El botón muestra "Show" seguido del title, así que title="properties" produce Show properties. Sin título, muestra Show details.

Ejemplos de solicitud y respuesta

<RequestExample> y <ResponseExample> convierten los bloques de código que contienen en un grupo de código, con una pestaña por bloque. Aparecen donde los coloques en la página.

curl https://api.acme.com/v1/users/usr_123 \
  -H "Authorization: Bearer sk_live_abc123"
const user = await acme.users.retrieve("usr_123");
{ "id": "usr_123", "email": "[email protected]" }
{ "error": "not_found" }
<RequestExample>
  ```bash cURL
  curl https://api.acme.com/v1/users/usr_123 \
    -H "Authorization: Bearer sk_live_abc123"
  ```
  ```javascript Node.js
  const user = await acme.users.retrieve("usr_123");
  ```
</RequestExample>

<ResponseExample>
  ```json 200
  { "id": "usr_123", "email": "[email protected]" }
  ```
  ```json 404
  { "error": "not_found" }
  ```
</ResponseExample>

Líneas de endpoint

<API> muestra un endpoint: su método y su ruta en una sola línea. Cuando tu sitio tiene una página para el mismo método y ruta, la línea enlaza a ella: una página que escribiste para el endpoint, o bien la que genera tu referencia de OpenAPI.

GET/users/{id}
<API method="GET" path="/users/{id}" />

Úsalo en las guías para indicar a los lectores el endpoint que llama un paso. Escribe la ruta exactamente como aparece en tu especificación, incluidos los parámetros entre llaves.

Props

API

PropTipoValor por defectoDescripción
methodstringGETEl método HTTP, como GET o POST.
pathstringningunoLa ruta del endpoint, como /users/{id}.

ParamField y ResponseField

PropTipoValor por defectoDescripción
path, query, body, headerstringningunoSolo en ParamField. El nombre del campo; el prop que uses define la etiqueta de ubicación.
namestringningunoEl nombre del campo. Úsalo en ResponseField, o en un ParamField sin ubicación.
typestringningunoTipo que se muestra junto al nombre, como string u object.
requiredbooleanfalseMuestra un marcador required.
deprecatedbooleanfalseMuestra un marcador deprecated.
defaultstringningunoMuestra default: con el valor.

El contenido entre las etiquetas es la descripción del campo.

Expandable

PropTipoValor por defectoDescripción
titlestringningunoCompleta la etiqueta del botón: Show + title.
defaultOpenbooleanfalseEmpieza expandido.

<RequestExample> y <ResponseExample> no reciben props. Etiqueta cada bloque de código como lo harías en un grupo de código.

En el editor visual

Estos componentes se muestran como código fuente de solo lectura en el editor visual y se guardan sin cambios. Edítalos en el modo de código fuente. <API> se muestra como un bloque de endpoint que puedes mover o eliminar.