Alpha: Ships on npm at 7.0.0-alpha.07.0.0-alpha.0
api-call
One API call beside its answer, a JSON response or an event stream.
Carried by the api-product Template. Seen on pages/harbor/home.json, section 4.
{
"kind": "section",
"shell": {
"inset": "contained",
"density": "section",
"surface": "plate"
},
"block": {
"type": "api-call",
"method": "GET",
"path": "/v1/berths/{berth}/tides",
"note": "One berth, 14 days",
"examples": [
{
"label": "Pier 4, today",
"request": "curl https://api.harbor-tides.example/v1/berths/pier-4/tides?days=1",
"status": "200 OK",
"response": "{\n \"berth\": \"pier-4\",\n \"datum\": \"chart datum\",\n \"tides\": [\n { \"at\": \"04:12\", \"type\": \"low\", \"m\": 0.6 },\n { \"at\": \"10:31\", \"type\": \"high\", \"m\": 4.1 },\n { \"at\": \"16:40\", \"type\": \"low\", \"m\": 0.8 },\n { \"at\": \"22:58\", \"type\": \"high\", \"m\": 3.9 }\n ]\n}"
}
]
}
}
{
"title": "api-call",
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "api-call"
},
"method": {
"type": "string",
"enum": [
"GET",
"POST",
"PUT",
"PATCH",
"DELETE"
]
},
"path": {
"type": "string",
"minLength": 1,
"maxLength": 72
},
"note": {
"type": "string",
"minLength": 1,
"maxLength": 32
},
"group": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]{0,23}$"
},
"examples": {
"minItems": 1,
"maxItems": 4,
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string",
"minLength": 1,
"maxLength": 28
},
"request": {
"type": "string",
"minLength": 1,
"maxLength": 1008
},
"status": {
"type": "string",
"minLength": 1,
"maxLength": 28
},
"response": {
"type": "string",
"minLength": 1,
"maxLength": 1728
},
"events": {
"minItems": 1,
"maxItems": 10,
"type": "array",
"items": {
"type": "object",
"properties": {
"at": {
"type": "string",
"minLength": 1,
"maxLength": 12
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 40
},
"ref": {
"type": "string",
"minLength": 1,
"maxLength": 16
},
"text": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"open": {
"type": "boolean"
}
},
"required": [
"at",
"name",
"text"
],
"additionalProperties": false
}
}
},
"required": [
"label",
"request",
"status"
],
"additionalProperties": false
}
}
},
"required": [
"type",
"method",
"path",
"examples"
],
"additionalProperties": false
}{
"kind": "section",
"shell": { "inset": "contained", "density": "section", "surface": "plate" },
"block": {
"type": "api-call",
"method": "GET",
"path": "/v1/berths/{berth}/tides",
"note": "One berth, 14 days",
"examples": [
{
"label": "Pier 4, today",
"request": "curl https://api.harbor-tides.example/v1/berths/pier-4/tides?days=1",
"status": "200 OK",
"response": "{\n \"berth\": \"pier-4\",\n \"datum\": \"chart datum\",\n \"tides\": [\n { \"at\": \"04:12\", \"type\": \"low\", \"m\": 0.6 },\n { \"at\": \"10:31\", \"type\": \"high\", \"m\": 4.1 },\n { \"at\": \"16:40\", \"type\": \"low\", \"m\": 0.8 },\n { \"at\": \"22:58\", \"type\": \"high\", \"m\": 3.9 }\n ]\n}"
}
]
}
}Smallest that parses
{
"type": "api-call",
"method": "GET",
"path": "/v1/berths/{berth}/tides",
"examples": [
{
"label": "Pier 4, today",
"request": "curl https://api.harbor-tides.example/v1/berths/pier-4/tides?days=1",
"status": "200 OK",
"response": "{\n \"berth\": \"pier-4\",\n \"datum\": \"chart datum\",\n \"tides\": [\n { \"at\": \"04:12\", \"type\": \"low\", \"m\": 0.6 },\n { \"at\": \"10:31\", \"type\": \"high\", \"m\": 4.1 },\n { \"at\": \"16:40\", \"type\": \"low\", \"m\": 0.8 },\n { \"at\": \"22:58\", \"type\": \"high\", \"m\": 3.9 }\n ]\n}"
}
]
}Props
From @mdxui/site@7.0.0-alpha.0. A count reads as min–max × item; a string bound is its maximum length in characters, and links its refusal.
| Prop | Type and bound | Required |
|---|---|---|
method | "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | yes |
path | string ≤72 | yes |
note | string ≤32 | no |
group | string (pattern) | no |
examples | 1–4 × object | yes |
examples[].label | string ≤28 | yes |
examples[].request | string ≤1008 | yes |
examples[].status | string ≤28 | yes |
examples[].response | string ≤1728 | no |
examples[].events | 1–10 × object | no |
examples[].events[].at | string ≤12 | yes |
examples[].events[].name | string ≤40 | yes |
examples[].events[].ref | string ≤16 | no |
examples[].events[].text | string ≤80 | yes |
examples[].events[].open | boolean | no |