|
| 1 | +# 30-minute CoreLink v1 quickstart |
| 2 | + |
| 3 | +**Maturity: Alpha documentation / `1.0.0-draft` public contract** |
| 4 | + |
| 5 | +This quickstart exercises the currently reviewed public Device and Command slice |
| 6 | +without depending on a prerelease SDK. It uses the versioned OpenAPI contract as |
| 7 | +the source of truth: |
| 8 | + |
| 9 | +- [CoreLink public v1 OpenAPI](https://github.com/CoreLinkPlatform/api-contracts/blob/main/openapi/corelink-public-v1.yaml) |
| 10 | +- public authentication: bearer JWT; |
| 11 | +- public tenant scope: `tenant_id` in the resource path; |
| 12 | +- public device identity: `corelink_device_id`. |
| 13 | + |
| 14 | +The contract is still draft. The examples below demonstrate the accepted |
| 15 | +contract shape; they do not claim that a public production endpoint, self-service |
| 16 | +token issuer, or Stable SDK release exists. |
| 17 | + |
| 18 | +## Target outcome |
| 19 | + |
| 20 | +Within 30 minutes you should be able to: |
| 21 | + |
| 22 | +1. configure an assigned API base URL, bearer token and tenant; |
| 23 | +2. verify readiness; |
| 24 | +3. list the tenant's devices; |
| 25 | +4. create a device when a valid `device_model_id` has been assigned; |
| 26 | +5. create an idempotent command for that device; |
| 27 | +6. inspect the command and recognize the standard failure responses. |
| 28 | + |
| 29 | +## 0–5 min: prerequisites |
| 30 | + |
| 31 | +You need values supplied by the CoreLink environment/operator: |
| 32 | + |
| 33 | +- `CORELINK_API_URL` — base URL for the environment you are authorized to use; |
| 34 | +- `CORELINK_ACCESS_TOKEN` — bearer JWT for that environment; |
| 35 | +- `CORELINK_TENANT_ID` — UUID of the tenant you are authorized to access; |
| 36 | +- `CORELINK_DEVICE_MODEL_ID` — UUID of an allowed device model if you will |
| 37 | + create a device. |
| 38 | + |
| 39 | +The draft public contract does **not** define a token-issuance endpoint. Do not |
| 40 | +invent or hard-code a client-secret flow in application code. Obtain credentials |
| 41 | +through the environment's approved onboarding path. |
| 42 | + |
| 43 | +Set the values in your shell without committing them: |
| 44 | + |
| 45 | +```bash |
| 46 | +export CORELINK_API_URL="https://api.example.invalid" |
| 47 | +export CORELINK_ACCESS_TOKEN="<bearer-token>" |
| 48 | +export CORELINK_TENANT_ID="<tenant-uuid>" |
| 49 | +export CORELINK_DEVICE_MODEL_ID="<device-model-uuid>" |
| 50 | +``` |
| 51 | + |
| 52 | +Use a real environment URL in place of `api.example.invalid`. Keep tokens out of |
| 53 | +shell history, screenshots, issue bodies and source control where practical. |
| 54 | + |
| 55 | +## 5–10 min: verify the environment |
| 56 | + |
| 57 | +The readiness endpoint is intentionally unauthenticated: |
| 58 | + |
| 59 | +```bash |
| 60 | +curl --fail-with-body --silent --show-error \ |
| 61 | + "$CORELINK_API_URL/health/ready" |
| 62 | +``` |
| 63 | + |
| 64 | +A ready environment returns HTTP `200`. HTTP `503` means a dependency required |
| 65 | +for traffic is unavailable; stop and resolve the environment before continuing. |
| 66 | + |
| 67 | +## 10–15 min: list tenant-scoped devices |
| 68 | + |
| 69 | +```bash |
| 70 | +curl --fail-with-body --silent --show-error \ |
| 71 | + -H "Authorization: Bearer $CORELINK_ACCESS_TOKEN" \ |
| 72 | + "$CORELINK_API_URL/api/v1/tenants/$CORELINK_TENANT_ID/devices?limit=20&offset=0" |
| 73 | +``` |
| 74 | + |
| 75 | +The response is a `DevicePage`. Device identifiers exposed by the public API are |
| 76 | +`corelink_device_id`; connector/provider identifiers are not public resource |
| 77 | +identities. |
| 78 | + |
| 79 | +Expected authorization failures: |
| 80 | + |
| 81 | +- `401` — authentication is missing or invalid; |
| 82 | +- `403` — the caller is authenticated but cannot access the requested tenant |
| 83 | + or operation. |
| 84 | + |
| 85 | +Never recover from `403` by changing the tenant ID to another tenant. |
| 86 | + |
| 87 | +## 15–20 min: create a device |
| 88 | + |
| 89 | +Skip this step if the environment has not assigned a valid |
| 90 | +`CORELINK_DEVICE_MODEL_ID`. |
| 91 | + |
| 92 | +```bash |
| 93 | +DEVICE_RESPONSE="$(curl --fail-with-body --silent --show-error \ |
| 94 | + -X POST \ |
| 95 | + -H "Authorization: Bearer $CORELINK_ACCESS_TOKEN" \ |
| 96 | + -H "Content-Type: application/json" \ |
| 97 | + "$CORELINK_API_URL/api/v1/tenants/$CORELINK_TENANT_ID/devices" \ |
| 98 | + --data "{\"device_model_id\":\"$CORELINK_DEVICE_MODEL_ID\",\"name\":\"quickstart-device\",\"metadata\":{\"source\":\"docs-v1-quickstart\"}}")" |
| 99 | + |
| 100 | +printf '%s\n' "$DEVICE_RESPONSE" |
| 101 | +``` |
| 102 | + |
| 103 | +A successful create returns HTTP `201` and a `Device` containing |
| 104 | +`corelink_device_id`. Record that value as `CORELINK_DEVICE_ID`: |
| 105 | + |
| 106 | +```bash |
| 107 | +export CORELINK_DEVICE_ID="<corelink-device-uuid>" |
| 108 | +``` |
| 109 | + |
| 110 | +HTTP `400` means the request is invalid; `401`/`403` are authentication or |
| 111 | +tenant/permission failures; `409` means the request conflicts with current |
| 112 | +state. |
| 113 | + |
| 114 | +## 20–25 min: submit one idempotent command |
| 115 | + |
| 116 | +The command create operation requires `Idempotency-Key`. Reuse the same key |
| 117 | +only when retrying the same logical command. |
| 118 | + |
| 119 | +```bash |
| 120 | +export CORELINK_IDEMPOTENCY_KEY="quickstart-$(date +%s)" |
| 121 | + |
| 122 | +COMMAND_RESPONSE="$(curl --fail-with-body --silent --show-error \ |
| 123 | + -X POST \ |
| 124 | + -H "Authorization: Bearer $CORELINK_ACCESS_TOKEN" \ |
| 125 | + -H "Content-Type: application/json" \ |
| 126 | + -H "Idempotency-Key: $CORELINK_IDEMPOTENCY_KEY" \ |
| 127 | + "$CORELINK_API_URL/api/v1/tenants/$CORELINK_TENANT_ID/devices/$CORELINK_DEVICE_ID/commands" \ |
| 128 | + --data '{"command_type":"quickstart.ping","payload":{},"metadata":{"source":"docs-v1-quickstart"}}')" |
| 129 | + |
| 130 | +printf '%s\n' "$COMMAND_RESPONSE" |
| 131 | +``` |
| 132 | + |
| 133 | +A successful submission returns HTTP `201` and a `Command`. Record its |
| 134 | +`command_id`: |
| 135 | + |
| 136 | +```bash |
| 137 | +export CORELINK_COMMAND_ID="<command-uuid>" |
| 138 | +``` |
| 139 | + |
| 140 | +Command status is one of `queued`, `dispatching`, `sent`, `acknowledged`, |
| 141 | +`succeeded`, `failed`, `timed_out`, or `cancelled`. A `201` response |
| 142 | +means the command was accepted; it does not mean device execution succeeded. |
| 143 | + |
| 144 | +## 25–30 min: inspect the command |
| 145 | + |
| 146 | +```bash |
| 147 | +curl --fail-with-body --silent --show-error \ |
| 148 | + -H "Authorization: Bearer $CORELINK_ACCESS_TOKEN" \ |
| 149 | + "$CORELINK_API_URL/api/v1/tenants/$CORELINK_TENANT_ID/devices/$CORELINK_DEVICE_ID/commands/$CORELINK_COMMAND_ID" |
| 150 | +``` |
| 151 | + |
| 152 | +Expected failures use the contract's `application/problem+json` shape and carry |
| 153 | +a `correlation_id` for diagnosis. Preserve that identifier when escalating an |
| 154 | +unexpected error. |
| 155 | + |
| 156 | +## Tenant-isolation check |
| 157 | + |
| 158 | +If you have two explicitly authorized test tenants, repeat a read with the token |
| 159 | +and tenant combination provided for each environment. A token must never gain |
| 160 | +access merely because a caller changes `tenant_id` in the URL. Do not probe |
| 161 | +tenants you are not authorized to test. |
| 162 | + |
| 163 | +## Safe retry rules |
| 164 | + |
| 165 | +- GET requests may be retried according to the environment's documented policy. |
| 166 | +- For command POST retries, retain the original `Idempotency-Key`. |
| 167 | +- Do not automatically retry `400`, `401`, `403`, or `404`. |
| 168 | +- Treat `409` as a state/idempotency conflict that needs reconciliation. |
| 169 | +- A readiness `503` is an environment/dependency failure, not proof that a |
| 170 | + write failed or succeeded. |
| 171 | + |
| 172 | +## Definition of a successful quickstart |
| 173 | + |
| 174 | +The quickstart is complete when the developer has retained: |
| 175 | + |
| 176 | +- the environment/contract baseline used; |
| 177 | +- the authorized tenant ID; |
| 178 | +- one successful tenant-scoped read; |
| 179 | +- one `corelink_device_id` from an existing or newly created device; |
| 180 | +- one command ID plus its observed terminal or current state; |
| 181 | +- any failure `correlation_id` needed for follow-up. |
| 182 | + |
| 183 | +For SDK usage, sandbox packaging and broader resource guides, follow their |
| 184 | +repository maturity. TypeScript/Python are prerelease Alpha; Java, CLI, MCP and |
| 185 | +mock-server remain Scaffold/Planned until their release gates pass. |
0 commit comments