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.
idpathstringrequiredKasutaja 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.
AuthorizationheaderstringrequiredBearer, millele järgneb sinu API-võti.
emailbodystringrequiredUue kasutaja e-posti aadress.
nicknamebodystringdeprecatedKasuta 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.
idstringrequiredKasutaja unikaalne ID.
created_atstringMillal 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.
teamobjectTiim, kuhu kasutaja kuulub.
Show properties
team.idstringTiimi unikaalne ID.
team.namestringTiimi 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"{ "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õ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.
/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
| Prop | Tüüp | Vaikeväärtus | Kirjeldus |
|---|---|---|---|
method | string | GET | HTTP-meetod, nagu GET või POST. |
path | string | puudub | Lõpp-punkti tee, nagu /users/{id}. |
ParamField ja ResponseField
| Prop | Tüüp | Vaikeväärtus | Kirjeldus |
|---|---|---|---|
path, query, body, header | string | puudub | Ainult ParamField. Välja nimi; kasutatav prop määrab asukohasildi. |
name | string | puudub | Välja nimi. Kasuta seda ResponseField-il või ParamField-il ilma asukohata. |
type | string | puudub | Nime kõrval kuvatav tüüp, nagu string või object. |
required | boolean | false | Näitab required märgist. |
deprecated | boolean | false | Näitab deprecated märgist. |
default | string | puudub | Näitab default: koos väärtusega. |
Siltide vahel olev sisu on välja kirjeldus.
Expandable
| Prop | Tüüp | Vaikeväärtus | Kirjeldus |
|---|---|---|---|
title | string | puudub | Täiendab lülitisilti: Show + title. |
defaultOpen | boolean | false | Algab 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.