Typemark Documentation

API-väljad

Dokumenteeri päringu parameetrid ja vastuse väljad nime, tüübi ja kohustuslikkuse märgistega. Pesasta alamväljad ning näita päringu- ja vastusenäiteid.

Uuendatud 19. nov 20262 min lugemist

API-väljad loetlevad parameetrid, mida lõpp-punkt võtab, ja väljad, mida see tagastab. Igaüks näitab nime, tüüpi ja märgiseid nagu required, kirjelduse all. Kirjuta neid käsitsi mis tahes lehel. Täieliku viite saamiseks spetsifikatsioonifailist vaata OpenAPI.

idpathstringrequired

Kasutaja ID, mille soovid päringuga tuua.

expandquerystring[]default: []

Seotud objektid, mis vastusesse lisada, näiteks 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>

Parameetrid

<ParamField> dokumenteerib midagi, mida päring saadab. Nimeta väli prop'iga, mis näitab, kuhu see läheb: path, query, body või header. See asukoht kuvatakse nime kõrval.

Authorizationheaderstringrequired

Bearer, millele järgneb sinu API-võti.

emailbodystringrequired

Uue kasutaja e-posti aadress.

nicknamebodystringdeprecated

Kasuta selle asemel 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>

Vastuse väljad

<ResponseField> dokumenteerib midagi, mida vastus tagastab. Nimeta see atribuudiga name.

idstringrequired

Kasutaja unikaalne ID.

created_atstring

Millal kasutaja loodi, ISO 8601 ajatempliga.

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

Pesastatud väljad

Mähi alamväljad <Expandable> sisse ülemvälja sees. Lugejad klõpsavad Show, et neid näha, nii et pikad objektid ei hõiva kogu lehte.

teamobject

Tiim, kuhu kasutaja kuulub.

Show properties
team.idstring

Tiimi unikaalne ID.

team.namestring

Tiimi kuvatav nimi.

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

Lüliti loeb "Show" ja sellele järgneb title, nii et title="properties" annab Show properties. Ilma pealkirjata loeb see Show details.

Päringu- ja vastusenäited

<RequestExample> ja <ResponseExample> muudavad nende sees olevad koodiplokid koodirühmaks, kus on üks vahekaart iga ploki kohta. Need ilmuvad lehel sinna, kuhu need paned.

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õpp-punkti read

<API> näitab ühte lõpp-punkti: selle meetodi ja tee ühel real. Kui su saidil on sama meetodi ja teega leht, viib rida sinna: lehele, mille oled lõpp-punkti jaoks kirjutanud, või muidu sellele, mille sinu OpenAPI viide genereerib.

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

Kasuta seda juhendites, et suunata lugejad lõpp-punkti, mida samm kutsub. Kirjuta tee täpselt nii, nagu see on sinu spetsifikatsioonis, sealhulgas parameetrid looksulgudes.

Propid

API

PropTüüpVaikeväärtusKirjeldus
methodstringGETHTTP-meetod, nagu GET või POST.
pathstringpuudubLõpp-punkti tee, nagu /users/{id}.

ParamField ja ResponseField

PropTüüpVaikeväärtusKirjeldus
path, query, body, headerstringpuudubAinult ParamField. Välja nimi; kasutatav prop määrab asukohasildi.
namestringpuudubVälja nimi. Kasuta seda ResponseField-il või ParamField-il ilma asukohata.
typestringpuudubNime kõrval kuvatav tüüp, nagu string või object.
requiredbooleanfalseNäitab required märgist.
deprecatedbooleanfalseNäitab deprecated märgist.
defaultstringpuudubNäitab default: koos väärtusega.

Siltide vahel olev sisu on välja kirjeldus.

Expandable

PropTüüpVaikeväärtusKirjeldus
titlestringpuudubTäiendab lülitisilti: Show + title.
defaultOpenbooleanfalseAlgab avatuna.

<RequestExample> ja <ResponseExample> ei võta propse. Märgi iga koodiplokk nii, nagu teeksid seda koodirühmas.

Visuaalses redaktoris

Need komponendid kuvatakse visuaalses redaktoris kirjutuskaitstud lähtekoodina ning salvestuvad muutumatuna. Muuda neid lähtekoodi režiimis. <API> kuvatakse lõpp-punkti plokina, mida saab teisaldada või kustutada.