Skip to main content

REST API

ഓരോ imatic ഉൽപ്പന്നവും ഒരു വേർഷൻ ചെയ്ത REST API നൽകുന്നു, അതിനാൽ നിങ്ങളുടെ സ്വന്തം കോഡിൽ നിന്ന് അത് ഓട്ടോമേറ്റ് ചെയ്യാം. ഈ പേജിലെ കൺവെൻഷനുകൾ — നിങ്ങൾ എങ്ങനെ ഓതന്റിക്കേറ്റ് ചെയ്യുന്നു, API കീകൾ എങ്ങനെ പ്രവർത്തിക്കുന്നു, webhooks എങ്ങനെ സൈൻ ചെയ്യപ്പെടുന്നു, പേജിനേഷൻ, റേറ്റ് ലിമിറ്റുകൾ, എററുകൾ എങ്ങനെ പെരുമാറുന്നു — ഉൽപ്പന്നങ്ങളിലുടനീളം ഒരുപോലെയാണ്. വ്യത്യാസപ്പെടുന്നത് ഓരോ ഉൽപ്പന്നവും വെളിപ്പെടുത്തുന്ന റിസോഴ്സുകൾ ആണ്, അവ അതിന്റെ ഡെവലപ്പർ പേജിൽ രേഖപ്പെടുത്തിയിരിക്കുന്നു.

ഉദാഹരണങ്ങൾ വിശദീകരണാത്മകം മാത്രമാണ്

താഴെയുള്ള റിക്വസ്റ്റ്, റെസ്പോൺസ് സ്നിപ്പെറ്റുകൾ കോളുകളുടെ രൂപം കാണിക്കുന്നു — ഹെഡറുകൾ, ഓത്ത്, എറർ എൻവലപ്പുകൾ — കൃത്യമായ ഫീൽഡ്-ബൈ-ഫീൽഡ് സ്കീമയല്ല. ഒരു ഉൽപ്പന്നത്തിന്റെ കൃത്യമായ എൻഡ്പോയിന്റുകൾ, പാരാമീറ്ററുകൾ, ഫീൽഡ് നാമങ്ങൾ എന്നിവയ്ക്ക്, ആ ഉൽപ്പന്നത്തിന്റെ ഡെവലപ്പർ പേജിലേക്കുള്ള ലിങ്കുകൾ പിന്തുടരുക.

ഓതന്റിക്കേഷൻ​

imatic രണ്ട് വ്യത്യസ്ത കോളർമാർക്കായി രണ്ട് തരം ക്രെഡൻഷ്യലുകൾ ഉപയോഗിക്കുന്നു:

  • JWT (സെഷൻ ടോക്കൺ) — നിങ്ങൾ ഇമെയിലും പാസ്‌വേഡും ഉപയോഗിച്ച് സൈൻ ഇൻ ചെയ്തതിന് ശേഷം വെബ് ആപ്പ് ഉപയോഗിക്കുന്നത്. ഇത് ബ്രൗസറിൽ നിങ്ങളെ പ്രതിനിധീകരിക്കുന്നു, ഹ്രസ്വകാലമാണ്. നിങ്ങൾ ഇത് നേരിട്ട് കൈകാര്യം ചെയ്യുന്നില്ല; ആപ്പാണ് അത് ചെയ്യുന്നത്.
  • സ്കോപ്പ്ഡ് API കീ — നിങ്ങളുടെ കോഡ് v1 REST API കോൾ ചെയ്യാൻ ഉപയോഗിക്കുന്നത്. നിങ്ങൾ തന്നെ അത് സൃഷ്ടിക്കുന്നു, അത് വ്യക്തമായ സ്കോപ്പുകൾ വഹിക്കുന്നു, ഒരു ബ്രൗസർ സെഷനോടൊപ്പം അത് കാലഹരണപ്പെടുന്നില്ല.

സെർവർ-ടു-സെർവർ കോളുകൾക്ക്, എപ്പോഴും ഒരു API കീ ഉപയോഗിക്കുക — ഒരിക്കലും നിങ്ങളുടെ പാസ്‌വേഡോ പകർത്തിയ സെഷൻ ടോക്കണോ അല്ല.

ഒരു API കീ അയയ്ക്കുന്നു​

Authorization ഹെഡറിൽ കീ ഒരു Bearer ടോക്കണായി കൈമാറുക:

curl https://<product-host>/v1/event-types \
  -H "Authorization: Bearer cal_abc123.s3cr3t_keymaterial" \
  -H "Content-Type: application/json"

API കീകൾ എങ്ങനെ പ്രവർത്തിക്കുന്നു​

