Typemark Documentation

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.

idpathstringrequired

Die 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.

Authorizationheaderstringrequired

Bearer gefolgt von deinem API-Schlüssel.

emailbodystringrequired

Die E-Mail-Adresse des neuen Benutzers.

nicknamebodystringdeprecated

Verwende 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.

idstringrequired

Eindeutige ID des Benutzers.

created_atstring

Zeitpunkt 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.

teamobject

Das Team, zu dem der Benutzer gehört.

Show properties
team.idstring

Eindeutige ID des Teams.

team.namestring

Der 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"
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>

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.

GET/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

PropTypStandardBeschreibung
methodstringGETDie HTTP-Methode, etwa GET oder POST.
pathstringkeinerDer Pfad des Endpunkts, etwa /users/{id}.

ParamField und ResponseField

PropTypStandardBeschreibung
path, query, body, headerstringkeinerNur ParamField. Der Name des Feldes; das verwendete Prop legt das Ortslabel fest.
namestringkeinerDer Name des Feldes. Verwende es bei ResponseField oder bei einem ParamField ohne Ort.
typestringkeinerTyp, der neben dem Namen angezeigt wird, etwa string oder object.
requiredbooleanfalseZeigt eine required-Markierung an.
deprecatedbooleanfalseZeigt eine deprecated-Markierung an.
defaultstringkeinerZeigt default: mit dem Wert.

Der Inhalt zwischen den Tags ist die Beschreibung des Feldes.

Expandable

PropTypStandardBeschreibung
titlestringkeinerErgänzt das Umschalter-Label: Show + title.
defaultOpenbooleanfalseStartet 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.