कॉन्सेप्ट्स

Pagination और फ़ॉर्मैट

सूचियाँ cursor से paginate होती हैं। Responses JSON में होते हैं और उनके conventions पहले से तय हैं।

Cursor pagination#

सूची लौटाने वाला हर endpoint दो query parameters स्वीकार करता है:

Response का आकार हमेशा ऐसा होता है:

{
  "data": [ { "id": "1043", "...": "..." } ],
  "next_cursor": "eyJpZCI6IjEwNDMifQ"
}

जब next_cursor null हो, तो और पेज नहीं हैं। Cursors opaque strings होते हैं: इन्हें ख़ुद न बनाएँ या बदलें, और लंबे समय तक सेव न करें।

हर पेज पढ़ना#

curl "https://api.linework.app/open/v1/me/posts?limit=50" \
  -H "Authorization: Bearer $LINEWORK_API_KEY"

# next page: pass the next_cursor you received
curl "https://api.linework.app/open/v1/me/posts?limit=50&cursor=eyJpZCI6IjEwNDMifQ" \
  -H "Authorization: Bearer $LINEWORK_API_KEY"

async function* all(path) {
  let cursor = null;
  do {
    const url = new URL(`https://api.linework.app/open/v1${path}`);
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("cursor", cursor);
    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.LINEWORK_API_KEY}` },
    });
    const page = await res.json();
    yield* page.data;
    cursor = page.next_cursor;
  } while (cursor);
}

for await (const post of all("/me/posts")) console.log(post.id);

import os, requests

API = "https://api.linework.app/open/v1"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['LINEWORK_API_KEY']}"

def all_items(path):
    cursor = None
    while True:
        params = {"limit": 100}
        if cursor:
            params["cursor"] = cursor
        page = s.get(API + path, params=params, timeout=30).json()
        yield from page["data"]
        cursor = page.get("next_cursor")
        if not cursor:
            break

for post in all_items("/me/posts"):
    print(post["id"])

JSON conventions#

• फ़ील्ड्स के नाम camelCase में होते हैं (उदाहरण के लिए createdAt, mediaIds)। एकमात्र अपवाद सूची वाले responses में next_cursor है।
• Ids strings होती हैं, भले ही वे नंबर जैसी दिखें। उन्हें नंबर के रूप में parse न करें।
• तारीख़ें UTC में ISO 8601 strings होती हैं, उदाहरण के लिए 2026-10-14T09:30:00.000Z।
• Request bodies JSON (Content-Type: application/json) होती हैं, सिवाय POST /media के, जो multipart/form-data है।
• मौजूद न होने वाली optional वैल्यूज़ null होती हैं या छोड़ दी जाती हैं; दोनों को एक जैसा मानें।
• Responses में किसी भी समय नए फ़ील्ड्स जोड़े जा सकते हैं: जिन फ़ील्ड्स को आप नहीं जानते, उन्हें नज़रअंदाज़ करें।

Versioning#

वर्ज़न path में होता है (/open/v1)। v1 के भीतर हम केवल backward-compatible बदलाव करते हैं: नए endpoints, नए optional parameters, नए response फ़ील्ड्स, नए error codes। Breaking changes /open/v2 के रूप में आएँगे, जिनकी घोषणा changelog में काफ़ी पहले से की जाएगी।