ഓരോ ഉൽപ്പന്നത്തിന്റെയും ഡെവലപ്പർ ഏരിയയിൽ നിങ്ങൾ API കീകൾ സൃഷ്ടിക്കുകയും കൈകാര്യം ചെയ്യുകയും ചെയ്യുന്നു — ഉദാഹരണത്തിന് Calendar-ന്റെ Developers → API keys, Survey-യുടെ Developers → API keys. ഒരു കീക്ക് മനസ്സിലാക്കാൻ വിലയുള്ള മൂന്ന് സവിശേഷതകളുണ്ട്:

  • prefix.secret ഫോർമാറ്റ് — ഒരു കീക്ക് ഒരു പൊതുവായ prefix-ഉം ഒരു സീക്രട്ട് ഭാഗവുമുണ്ട്, ഒരു ഡോട്ട് കൊണ്ട് ചേർത്തിരിക്കുന്നു (ഉദാഹരണത്തിന് cal_abc123.s3cr3t_keymaterial — Calendar കീകൾ ഒരു ചെറിയ cal_ prefix ഉപയോഗിക്കുന്നു). ലിസ്റ്റുകളിലും ലോഗുകളിലും കീ തിരിച്ചറിയാൻ prefix imatic-നെ അനുവദിക്കുന്നു; സീക്രട്ട് അത് നിങ്ങളുടേതാണെന്ന് തെളിയിക്കുന്നു.
  • ഒരിക്കൽ മാത്രം കാണിക്കുന്നു — കീയുടെ പൂർണ്ണ മൂല്യം നിങ്ങൾ അത് സൃഷ്ടിക്കുന്ന നിമിഷത്തിൽ മാത്രമേ പ്രദർശിപ്പിക്കൂ. അതിന് ശേഷം, prefix മാത്രമേ ദൃശ്യമാകൂ.
  • സ്കോപ്പുകൾ — ഓരോ കീയും നിങ്ങൾ അനുവദിക്കുന്ന പ്രവർത്തനങ്ങളിലേക്ക് പരിമിതപ്പെടുത്തിയിരിക്കുന്നു. Calendar-ന്റെ സ്കോപ്പുകൾ slots:read, bookings:read, bookings:write, mcp എന്നിവയാണ് (mcp സ്കോപ്പ് ആണ് ഒരു AI ഏജന്റിന്റെ കീക്ക് ആവശ്യമുള്ളത് — AI ഏജന്റുകൾക്കായുള്ള MCP കാണുക). ഒരു കീയുടെ സ്കോപ്പ് കവിയുന്ന ഒരു റിക്വസ്റ്റ് നിരസിക്കപ്പെടുന്നു.
API കീകളെ പാസ്‌വേഡുകൾ പോലെ കണക്കാക്കുക

ഒരു കീയുടെ സീക്രട്ട് സൃഷ്ടിക്കുമ്പോൾ ഒരിക്കൽ മാത്രമേ കാണിക്കൂ. അപ്പോൾ അത് പകർത്തി ഒരു സീക്രട്ട് മാനേജറിലോ എൻവയോൺമെന്റ് വേരിയബിളിലോ സൂക്ഷിക്കുക — ഒരിക്കലും സോഴ്സ് കൺട്രോളിലോ, ഒരു സ്ക്രീൻഷോട്ടിലോ, പങ്കിട്ട ഡോക്കിലോ അല്ല. ഒരു കീ വെളിപ്പെട്ടാൽ, ഡെവലപ്പർ ഏരിയയിൽ അത് revoke ചെയ്യുക എന്നിട്ട് ഒരു പകരം സൃഷ്ടിക്കുക. Revocation ഉടനടി പ്രാബല്യത്തിൽ വരുന്നു.

Webhooks​

മാറ്റങ്ങൾക്കായി പോൾ ചെയ്യുന്നതിന് പകരം, ഒരു webhook URL രജിസ്റ്റർ ചെയ്യുക, എന്തെങ്കിലും സംഭവിക്കുമ്പോൾ imatic അതിലേക്ക് ഒരു ഇവന്റ് POST ചെയ്യും — ഉദാഹരണത്തിന് Calendar-ൽ ഒരു ബുക്കിംഗ് സൃഷ്ടിക്കപ്പെടുമ്പോൾ അല്ലെങ്കിൽ Survey-യിൽ ഒരു റെസ്പോൺസ് സമർപ്പിക്കുമ്പോൾ. ഓരോ ഉൽപ്പന്നത്തിന്റെയും Developers → Webhooks ഏരിയയിൽ നിങ്ങൾ webhook എൻഡ്പോയിന്റുകൾ കൈകാര്യം ചെയ്യുന്നു, അവിടെ നിങ്ങൾക്ക് ഒരു ടെസ്റ്റ് ഡെലിവറിയും അയയ്ക്കാം.

