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.
idpathstringrequiredEl 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.
AuthorizationheaderstringrequiredBearer seguido de tu clave de API.
emailbodystringrequiredLa dirección de correo electrónico del nuevo usuario.
nicknamebodystringdeprecatedUsa 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.
idstringrequiredID único del usuario.
created_atstringFecha 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.
teamobjectEl equipo al que pertenece el usuario.
Show properties
team.idstringID único del equipo.
team.namestringEl 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"{ "id": "usr_123", "email": "[email protected]" }<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.
/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
| Prop | Tipo | Valor por defecto | Descripción |
|---|---|---|---|
method | string | GET | El método HTTP, como GET o POST. |
path | string | ninguno | La ruta del endpoint, como /users/{id}. |
ParamField y ResponseField
| Prop | Tipo | Valor por defecto | Descripción |
|---|---|---|---|
path, query, body, header | string | ninguno | Solo en ParamField. El nombre del campo; el prop que uses define la etiqueta de ubicación. |
name | string | ninguno | El nombre del campo. Úsalo en ResponseField, o en un ParamField sin ubicación. |
type | string | ninguno | Tipo que se muestra junto al nombre, como string u object. |
required | boolean | false | Muestra un marcador required. |
deprecated | boolean | false | Muestra un marcador deprecated. |
default | string | ninguno | Muestra default: con el valor. |
El contenido entre las etiquetas es la descripción del campo.
Expandable
| Prop | Tipo | Valor por defecto | Descripción |
|---|---|---|---|
title | string | ninguno | Completa la etiqueta del botón: Show + title. |
defaultOpen | boolean | false | Empieza 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.