API-Felder
Anfrageparameter und Antwortfelder mit Name, Typ und Pflicht-Markierungen dokumentieren. Untergeordnete Felder verschachteln und Anfrage- und Antwortbeispiele anzeigen.
Aktualisiert am 19. Nov. 20262 Min. Lesezeit
API-Felder listen die Parameter auf, die ein Endpunkt entgegennimmt, und die Felder, die er zurückgibt. Jedes zeigt den Namen, seinen Typ und Markierungen wie required, darunter eine Beschreibung. Du schreibst sie von Hand auf jeder Seite. Für eine vollständige Referenz, die aus einer Spezifikationsdatei erzeugt wird, siehe OpenAPI.
idpathstringrequiredDie ID des Benutzers, der abgerufen werden soll.
expandquerystring[]default: []Zugehörige Objekte, die in die Antwort aufgenommen werden, etwa 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>
Parameter
<ParamField> dokumentiert etwas, das die Anfrage sendet. Benenne das Feld mit dem Prop für den Ort, an dem es platziert wird: path, query, body oder header. Dieser Ort wird neben dem Namen angezeigt.
AuthorizationheaderstringrequiredBearer gefolgt von deinem API-Schlüssel.
emailbodystringrequiredDie E-Mail-Adresse des neuen Benutzers.
nicknamebodystringdeprecatedVerwende stattdessen display_name.
<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>
Antwortfelder
<ResponseField> dokumentiert etwas, das die Antwort zurückgibt. Benenne es mit name.
idstringrequiredEindeutige ID des Benutzers.
created_atstringZeitpunkt der Erstellung des Benutzers als ISO-8601-Zeitstempel.
<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>
Verschachtelte Felder
Umschließe untergeordnete Felder mit <Expandable> innerhalb des übergeordneten Feldes. Leser klicken auf Show, um sie zu sehen, damit lange Objekte die Seite nicht dominieren.
teamobjectDas Team, zu dem der Benutzer gehört.
Show properties
team.idstringEindeutige ID des Teams.
team.namestringDer Anzeigename des Teams.
<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>
Der Umschalter liest „Show“ gefolgt vom title, also ergibt title="properties" Show properties. Ohne Titel lautet er Show details.
Anfrage- und Antwortbeispiele
<RequestExample> und <ResponseExample> wandeln die Codeblöcke darin in eine Code-Gruppe um, mit einem Tab pro Block. Sie erscheinen an der Stelle, an die du sie setzt, auf der Seite.
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>
Endpunkt-Zeilen
<API> zeigt einen Endpunkt: seine Methode und seinen Pfad in einer Zeile. Wenn deine Website eine Seite für dieselbe Methode und denselben Pfad hat, verlinkt die Zeile darauf: eine Seite, die du für den Endpunkt geschrieben hast, oder sonst die, die deine OpenAPI-Referenz erzeugt.
/users/{id}
<API method="GET" path="/users/{id}" />
Verwende sie in Anleitungen, um Leser auf den Endpunkt zu verweisen, den ein Schritt aufruft. Schreibe den Pfad genau so, wie er in deiner Spezifikation steht, einschließlich der Parameter in geschweiften Klammern.
Props
API
| Prop | Typ | Standard | Beschreibung |
|---|---|---|---|
method | string | GET | Die HTTP-Methode, etwa GET oder POST. |
path | string | keiner | Der Pfad des Endpunkts, etwa /users/{id}. |
ParamField und ResponseField
| Prop | Typ | Standard | Beschreibung |
|---|---|---|---|
path, query, body, header | string | keiner | Nur ParamField. Der Name des Feldes; das verwendete Prop legt das Ortslabel fest. |
name | string | keiner | Der Name des Feldes. Verwende es bei ResponseField oder bei einem ParamField ohne Ort. |
type | string | keiner | Typ, der neben dem Namen angezeigt wird, etwa string oder object. |
required | boolean | false | Zeigt eine required-Markierung an. |
deprecated | boolean | false | Zeigt eine deprecated-Markierung an. |
default | string | keiner | Zeigt default: mit dem Wert. |
Der Inhalt zwischen den Tags ist die Beschreibung des Feldes.
Expandable
| Prop | Typ | Standard | Beschreibung |
|---|---|---|---|
title | string | keiner | Ergänzt das Umschalter-Label: Show + title. |
defaultOpen | boolean | false | Startet ausgeklappt. |
<RequestExample> und <ResponseExample> nehmen keine Props entgegen. Beschrifte jeden Codeblock so, wie du es in einer Code-Gruppe tun würdest.
Im visuellen Editor
Diese Komponenten werden im visuellen Editor als schreibgeschützter Quelltext angezeigt und unverändert zurückgespeichert. Bearbeite sie im Quelltextmodus. <API> wird als Endpunkt-Block angezeigt, den du verschieben oder löschen kannst.