ഒരു ഡെലിവറി ഏകദേശം ഇതുപോലെ കാണപ്പെടുന്നു:

POST /your/webhook/endpoint HTTP/1.1
Content-Type: application/json
X-Imatic-Signature: t=1718900000,v1=9f86d081884c7d659a2feaa0c55ad015...

{
  "event": "booking.created",
  "data": { "...": "event-specific payload" }
}

സിഗ്നേച്ചർ പരിശോധിക്കുന്നു​

ഓരോ ഡെലിവറിയും നിങ്ങളുടെ എൻഡ്പോയിന്റിന്റെ സൈനിംഗ് സീക്രട്ട് ഉപയോഗിച്ച് HMAC-SHA256 കൊണ്ട് സൈൻ ചെയ്യപ്പെടുന്നു, ഒരു Stripe-ശൈലിയിലുള്ള X-Imatic-Signature ഹെഡറിൽ. ഹെഡർ രണ്ട് ഫീൽഡുകൾ വഹിക്കുന്നു: t, അയയ്ക്കുന്ന സമയത്തെ unix-epoch സെക്കൻഡുകൾ, പിന്നെ v1, ${t}.${body} എന്ന സ്ട്രിങ്ങിന്റെ ഹെക്സ് HMAC (ടൈംസ്റ്റാമ്പ്, ഒരു ലിറ്ററൽ ഡോട്ട്, പിന്നെ കൃത്യമായ റോ റിക്വസ്റ്റ് ബോഡി). പരിശോധിക്കാൻ, ഹെഡർ വിഭജിക്കുക, നിങ്ങളുടെ സൈനിംഗ് സീക്രട്ട് ഉപയോഗിച്ച് t + "." + rawBody-ന് മേൽ v1 വീണ്ടും കണക്കാക്കുക, constant-time-ൽ താരതമ്യം ചെയ്യുക. പൊരുത്തപ്പെടുന്നില്ലെങ്കിൽ നിരസിക്കുക — replay-നെതിരെ കാക്കാൻ t കുറച്ച് മിനിറ്റുകളിൽ പഴയതാണെങ്കിൽ ഓപ്ഷണലായി നിരസിക്കുകയും ചെയ്യാം.

import crypto from "node:crypto";

function isValid(rawBody, signatureHeader, signingSecret) {
  // Header shape: "t=<epoch-seconds>,v1=<hex hmac>"
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((kv) => kv.split("=")),
  );
  const { t, v1 } = parts;
  if (!t || !v1) return false;

  // Sign the timestamped body: `${t}.${rawBody}` — NOT the raw body alone.
  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(`${t}.${rawBody}`)
    .digest("hex");

  // Constant-time comparison to avoid timing attacks.
  const a = Buffer.from(v1);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}
ഉൽപ്പന്നം അനുസരിച്ച് കൃത്യമായ സ്കീം

മുകളിലുള്ള t=…,v1=… സ്കീം Calendar-ന്റേതാണ്. ഒരു verifier ഷിപ്പ് ചെയ്യുന്നതിന് മുമ്പ് ഓരോ ഉൽപ്പന്നത്തിന്റെയും ഡെവലപ്പർ പേജിൽ ഹെഡർ നാമം, ഫീൽഡുകൾ, സൈൻ ചെയ്ത സ്ട്രിങ് എന്നിവ സ്ഥിരീകരിക്കുക.

വേഗത്തിൽ പ്രതികരിക്കുക, പിന്നീട് പ്രോസസ് ചെയ്യുക

രസീത് സ്ഥിരീകരിക്കാൻ വേഗത്തിൽ ഒരു 2xx തിരികെ നൽകുക, എന്നിട്ട് ഏതെങ്കിലും മന്ദഗതിയിലുള്ള ജോലി അസിൻക്രണസായി ചെയ്യുക. നിങ്ങളുടെ എൻഡ്പോയിന്റ് മന്ദഗതിയിലാണെങ്കിലോ എറർ ചെയ്താലോ, ഡെലിവറികൾ വീണ്ടും ശ്രമിച്ചേക്കാം.

പേജിനേഷൻ​

ലിസ്റ്റ് എൻഡ്പോയിന്റുകൾ ഫലങ്ങൾ പേജുകളായി തിരികെ നൽകുന്നു, അതിനാൽ ഒരൊറ്റ കോളിന് ഒരിക്കലും എല്ലാം ലോഡ് ചെയ്യേണ്ടി വരുന്നില്ല. റിക്വസ്റ്റിൽ പേജിംഗ് പാരാമീറ്ററുകൾ കൈമാറുക, അടുത്ത പേജ് ലഭിക്കാൻ റെസ്പോൺസിലെ പേജിംഗ് മെറ്റാഡാറ്റ വായിക്കുക.

curl "https://<product-host>/v1/bookings?limit=25" \
  -H "Authorization: Bearer cal_abc123.s3cr3t_keymaterial"
{
  "success": true,
  "data": [ { "...": "one item per result" } ],
  "pagination": { "page": 1, "limit": 20, "total": 0, "pages": 0 }
}

കൂടുതൽ ഫലങ്ങൾ ഇല്ലാതാകുന്നതുവരെ അടുത്ത പേജ് അഭ്യർത്ഥിക്കുന്നത് തുടരുക.

റേറ്റ് ലിമിറ്റിംഗ്​

പ്ലാറ്റ്ഫോം ന്യായവും സ്ഥിരവുമായി നിലനിർത്താൻ API കീകൾ റേറ്റ് ലിമിറ്റ് ചെയ്യപ്പെടുന്നു. നിങ്ങൾ ലിമിറ്റ് കവിഞ്ഞാൽ, API HTTP 429 Too Many Requests പ്രതികരണം നൽകുന്നു. എൻഡ്പോയിന്റ് ഇടിച്ചുകൊണ്ടിരിക്കുന്നതിന് പകരം — ആദർശപരമായി എക്സ്പോണൻഷ്യൽ ബാക്ക്ഓഫും ജിറ്ററും ഉപയോഗിച്ച് — ബാക്ക് ഓഫ് ചെയ്ത് വീണ്ടും ശ്രമിക്കുക.

{
  "success": false,
  "error": "rate_limited",
  "message": "Too many requests. Please retry after a short delay."
}

എറർ കൈകാര്യം​

എന്താണ് തെറ്റിയതെന്ന് വിവരിക്കുന്ന ഒരു JSON ബോഡിയോടെ എററുകൾ സ്റ്റാൻഡേർഡ് HTTP സ്റ്റാറ്റസ് കോഡുകൾ ഉപയോഗിക്കുന്നു. നിങ്ങൾ ഏറ്റവും കൂടുതൽ കാണുന്ന കോഡുകൾ:

  • 400 — റിക്വസ്റ്റ് രൂപഭംഗം വന്നതോ വാലിഡേഷൻ പരാജയപ്പെട്ടതോ ആയിരുന്നു.
  • 401 — കാണാത്ത അല്ലെങ്കിൽ അസാധുവായ API കീ.
  • 403 — കീ സാധുവാണ് പക്ഷേ ഈ പ്രവർത്തനത്തിനുള്ള സ്കോപ്പ് (അല്ലെങ്കിൽ org ആക്സസ്) ഇല്ല.
  • 404 — റിസോഴ്സ് നിലവിലില്ല അല്ലെങ്കിൽ ഈ കീക്ക് ദൃശ്യമല്ല.
  • 409 — ഒരു വൈരുദ്ധ്യം, ഉദാഹരണത്തിന് ഇപ്പോൾ എടുത്ത ഒരു സ്ലോട്ട് ബുക്ക് ചെയ്യാൻ ശ്രമിക്കുന്നത്.
  • 429 — റേറ്റ് ലിമിറ്റ് ചെയ്തു; ബാക്ക് ഓഫ് ചെയ്ത് വീണ്ടും ശ്രമിക്കുക.
  • 5xx — ഒരു സെർവർ-സൈഡ് എറർ; താൽക്കാലിക പരാജയങ്ങൾ വീണ്ടും ശ്രമിക്കുക.

ഒരു സാധാരണ എറർ എൻവലപ്പ്:

{
  "success": false,
  "error": "validation_failed",
  "message": "A human-readable explanation of the problem."
}

ഉൽപ്പന്നം അനുസരിച്ചുള്ള റിസോഴ്സുകൾ​

മുകളിലുള്ള കൺവെൻഷനുകൾ പങ്കിടുന്നവയാണ്, പക്ഷേ ഓരോ ഉൽപ്പന്നവും അതിന്റേതായ എൻഡ്പോയിന്റുകൾ വെളിപ്പെടുത്തുന്നു. കൃത്യമായ റിസോഴ്സുകൾ, പാരാമീറ്ററുകൾ, ഫീൽഡ് നാമങ്ങൾ എന്നിവയ്ക്ക് ഉൽപ്പന്നത്തിന്റെ ഡെവലപ്പർ പേജിൽ നിന്ന് ആരംഭിക്കുക:

ബന്ധപ്പെട്ടവ​