21 ਅਕਤੂ 2025·8 ਮਿੰਟ
ਪਹਿਲੀ ਵਾਰੀ SaaS ਬਣਾਉਣ ਵਾਲਿਆਂ ਲਈ Public API ਡਿਜ਼ਾਈਨ: ਬੁਨਿਆਦੀ ਗੱਲਾਂ
ਪਹਿਲੀ ਵਾਰੀ SaaS ਬਣਾਉਣ ਵਾਲਿਆਂ ਲਈ Public API ਡਿਜ਼ਾਈਨ ਨੂੰ ਪ੍ਰਯੋਗਿਕ ਬਣਾਓ: ਵਰਜਨਿੰਗ, pagination, rate limits, docs ਅਤੇ ਇੱਕ ਛੋਟਾ SDK ਤੇਜ਼ੀ ਨਾਲ ਜਾਰੀ ਕਰੋ।
ਪਹਿਲੀ ਵਾਰੀ SaaS ਬਣਾਉਣ ਵਾਲਿਆਂ ਲਈ Public API ਡਿਜ਼ਾਈਨ ਨੂੰ ਪ੍ਰਯੋਗਿਕ ਬਣਾਓ: ਵਰਜਨਿੰਗ, pagination, rate limits, docs ਅਤੇ ਇੱਕ ਛੋਟਾ SDK ਤੇਜ਼ੀ ਨਾਲ ਜਾਰੀ ਕਰੋ।
Public API ਕੇਵਲ ਤੁਹਾਡੇ ਐਪ ਦਾ ਇੱਕ ਐਂਡਪੌਇੰਟ ਨਹੀਂ ਹੁੰਦਾ। ਇਹ ਤੁਹਾਡੇ ਬਾਹਰਲੇ ਲੋਕਾਂ ਨੂੰ ਇੱਕ ਵਾਅਦਾ ਹੈ ਕਿ ਕੰਟਰੈਕਟ ਚਲਦਾ ਰਹੇਗਾ, ਭਾਵੇਂ ਤੁਸੀਂ ਪ੍ਰੋਡਕਟ ਵਿੱਚ ਬਦਲਾਅ ਕਰਦੇ ਹੋ।
ਮੁਸ਼ਕਲ ਗੱਲ v1 ਲਿਖਣਾ ਨਹੀਂ, ਇਹ ਹੈ ਕਿ ਜਦੋਂ ਤੁਸੀਂ ਬੱਗ ਫਿਕਸ ਕਰੋ, ਫੀਚਰ ਜੋੜੋ, ਜਾਂ ਗਾਹਕਾਂ ਦੀਆਂ ਜ਼ਰੂਰਤਾਂ ਸਿੱਖੋ ਤਾਂ ਇਸਨੂੰ ਸਥਿਰ ਰੱਖਣਾ।
ਆਰੰਭਕ ਚੋਣਾਂ ਬਾਅਦ ਵਿੱਚ ਸਪੋਰਟ ਟਿਕਟਾਂ ਵਜੋਂ ਸਾਹਮਣੇ ਆਉਂਦੀਆਂ ਹਨ। ਜੇ ਰਿਸਪਾਂਸ ਦੀ ਸ਼ਕਲ ਬਿਨਾਂ ਚੇਤਾਵਨੀ ਦੇ ਬਦਲ ਜਾਏ, ਨੈਮਿੰਗ ਅਸੰਗਤ ਹੋਵੇ, ਜਾਂ ਕਲਾਇੰਟ ਪਤਾ ਨਾ ਲਗਾ ਸਕਣ ਕਿ ਰਿਕਵੇਸਟ ਸਫਲ ਰਹੀ ਕਿ ਨਹੀਂ, ਤਾਂ ਤਕਲਿਫ਼ ਬਣਦੀ ਹੈ। ਉਹ ਤਕਲਿਫ਼ ਅਣਵਿਸ਼ਵਾਸ਼ 'ਚ ਬਦਲਦੀ ਹੈ, ਅਤੇ ਲੋਕ ਤੁਹਾਡੇ ਉੱਤੇ ਨਿਰਭਰ ਕਰਨਾ ਛੱਡ ਦੇਂਦੇ ਹਨ।
ਤੇਜ਼ੀ ਵੀ ਮਹੱਤਵਪੂਰਣ ਹੈ। ਜ਼ਿਆਦਾਤਰ ਪਹਿਲੀ ਵਾਰੀ SaaS ਬਣਾਉਣ ਵਾਲਿਆਂ ਨੂੰ ਕੋਈ ਕਾਰਗਰ ਚੀਜ਼ ਤੇਜ਼ੀ ਨਾਲ ਰਿਲੀਜ਼ ਕਰਨੀ ਹੁੰਦੀ ਹੈ, ਫਿਰ ਉਸਨੂੰ ਸੁਧਾਰਨਾ। ਟ੍ਰੇਡਆਫ਼ ਸਪੱਸ਼ਟ ਹੈ: ਜਿੰਨਾ ਤੇਜ਼ ਤੁਸੀਂ ਬਿਨਾਂ ਨਿਯਮਾਂ ਦੇ ਰਿਲੀਜ਼ ਕਰੋਗੇ, ਉਤਨਾ ਹੀ ਜ਼ਿਆਦਾ ਸਮਾਂ ਤੁਹਾਨੂੰ ਉਹ ਫੈਸਲੇ ਵਾਪਸ ਕਰਨ ਵਿੱਚ ਲੱਗੇਗਾ ਜਦੋਂ ਅਸਲੀ ਉਪਭੋਗੀ ਆਉਣਗੇ।
v1 ਲਈ "ਕਾਫੀ ਚੰਗਾ" ਆਮ ਤੌਰ 'ਤੇ ਦਰਸਾਉਂਦਾ ਹੈ: ਥੋੜੇ endpoints ਜੋ ਅਸਲੀ ਯੂਜ਼ਰ ਕਾਰਵਾਈਆਂ ਨਾਲ ਮੇਲ ਖਾਂਦੇ ਹਨ, ਸਥਿਰ ਨੈਮਿੰਗ ਅਤੇ ਰਿਸਪਾਂਸ ਸ਼ੇਪ, ਇੱਕ ਸਾਫ਼ ਚੇਨਜ ਰਣਨੀਤੀ (ਭਾਵੇਂ ਸਿਰਫ v1 ਹੋਵੇ), ਪੇਜਿਨੇਸ਼ਨ ਦੀ ਭਵਿੱਖਬਾਣੀ ਯੋਗ ਪੇਸ਼ਕਸ਼ ਅਤੇ ਸਮਝਦਾਰ rate limits, ਅਤੇ ਐਸੀਆਂ ਦਸਤਾਵੇਜ਼ੀਕਰਨ ਜੋ ਦਿਖਾਉਂਦੀਆਂ ਹਨ ਕਿ ਕੀ ਭੇਜਣਾ ਹੈ ਅਤੇ ਤੁਹਾਨੂੰ ਕੀ ਵਾਪਸ ਮਿਲੇਗਾ।
ਇਕ ٹھوس ਉਦਾਹਰਣ: ਸੋਚੋ ਇੱਕ ਗਾਹਕ ਰਾਤ ਨੂੰ ਇਨਵੌਇਸ ਬਣਾਉਣ ਵਾਲੀ ਇੰਟੀਗ੍ਰੇਸ਼ਨ ਬਣਾਉਂਦਾ ਹੈ। ਜੇ ਤੁਸੀਂ ਬਾਅਦ ਵਿੱਚ ਇੱਕ ਫੀਲਡ ਦਾ ਨਾਮ ਬਦਲ ਦਿਓ, ਤਰੀਕਾਂ ਦੇ ਫਾਰਮੈਟ ਬਦਲ ਦਿਓ, ਜਾਂ ਚੁੱਪਚਾਪ ਹਿੱਸਾ ਨਤੀਜੇ ਵਾਪਸ ਕਰਨਾ ਸ਼ੁਰੂ ਕਰ ਦਿਓ ਤਾਂ ਉਹਨਾਂ ਦੀ ਜੌਬ 2 ਵਜੇ ਰਾਤ ਨੂੰ ਫੇਲ ਹੋ ਜਾਏਗੀ। ਉਹ ਤੁਹਾਡੇ API ਨੂੰ ਦੋਸ਼ ਦੇਣਗੇ, ਆਪਣੇ ਕੋਡ ਨੂੰ ਨਹੀਂ।
ਜੇ ਤੁਸੀਂ Koder.ai ਵਰਗੇ chat-driven ਟੂਲ ਨਾਲ ਬਣਾਉਂਦੇ ਹੋ ਤਾਂ ਤੇਜ਼ੀ ਨਾਲ ਬਹੁਤ ਸਾਰੇ endpoints ਜਨਰੇਟ ਕਰਨ ਦਾ ਮਨ ਕਰੇਗਾ। ਇਹ ਠੀਕ ਹੈ, ਪਰ public surface ਨੂੰ ਛੋਟਾ ਰੱਖੋ। ਤੁਸੀਂ ਅੰਦਰੂਨੀ endpoints ਨੂੰ ਗੁਪਤ ਰੱਖ ਸਕਦੇ ਹੋ ਜਦੋਂ ਤੱਕ ਤੁਸੀਂ ਨਹੀਂ ਸਿੱਖ ਲੈਂਦੇ ਕਿ ਕੀ ਲੰਬੇ ਸਮੇਂ ਲਈ ਕੰਟਰੈਕਟ ਦਾ ਹਿੱਸਾ ਹੋਣਾ ਚਾਹੀਦਾ ਹੈ।
ਚੰਗੀ public API ਡਿਜ਼ਾਈਨ ਉਸ ਛੋਟੀ ਗਿਣਤੀ ਦੇ ਨਾਉਂ (resources) ਚੁਣਨ ਨਾਲ ਸ਼ੁਰੂ ਹੁੰਦੀ ਹੈ ਜੋ ਗਾਹਕ ਤੁਹਾਡੇ ਪ੍ਰੋਡਕਟ ਬਾਰੇ ਗੱਲ ਕਰਨ ਵੇਲੇ ਵਰਤਦੇ ਹਨ। resource ਨਾਂ ਸਥਿਰ ਰੱਖੋ ਭਾਵੇਂ ਤੁਹਾਡਾ ਅੰਦਰੂਨੀ ਡਾਟਾਬੇਸ ਬਦਲੇ। ਜਦੋਂ ਤੁਸੀਂ ਫੀਚਰ ਜੋੜਦੇ ਹੋ, ਤਾਂ ਕੋਰ resources ਦਾ ਨਾਮ ਬਦਲਣ ਦੀ ਥਾਂ ਫੀਲਡ ਜਾਂ ਨਵੇਂ endpoints ਜੋੜਨਾ ਪਸੰਦ ਕਰੋ।
ਅਧਿਕਤਮ SaaS ਪ੍ਰੋਡਕਟਾਂ ਲਈ ਇੱਕ ਪ੍ਰੈਕਟਿਕਲ ਸ਼ੁਰੂਆਤ ਹੈ: users, organizations, projects, ਅਤੇ events। ਜੇ ਤੁਸੀਂ ਕਿਸੇ resource ਨੂੰ ਇੱਕ ਵਾਕ ਵਿੱਚ ਸਮਝਾ ਨਹੀਂ ਸਕਦੇ, ਤਾਂ ਉਹ ਸ਼ਾਇਦ public ਕਰਨ ਲਈ ਤਿਆਰ ਨਹੀਂ ਹੈ।
HTTP ਦੀ ਵਰਤੋਂ ਨਿਰਾਖਣ ਅਤੇ ਅਨੁਮਾਨਯੋਗ ਰੱਖੋ:
Auth ਦੀ ਪਹਿਲੇ ਦਿਨ fancy ਹੋਣ ਦੀ ਲੋੜ ਨਹੀਂ। ਜੇ ਤੁਹਾਡਾ API ਮੁੱਖ ਤੌਰ ਤੇ server-to-server ਹੈ (ਗਾਹਕ ਆਪਣੇ ਬੈਕਐਂਡ ਤੋਂ ਕਾਲ ਕਰਦੇ ਹਨ), ਤਾਂ API keys ਅਕਸਰ ਕਾਫ਼ੀ ਹੁੰਦੇ ਹਨ। ਜੇ ਗਾਹਕਾਂ ਨੂੰ ਅ Individual end users ਵਜੋਂ ਕਾਰਵਾਈ ਕਰਨ ਦੀ ਲੋੜ ਹੈ, ਜਾਂ ਤੁਸੀਂ ਤੀਜੀ-ਪੱਖ ਇਨਟੀਗ੍ਰੇਸ਼ਨ ਦੀ ਉਮੀਦ ਕਰਦੇ ਹੋ ਜਿੱਥੇ ਯੂਜ਼ਰ ਐਕਸੈਸ ਦੇਂਦੇ ਹਨ, ਤਾਂ OAuth ਜਿਆਦਾ ਫਿੱਟ ਹੁੰਦਾ ਹੈ। ਫੈਸਲਾ ਸਧਾਰਨ ਭਾਸ਼ਾ ਵਿੱਚ ਲਿਖੋ: ਕੌਣ ਕਾਲਰ ਹੈ ਅਤੇ ਉਹ ਕਿਸ ਦੀਆਂ ਡੇਟਾ ਨੂੰ ਛੂਹ ਸਕਦਾ ਹੈ?
ਛੇਤੀ ਉਮੀਦਾਂ ਸੈੱਟ ਕਰੋ। ਸਪਸ਼ਟ ਕਰੋ ਕਿ ਕੀ ਸਮਰਥਿਤ ਹੈ ਅਤੇ ਕੀ best-effort ਹੈ। ਉਦਾਹਰਣ ਵਜੋਂ: list endpoints ਸਥਿਰ ਅਤੇ backward-compatible ਹਨ, ਪਰ search filters ਵਧ ਸਕਦੇ ਹਨ ਅਤੇ ਪੂਰੀ ਗਾਰੰਟੀ ਨਹੀਂ ਹੈ। ਇਹ ਸਪੋਰਟ ਟਿਕਟਾਂ ਘਟਾਉਂਦਾ ਹੈ ਅਤੇ ਤੁਹਾਨੂੰ ਸੁਧਾਰ ਕਰਨ ਦੀ ਆਜ਼ਾਦੀ ਦਿੰਦਾ ਹੈ।
ਜੇ ਤੁਸੀਂ Koder.ai ਵਰਗੇ vibe-coding ਪਲੇਟਫਾਰਮ 'ਤੇ ਬਣਾਉਂਦੇ ਹੋ, ਤਾਂ API ਨੂੰ ਇੱਕ ਪ੍ਰੋਡਕਟ ਕੰਟਰੈਕਟ ਵਜੋਂ ਸਲੂਕ ਕਰੋ: ਪਹਿਲਾਂ ਕੰਟਰੈਕਟ ਛੋਟਾ ਰੱਖੋ, ਫਿਰ ਅਸਲੀ ਵਰਤੋਂ ਦੇ ਆਧਾਰ 'ਤੇ ਵਧਾਓ, ਅਨੁਮਾਨਾਂ ਦੇ ਆਧਾਰ 'ਤੇ ਨਹੀਂ।
Versioning ਮੁੱਖ ਤੌਰ 'ਤੇ ਉਮੀਦਾਂ ਬਾਰੇ ਹੈ। ਕਲਾਇੰਟ ਜਾਣਨਾ ਚਾਹੁੰਦੇ ਹਨ: ਕੀ ਮੇਰੀ ਇਨਟੀਗ੍ਰੇਸ਼ਨ ਆਉਣ ਵਾਲੇ ਹਫ਼ਤੇ ਟੁੱਟ ਜਾਵੇਗੀ? ਤੁਸੀਂ ਬਿਨਾਂ ਡਰ ਦੇ ਚੀਜ਼ਾਂ ਸੁਧਾਰ ਕਰਨ ਲਈ ਥਾਂ ਚਾਹੁੰਦੇ ਹੋ।
Header-ਅਧਾਰਤ versioning ਸੁੱਧ ਦਰਸਦੀ ਹੈ, ਪਰ ਇਹ ਲੋਗਜ਼, caches, ਅਤੇ ਸਪੋਰਟ ਸਕਰੀਨਸ਼ਾਟਸ ਵਿੱਚ ਛੁਪ ਸਕਦੀ ਹੈ। URL versioning ਆਮ ਤੌਰ 'ਤੇ ਸਭ ਤੋਂ ਸਾਦਾ ਚੋਣ ਹੈ: /v1/.... ਜਦੋਂ ਕੋਈ ਗਾਹਕ ਤੁਹਾਨੂੰ ਫੇਲ ਹੋਣ ਵਾਲੀ ਰਿਕਵੇਸਟ ਭੇਜੇ, ਤੁਸੀਂ ਤੁਰੰਤ ਵਰਜਨ ਦੇਖ ਸਕਦੇ ਹੋ। ਇਸ ਨਾਲ v1 ਅਤੇ v2 ਨੂੰ ਇਕੱਠੇ ਚਲਾਉਣਾ ਵੀ ਆਸਾਨ ਹੁੰਦਾ ਹੈ।
ਇੱਕ ਬਦਲਾਅ breaking ਹੈ ਜੇ ਇੱਕ ਵਧੀਆ ਤਰੀਕੇ ਨਾਲ ਬਣਾਇਆ ਗਿਆ ਕਲਾਇੰਟ ਬਿਨਾਂ ਆਪਣਾ ਕੋਡ ਬਦਲੇ ਕੰਮ ਕਰਨਾ ਬੰਦ ਕਰ ਸਕਦਾ ਹੈ। ਆਮ ਉਦਾਹਰਣ:
customer_id ਨੂੰ customerId ਕਰਨਾ)ਇੱਕ محفوظ ਬਦਲਾਅ ਉਹ ਹੈ ਜੋ ਪੁਰਾਣੇ ਕਲਾਇੰਟ ਨੂੰ ਨਜ਼ਰਅੰਦਾਜ਼ ਕਰਨ ਯੋਗ ਹੋਵੇ। ਇੱਕ ਨਵਾਂ optional ਫੀਲਡ ਜੁੜਨਾ ਆਮ ਤੌਰ 'ਤੇ محفوظ ਹੁੰਦਾ ਹੈ। ਉਦਾਹਰਣ ਲਈ, GET /v1/subscriptions ਦੇ ਰਿਸਪਾਂਸ ਵਿੱਚ plan_name ਜੁੜਨਾ ਉਹਨਾਂ ਕਲਾਇੰਟਾਂ ਨੂੰ ਨਹੀਂ ਤੋੜੇਗਾ ਜੋ ਸਿਰਫ status ਪੜ੍ਹਦੇ ਹਨ।
ਇਕ ਪ੍ਰਾਇਕਟਿਕ ਨਿਯਮ: ਇੱਕੇ major version ਦੇ ਅੰਦਰ ਫੀਲਡਾਂ ਨੂੰ ਹਟਾਉਣਾ ਜਾਂ ਉਨ੍ਹਾਂ ਦਾ ਮੁੜ ਉਪਯੋਗ ਨਾ ਕਰੋ। ਨਵੇਂ ਫੀਲਡ ਜੋੜੋ, ਪੁਰਾਣੇ ਰੱਖੋ, ਅਤੇ ਸਿਰਫ਼ ਜਦੋਂ ਤੁਸੀਂ ਪੂਰੀ ਵਰਜਨ ਨੂੰ ਡੀਪ੍ਰੀਕੇਟ ਕਰਨ ਲਈ ਤਿਆਰ ਹੋ ਤਦ ਉਹਨਾਂ ਨੂੰ ਰਿਟਾਇਰ ਕਰੋ।
ਇਸਨੂੰ ਸਧਾਰਨ ਰੱਖੋ: ਡੀਪ੍ਰੀਕੇਸ਼ਨ ਪਹਿਲਾਂ ਐਲਾਨ ਕਰੋ, ਰਿਸਪਾਂਸ ਵਿੱਚ ਇੱਕ ਸਾਫ਼ ਚੇਤਾਵਨੀ ਵਾਪਸ ਕਰੋ, ਅਤੇ ਇੱਕ ਅੰਤ ਮਿਤੀ ਨਿਰਧਾਰਤ ਕਰੋ। ਪਹਿਲੇ API ਲਈ 90-ਦਿਨਾਂ ਦੀ ਵਿੰਡੋ ਅਕਸਰ ਵਾਸਤਵਿਕ ਹੁੰਦੀ ਹੈ। ਇਸ ਦੌਰਾਨ, v1 ਚਲਦਾ ਰਹੇ, ਇੱਕ ਛੋਟੀ migration ਨੋਟ ਪ੍ਰਕਾਸ਼ਿਤ ਕਰੋ, ਅਤੇ ਯਕੀਨੀ ਬਣਾਓ ਕਿ ਸਪੋਰਟ ਇੱਕ ਵਾਕ ਦੇ ਸਕੇ: v1 ਇਸ ਤਾਰੀਖ ਤੱਕ ਚਲਦੀ ਹੈ; ਇਹ v2 ਵਿੱਚ ਕੀ ਬਦਲਿਆ।
ਜੇ ਤੁਸੀਂ Koder.ai ਵਰਗੇ ਪਲੇਟਫਾਰਮ 'ਤੇ ਬਣਾਉਂਦੇ ਹੋ, ਤਾਂ API ਵਰਜਨਾਂ ਨੂੰ snapshot ਵਾਂਗ ਸਮਝੋ: ਸੁਧਾਰ ਨਵੀਂ ਵਰਜਨ ਵਿੱਚ ਰਿਲੀਜ਼ ਕਰੋ, ਪੁਰਾਣੀ ਨੂੰ ਸਥਿਰ ਰੱਖੋ, ਅਤੇ ਕੇਵਲ ਉਸ ਵੇਲੇ ਕੱਟੋ ਜਦੋਂ ਤੁਸੀਂ ਗਾਹਕਾਂ ਨੂੰ ਮਾਈਗਰੇਟ ਕਰਨ ਲਈ ਸਮਾਂ ਦੇ ਚੁੱਕੇ ਹੋਵੋ।
Pagination ਉਹ ਥਾਂ ਹੈ ਜਿੱਥੇ ਭਰੋਸਾ ਜੀਤਿਆ ਜਾਂ ਖੋ ਦਿੱਤਾ ਜਾਂਦਾ ਹੈ। ਜੇ ਨਤੀਜੇ ਕਹਾਣੀਆਂ ਦੌਰਾਨ ਬਦਲਦੇ ਰਹਿਣ, ਲੋਕ ਤੁਹਾਡੇ API 'ਤੇ ਭਰੋਸਾ ਕਰਨਾ ਬੰਦ ਕਰਦੇ ਹਨ।
ਜਦੋਂ ਡੇਟਾ ਸੈੱਟ ਛੋਟਾ ਹੋਵੇ, ਕਵੈਰੀ ਸਧਾਰਣ ਹੋਵੇ, ਅਤੇ ਯੂਜ਼ਰ ਅਕਸਰ ਪੇਜ 3 ਵਗੈਰਾ ਦੇਖਣਾ ਚਾਹੁੰਦੇ ਹੋਣ ਤਾਂ page/limit ਵਰਤੋਂ। ਜਦੋਂ lists ਵੱਡੀਆਂ ਹੋ ਸਕਦੀਆਂ ਹਨ, ਨਵੇਂ ਆਈਟਮ ਅਕਸਰ ਆਉਂਦੇ ਹਨ, ਜਾਂ ਯੂਜ਼ਰ ਬਹੁਤ ਸਾਰਾ sort ਅਤੇ filter ਕਰ ਸਕਦੇ ਹਨ ਤਾਂ cursor-based pagination ਵਰਤੋਂ। Cursor-based pagination ਨਵੀਆਂ ਰਿਕਾਰਡਾਂ ਦੇ ਆਉਣ 'ਤੇ ਵੀ ਅਨੁਕ੍ਰਮਨ ਨੂੰ ਸਥਿਰ ਰੱਖਦੀ ਹੈ।
ਕੁਝ ਨਿਯਮ pagination ਨੂੰ ਭਰੋਸੇਯੋਗ ਰੱਖਦੇ ਹਨ:
Totals ਮੁਸ਼ਕਲ ਹੋ ਸਕਦੇ ਹਨ। total_count ਵੱਡੀਆਂ ਟੇਬਲਾਂ 'ਤੇ ਮਹਿੰਗਾ ਹੋ ਸਕਦਾ ਹੈ, ਖਾਸ ਕਰਕੇ filters ਦੇ ਨਾਲ। ਜੇ ਤੁਸੀਂ ਓਹਨੂੰ ਸਸਤਾ ਤਰੀਕੇ ਨਾਲ ਦੇ ਸਕਦੇ ਹੋ, ਤਾਂ ਸ਼ਾਮِل ਕਰੋ। ਜੇ ਨਹੀਂ, ਤਾਂ ਇਸਨੂੰ ਛੱਡੋ ਜਾਂ query flag ਰਾਹੀਂ ਵਿਕਲਪੀ ਰੱਖੋ।
ਇੱਥੇ ਸਧਾਰਣ request/response ਸ਼ੇਪ ਹਨ.
// Page/limit
GET /v1/invoices?page=2&limit=25&sort=created_at_desc
{
"items": [{"id":"inv_1"},{"id":"inv_2"}],
"page": 2,
"limit": 25,
"total_count": 142
}
// Cursor-based
GET /v1/invoices?limit=25&cursor=eyJjcmVhdGVkX2F0IjoiMjAyNi0wMS0wOVQxMDozMDowMFoiLCJpZCI6Imludl8xMDAifQ==
{
"items": [{"id":"inv_101"},{"id":"inv_102"}],
"next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wMS0wOVQxMDoyNTowMFoiLCJpZCI6Imludl8xMjUifQ=="
}
Rate limits ਸਖ਼ਤੀ ਬਾਰੇ ਘੱਟ ਅਤੇ online ਰਹਿਣ ਬਾਰੇ ਜ਼ਿਆਦਾ ਹਨ। ਉਹ ਤੁਹਾਡੇ ਐਪ ਨੂੰ ਟ੍ਰੈਫਿਕ ਸਪਾਈਕ ਤੋਂ, ਤੁਹਾਡੇ ਡੇਟਾਬੇਸ ਨੂੰ ਮਹਿੰਗੀਆਂ ਕਵੈਰੀਜ਼ ਤੋਂ, ਅਤੇ ਤੁਹਾਡੇ ਬੁਕਤਾਂ (wallet) ਨੂੰ ਅਚਾਨਕ ਇੰਫਰਾਸਟ੍ਰਕਚਰ ਬਿਲਾਂ ਤੋਂ ਬਚਾਉਂਦੇ ਹਨ। ਇੱਕ limit ਇੱਕ ਕੰਟਰੈਕਟ ਵੀ ਹੈ: ਕਲਾਇੰਟ ਜਾਣਦੇ ਹਨ ਕਿ ਆਮ ਵਰਤੋਂ ਕੀ ਹੈ।
ਸਰਲ ਸ਼ੁਰੂ ਕਰੋ ਅਤੇ ਬਾਅਦ ਵਿੱਚ ਟਿਊਨ ਕਰੋ। ਕੁਝ ਥੋੜ੍ਹਾ ਜਿਹਾ ਕਵਰ ਕਰਨ ਵਾਲੀ ਚੀਜ਼ ਚੁਣੋ ਜੋ ਆਮ ਵਰਤੋਂ ਨੂੰ ਮਕਬੂਲ ਕਰੇ, ਫਿਰ ਅਸਲ ਟ੍ਰੈਫਿਕ ਵੇਖੋ। ਜੇ ਤੁਹਾਡੇ ਕੋਲ ਹੁਣ ਤੱਕ ਡਾਟਾ ਨਹੀਂ ਹੈ, ਤਾਂ ਇੱਕ محفوظ ਡਿਫਾਲਟ ਇੱਕ per-API-key limit ਜਿਵੇਂ 60 requests per minute ਨਾਲ਼ ਇੱਕ ਛੋਟਾ burst allowance ਹੈ। ਜੇ ਕੋਈ endpoint ਬਹੁਤ ਭਾਰੀ ਹੈ (ਜਿਵੇਂ search ਜਾਂ exports), ਤਾਂ ਉਹਨੂੰ ਕਠੋਰ limit ਦਿਓ ਜਾਂ ਅਲੱਗ cost rule ਦਿਓ ਨਾ ਕਿ ਹਰ ਰਿਕਵੇਸਟ ਨੂੰ ਸਜ਼ਾ ਦਿਓ।
ਜਦੋਂ ਤੁਸੀਂ limits ਲਗਾਉਂਦੇ ਹੋ, ਤਾਂ ਕਲਾਇੰਟ ਨੂੰ ਸਹੀ ਕਰਮ ਕਰਨ ਵਿੱਚ ਸੌਖਾ ਬਣਾਓ। 429 Too Many Requests ਰਿਸਪਾਂਸ ਵਾਪਸ ਕਰੋ ਅਤੇ ਕੁਝ ਸਟੈਂਡਰਡ headers ਸ਼ਾਮਿਲ ਕਰੋ:
X-RateLimit-Limit: window ਵਿੱਚ ਵੱਧ ਤੋਂ ਵੱਧX-RateLimit-Remaining: ਕਿੰਨੇ ਬਚੇ ਹਨX-RateLimit-Reset: ਕਦੋਂ window ਰੀਸੈਟ ਹੋਵੇਗੀ (timestamp ਜਾਂ seconds)Retry-After: ਦੁਬਾਰਾ ਕੋਸ਼ਿਸ਼ ਕਰਨ ਤੋਂ ਪਹਿਲਾਂ ਕਿੰਨੀ ਦੇਰ ਰੁਕੋਕਲਾਇੰਟਾਂ ਨੂੰ 429 ਨੂੰ ਇੱਕ ਆਮ ਹਾਲਤ ਸਮਝਣਾ ਚਾਹੀਦਾ ਹੈ, ਕੋਈ ਗਲਤੀ ਜੋ ਲੜਾਈ ਕਰਨ ਦੀ। ਇੱਕ ਸੌਖਾ retry ਪੈਟਰਨ ਦੋਹਾਂ ਪਾਸਿਆਂ ਨੂੰ ਖੁਸ਼ ਰੱਖਦਾ ਹੈ:
Retry-After ਮੌਜੂਦ ਹੋਵੇ ਤਾਂ ਉਸਦਾ ਇੰਤਜ਼ਾਰ ਕਰੋਉਦਾਹਰਣ: ਜੇ ਕੋਈ ਗਾਹਕ ਆਪਣਾ nightly sync ਚਲਾਉਂਦਾ ਹੈ ਜੋ ਤੁਹਾਡੇ API 'ਤੇ ਭਾਰੀ ਹੁੰਦਾ ਹੈ, ਤਾਂ ਉਹਨਾਂ ਦੀ ਜੌਬ minute ਦੇ ਅੰਦਰ ਬੇਟਾਂ ਵਿੱਚ requests ਫੈਲਾ ਸਕਦੀ ਹੈ ਅਤੇ 429 ਆਉਣ 'ਤੇ ਆਪਣੇ ਆਪ ਧੀਮੇ ਹੋ ਸਕਦੀ ਹੈ ਬਜਾਏ ਪੂਰੀ ਰਨ ਨੂੰ ਫੇਲ ਕਰਨ ਦੇ।
ਜੇ ਤੁਹਾਡੇ API errors ਪੜ੍ਹਨ ਲਈ ਔਖੇ ਹਨ, ਤਾਂ ਸਪੋਰਟ ਟਿਕਟ ਜਲਦੀ ਹੀ ਵੱਧ ਜਾਣਗੇ। ਇੱਕ error shape ਚੁਣੋ ਅਤੇ ਹਰ ਜਗ੍ਹਾ ਉਨ੍ਹਾਂ ਨਾਲ ਚਿੱਪਕੋ, 500s ਸਮੇਤ। ਇੱਕ ਸਧਾਰਣ standard ਹੁੰਦਾ ਹੈ: code, message, details, ਅਤੇ ਇੱਕ request_id ਜੋ ਯੂਜ਼ਰ ਸਪੋਰਟ ਚੈਟ ਵਿੱਚ ਪੇਸਟ ਕਰ ਸਕੇ।
ਇੱਥੇ ਇੱਕ ਛੋਟਾ, ਭਵਿੱਖਬਾਣੀ ਯੋਗ ਫਾਰਮੈਟ ਹੈ:
{
"error": {
"code": "validation_error",
"message": "Some fields are invalid.",
"details": {
"fields": [
{"name": "email", "issue": "must be a valid email"},
{"name": "plan", "issue": "must be one of: free, pro, business"}
]
},
"request_id": "req_01HT..."
}
}
HTTP status codes ਨੂੰ ਹਰ ਵਾਰ ਇੱਕੋ ਤਰ੍ਹਾਂ ਵਰਤੋਂ: 400 ਬੁਰਾ ਇਨਪੁੱਟ, 401 ਜਦ auth ਗੈਰ-ਹਾਜ਼ਿਰ ਜਾਂ ਗਲਤ ਹੋਵੇ, 403 ਜਦ ਯੂਜ਼ਰ authenticated ਹੋ ਕੇ ਵੀ permission ਨਹੀਂ ਰੱਖਦਾ, 404 ਜਦ resource ਨਹੀਂ ਮਿਲਦਾ, 409 conflicts ਲਈ (ਜਿਵੇਂ duplicate unique value ਜਾਂ ਗਲਤ state), 429 rate limits ਲਈ, ਅਤੇ 500 server errors ਲਈ। consistency ਜਿਆਦਾ ਮਹੱਤਵਪੂਰਣ ਹੈ।
Validation errors ਨੂੰ ਠੀਕ ਕਰਨਾ ਆਸਾਨ ਬਣਾਓ। ਫੀਲਡ-ਲੇਵਲ hints ਨੂੰ ਉਹੀ ਪਰਮੀਟਰ ਨਾਮ ਦਿਖਾਉਣਾ ਚਾਹੀਦਾ ਹੈ ਜੋ ਤੁਹਾਡੇ docs ਵਰਤਦੇ ਹਨ, ਨਾ ਕਿ ਅੰਦਰੂਨੀ ਡਾਟਾਬੇਸ ਕਾਲਮ। ਜੇ ਕਿਸੇ ਫਾਰਮੈਟ ਦੀ ਲੋੜ ਹੈ (date, currency, enum), ਤਾਂ ਦੱਸੋ ਕਿ ਤੁਸੀਂ ਕੀ ਸਵੀਕਾਰ ਕਰਦੇ ਹੋ ਅਤੇ ਉਦਾਹਰਣ ਦਿਖਾਓ।
Retries ਉਹ ਥਾਂ ਹਨ ਜਿੱਥੇ ਬਹੁਤ ਸਾਰੇ APIs ਗਲਤੀ ਨਾਲ duplicate data ਬਣਾਉਂਦੇ ਹਨ। ਮਹत्वਪੂਰਣ POST ਐਕਸ਼ਨਾਂ (payments, invoice creation, sending emails) ਲਈ idempotency keys ਸਪੋਰਟ ਕਰੋ ਤਾਂ ਕਿ ਕਲਾਇੰਟ ਸੁਰੱਖਿਅਤ ਤੌਰ 'ਤੇ retry ਕਰ ਸਕਣ।
Idempotency-Key header ਮਨਨ ਕਰੋ।ਉਹ ਇਕ header ਬਹੁਤ ਸਾਰੀਆਂ ਦਰਦਨਾਕ edge cases ਨੂੰ ਰੋਕਦਾ ਹੈ ਜਦ ਨੈਟਵਰਕ flaky ਹੋਵੇ ਜਾਂ ਕਲਾਇੰਟ timeouts ਮਾਰਦੇ ਹੋਣ।
ਮਾਨੋ ਤੁਸੀਂ ਇੱਕ ਸਧਾਰਣ SaaS ਚਲਾਉਂਦੇ ਹੋ ਜਿਸਦੇ ਤਿੰਨ ਮੁੱਖ object ਹਨ: projects, users, ਅਤੇ invoices। ਇੱਕ project ਵਿੱਚ ਬਹੁਤ ਸਾਰੇ users ਹਨ, ਅਤੇ ਹਰ project ਨੂੰ ਮਹੀਨਾਵਾਰ invoices ਮਿਲਦੇ ਹਨ। ਕਲਾਇੰਟ invoices ਨੂੰ ਆਪਣੇ accounting ਟੂਲ ਵਿੱਚ sync ਕਰਨਾ ਚਾਹੁੰਦੇ ਹਨ ਅਤੇ ਆਪਣੀ ਐਪ ਵਿੱਚ ਸਧਾਰਣ billing ਦਿਖਾਉਣਾ ਚਾਹੁੰਦੇ ਹਨ।
ਇੱਕ ਸਾਫ਼ v1 ਇਸ ਤਰ੍ਹਾਂ ਹੋ ਸਕਦਾ ਹੈ:
GET /v1/projects/{project_id}
GET /v1/projects/{project_id}/invoices
POST /v1/projects/{project_id}/invoices
ਹੁਣ ਇੱਕ breaking change ਹੁੰਦੀ ਹੈ। v1 ਵਿੱਚ ਤੁਸੀਂ invoice amounts ਨੂੰ cents ਵਿੱਚ ਇੱਕ integer ਵਜੋਂ ਸਟੋਰ ਕਰਦੇ ਸੀ: amount_cents: 1299। ਬਾਅਦ ਵਿੱਚ ਤੁਹਾਨੂੰ multi-currency ਅਤੇ decimals ਦੀ ਲੋੜ ਪੈਂਦੀ ਹੈ, ਇਸ ਲਈ ਤੁਸੀਂ amount: "12.99" ਅਤੇ currency: "USD" ਚਾਹੁੰਦੇ ਹੋ। ਜੇ ਤੁਸੀਂ ਪੁਰਾਣੇ ਫੀਲਡ ਨੂੰ ਓਵਰਰਾਈਟ ਕਰ ਦਿਓਗੇ ਤਾਂ ਹਰ ਮੌਜੂਦਾ ਇਨਟੀਗ੍ਰੇਸ਼ਨ ਟੁੱਟ ਜਾਵੇਗਾ। Versioning panic ਤੋਂ ਬਚਾਉਂਦੀ ਹੈ: v1 ਨੂੰ ਸਥਿਰ ਰੱਖੋ, /v2/... ਨਾਲ ਨਵੇਂ ਫੀਲਡ ਸ਼ਿਪ ਕਰੋ, ਅਤੇ clients ਮਾਈਗਰੇਟ ਕਰਨ ਤੱਕ ਦੋਹਾਂ ਨੂੰ ਸਹਾਇਤ ਕਰੋ।
ਇਨਵੌਇਸਾਂ ਦੀ ਲਿਸਟ ਕਰਨ ਲਈ, ਇੱਕ ਪ੍ਰਾਡਿਕਟਬਲ pagination shape ਵਰਤੋ। ਉਦਾਹਰਣ:
GET /v1/projects/p_123/invoices?limit=50&cursor=eyJpZCI6Imludl85OTkifQ==
200 OK
{
"data": [ {"id":"inv_1001"}, {"id":"inv_1000"} ],
"next_cursor": "eyJpZCI6Imludl8xMDAwIn0="
}
ਇਕ ਦਿਨ ਇੱਕ ਗਾਹਕ invoices ਨੂੰ ਲੂਪ ਵਿੱਚ ਇੰਪੋਰਟ ਕਰਦਾ ਹੈ ਅਤੇ ਤੁਹਾਡੇ rate limit ਨੂੰ ਹਿੱਟ ਕਰ ਲੈਂਦਾ ਹੈ। ਬੇਰੂਪ ਫੇਲ੍ਹਾਂ ਦੀ ਥਾਂ, ਉਹਨਾਂ ਨੂੰ ਇੱਕ ਸਾਫ਼ ਰਿਸਪਾਂਸ ਮਿਲਦੀ ਹੈ:
429 Too Many RequestsRetry-After: 20{ "error": { "code": "rate_limited" } }ਉਹਨਾਂ ਦੀ ਪਾਸੇ, ਕਲਾਇੰਟ 20 ਸਕਿੰਟ ਲਈ ਰੁੱਕ ਸਕਦਾ ਹੈ, ਫਿਰ ਉਥੋਂ ਹੀ cursor ਤੋਂ ਜਾਰੀ ਰੱਖ ਸਕਦਾ ਹੈ ਬਿਨਾਂ ਸਭ ਕੁਝ ਮੁੜ-ਡਾਊਨਲੋਡ ਕੀਤੇ ਜਾਂ duplicate invoices ਬਣਾਏ।
v1 ਲਾਂਚ ਉਹ ਸਮੇਂ ਬਿਹਤਰ ਹੁੰਦਾ ਹੈ ਜਦੋਂ ਤੁਸੀਂ ਇਸਨੂੰ ਇੱਕ ਛੋਟੀ ਪ੍ਰੋਡਕਟ ਰਿਲੀਜ਼ ਵਾਂਗ ਟ੍ਰੀਟ ਕਰੋ ਨਾ ਕਿ endpoints ਦਾ ਇਕ ਢੇਰ। ਮਕਸਦ ਸਧਾਰਨ ਹੈ: ਲੋਕ ਇਸ ਤੇ ਬਣਾਉਣ ਦੇ ਯੋਗ ਹੋਣ ਅਤੇ ਤੁਸੀਂ ਬਿਨਾਂ ਹੈਰਾਨੀ ਦੇ ਇਸਨੂੰ ਸੁਧਾਰ ਸਕੋ।
ਇੱਕ ਪੰਨਾ ਲਿਖ ਕੇ ਸ਼ੁਰੂ ਕਰੋ ਜੋ ਵਿਆਖਿਆ ਕਰਦਾ ਹੈ ਕਿ ਤੁਹਾਡਾ API ਕਿਸ ਲਈ ਹੈ ਅਤੇ ਕੀ ਨਹੀਂ। surface area ਇੰਨੀ ਛੋਟੀ ਰੱਖੋ ਕਿ ਤੁਸੀਂ ਇਸਨੂੰ ਇੱਕ ਮਿੰਟ ਵਿੱਚ ਉਮਰਾਉ ਸਕੋ।
ਇਸ ਲੜੀ ਨੂੰ ਵਰਤੋਂ ਅਤੇ ਹਰ ਕਦਮ ਤੱਕ ਚੰਗਾ ਨਾ ਹੋਵੇ ਤੱਕ ਅੱਗੇ ਨਾ ਵਧੋ:
ਜੇ ਤੁਸੀਂ code-generating workflow ਵਰਤ ਰਹੇ ਹੋ (ਉਦਾਹਰਣ, Koder.ai ਵਰਤ ਕੇ endpoints ਅਤੇ responses scaffold ਕਰਨਾ), ਤਾਂ ਫਿਰ ਵੀ fake-client ਟੈਸਟ ਕਰੋ। ਜਨਰੇਟ ਕੀਤਾ ਕੋਡ ਠੀਕ ਲੱਗ ਸਕਦਾ ਹੈ ਪਰ ਵਰਤਣ ਵਿੱਚ awkward ਹੋ ਸਕਦਾ ਹੈ।
ਫੈਦੇ ਇਹ ਹਨ: ਘੱਟ ਸਪੋਰਟ ਈਮੇਲ, ਘੱਟ hotfix releases, ਅਤੇ ਇੱਕ v1 ਜੋ ਤੁਸੀਂ ਅਸਲ ਵਿੱਚ ਰੱਖ-ਰਖਾਵ ਕਰ ਸਕਦੇ ਹੋ।
ਪਹਿਲੀ SDK ਦੂਜੀ ਉਤਪਾਦ ਨਹੀਂ ਹੈ। ਇਸਨੂੰ ਤੁਹਾਡੇ HTTP API ਦਾ ਇੱਕ ਪਤਲਾ, ਸਹਿਜ ਰੈਪਪਰ ਸਮਝੋ। ਇਹ ਆਮ calls ਨੂੰ ਆਸਾਨ ਬਣਾਉਣਾ ਚਾਹੀਦਾ ਹੈ, ਪਰ ਇਹ API ਕੰਮ ਕਰਨ ਦੇ ਤਰੀਕੇ ਨੂੰ ਛੁਪਾਉਣਾ ਨਹੀਂ ਚਾਹੀਦਾ। ਜੇ ਕਿਸੇ ਨੂੰ ਕੋਈ ਫੀਚਰ ਤੁਸੀਂ ਹਜੇ ਰੈਪ ਨਹੀਂ ਕੀਤਾ, ਤਾਂ ਉਹਨਾਂ ਨੂੰ ਅਜੇ ਵੀ raw requests 'ਤੇ ਥੱਲੇ ਆ ਸਕਣਾ ਚਾਹੀਦਾ ਹੈ।
ਇੱਕ زبان ਚੁਣੋ ਸ਼ੁਰੂ ਕਰਨ ਲਈ, ਜੋ ਤੁਹਾਡੇ ਗਾਹਕ ਅਸਲ ਵਿੱਚ ਵਰਤਦੇ ਹਨ। ਬਹੁਤ ਸਾਰੀਆਂ B2B SaaS APIs ਲਈ ਇਹ ਅਕਸਰ JavaScript/TypeScript ਜਾਂ Python ਹੁੰਦਾ ਹੈ। ਇਕ ਮਜ਼ਬੂਤ SDK ਤਿੰਨ ਅਧੂਰੇ SDKs ਨਾਲੋਂ ਵਧੀਆ ਹੈ।
ਇੱਕ ਵਧੀਆ starter ਸੈੱਟ:
ਤੁਸੀਂ ਇਹ ਹੱਥੋਂ ਲਿਖ ਸਕਦੇ ਹੋ ਜਾਂ OpenAPI spec ਤੋਂ generate ਕਰ ਸਕਦੇ ਹੋ। ਜਨਰੇਸ਼ਨ ਵਧੀਆ ਹੁੰਦੀ ਹੈ ਜਦੋਂ ਤੁਹਾਡਾ spec ਸਹੀ ਹੋਵੇ ਅਤੇ ਤੁਸੀਂ consistent typing ਚਾਹੁੰਦੇ ਹੋ, ਪਰ ਇਹ ਅਕਸਰ ਬਹੁਤ ਕੋਡ ਪੈਦਾ ਕਰਦਾ ਹੈ। ਸ਼ੁਰੂ ਵਿਚ, ਇੱਕ ਹੱਥੋਂ ਲਿਖਿਆ minimal client ਨਾਂਲ OpenAPI ਫ਼ਾਈਲ docs ਲਈ ਕਾਫੀ ਹੈ। ਜੇ ਤਰੱਕੀ ਹੋਣੀ ਹੋਏ, ਤੁਸੀਂ generated clients 'ਤੇ ਬਾਆਉਂਟ ਹੋ ਸਕਦੇ ਹੋ ਜੇ ਪ੍ਰਭਾਵਤਕ public SDK interface ਸਥਿਰ ਰਹੇ।
ਤੁਹਾਡੀ API ਵਰਜ਼ਨ ਤੁਹਾਡੇ compatibility rules ਨੂੰ ਫੋਲੋ ਕਰੇ। ਤੁਹਾਡੀ SDK ਵਰਜ਼ਨ packaging ਨਿਯਮਾਂ ਨੂੰ ਫੋਲੋ ਕਰੇ।
ਜੇ ਤੁਸੀਂ ਨਵੇਂ optional parameters ਜਾਂ endpoint ਜੋੜਦੇ ਹੋ ਤਾਂ ਆਮ ਤੌਰ 'ਤੇ ਇਹ ਇੱਕ minor SDK ਬੁੰਪ ਹੁੰਦਾ ਹੈ। major SDK releases ਉਹਨਾਂ ਬਦਲਾਵਾਂ ਲਈ ਰੱਖੋ ਜੋ SDK ਖੁਦ ਵਿੱਚ breaking ਹਨ (ਨਾਮ ਬਦਲੇ ਗਏ methods, defaults ਬਦਲੇ), ਭਾਵੇਂ API ਇੱਕੋ ਹੀ ਰਿਹਾ। ਇਹ ਵੱਖਰਾ ਕਰਨ ਨਾਲ upgrades ਸ਼ਾਂਤ ਰਹਿੰਦੀਆਂ ਹਨ ਅਤੇ ਸਪੋਰਟ ਟਿਕਟਾਂ ਘੱਟ ਰਹਿੰਦੀਆਂ ਹਨ।
ਅਧਿਕਤਮ API ਸਪੋਰਟ ਟਿਕਟਾਂ bugs ਬਾਰੇ ਨਹੀਂ ਹੁੰਦੀਆਂ। ਉਹ ਅਚਾਨਕੀ ਬਦਲਾਅ ਬਾਰੇ ਹੁੰਦੀਆਂ ਹਨ। Public API ਡਿਜ਼ਾਈਨ ਮੁੱਖ ਤੌਰ 'ਤੇ ਬੋਰਿੰਗ ਅਤੇ ਪੂਰੇ ਤਰੀਕੇ ਨਾਲ predictable ਹੋਣ ਬਾਰੇ ਹੈ ਤਾਂ ਕਿ ਕਲਾਇੰਟ ਕੋਡ ਮਹੀਨਿਆਂ ਤੱਕ ਚੱਲਦਾ ਰਹੇ।
ਤੇਜ਼ੀ ਨਾਲੋਂ ਸਭ ਤੋਂ ਤੇਜ਼ੀ ਨਾਲ ਭਰੋਸਾ ਖੋਣ ਦਾ ਤਰੀਕਾ ਹੈ ਬਿਨਾਂ ਦੱਸੇ responses ਨੂੰ ਬਦਲਣਾ। ਜੇ ਤੁਸੀਂ ਇੱਕ ਫੀਲਡ ਦਾ ਨਾਮ ਬਦਲਦੇ ਹੋ, ਟਾਈਪ ਬਦਲਦੇ ਹੋ, ਜਾਂ ਕਿਸੇ ਥਾਂ null ਵਾਪਸ ਕਰਨਾ ਸ਼ੁਰੂ ਕਰ ਦਿੰਦੇ ਹੋ ਜਿੱਥੇ ਪਹਿਲਾਂ ਇੱਕ value ਹੁੰਦੀ ਸੀ, ਤੁਸੀਂ ਕਲਾਇੰਟ ਟੁੱਟਣਗੇ ਜੋ ਉਹਨਾਂ ਲਈ ਪਤਾ ਲਾਉਣਾ ਔਖਾ ਹੁੰਦਾ ਹੈ। ਜੇ ਤੁਹਾਨੂੰ ਸੱਚਮੁੱਚ ਵਰਤੈਵ ਬਦਲਣਾ ਹੋਵੇ, ਤਾਂ ਇਸਨੂੰ version ਕਰੋ, ਜਾਂ ਇੱਕ ਨਵਾਂ ਫੀਲਡ ਜੋੜੋ ਅਤੇ ਪੁਰਾਣੇ ਨੂੰ ਕੁਝ ਸਮੇਂ ਲਈ ਰੱਖੋ ਇੱਕ ਸਪਸ਼ਟ sunset ਯੋਜਨਾ ਨਾਲ।
Pagination ਵੀ ਇੱਕ ਆਮ ਮੁਸ਼ਕਲ ਹੈ। ਸਮੱਸਿਆ ਇਹ ਹੈ ਜਦੋਂ ਇਕ endpoint page/pageSize ਵਰਤਦਾ ਹੈ, ਦੂਜਾ offset/limit, ਅਤੇ ਤੀਜਾ cursors, ਸਭ ਵੱਖ-ਵੱਖ defaults ਨਾਲ। v1 ਲਈ ਇਕ ਪੈਟਰਨ ਚੁਣੋ ਅਤੇ ਹਰ ਥਾਂ ਇਸ 'ਤੇ टिकੇ ਰਹੋ। sorting ਨੂੰ ਵੀ ਸਥਿਰ ਰੱਖੋ, ਤਾਂ ਜੋ ਨੈਕਸਟ ਪੇਜ ਨਵੇਂ ਰਿਕਾਰਡ ਆਉਣ 'ਤੇ skip ਜਾਂ repeat ਨਾ ਕਰੇ।
Errors ਕਾਫ਼ੀ ਵਦੀਆਂ back-and-forth ਬਣਾਉਂਦੇ ਹਨ ਜਦੋਂ ਉਹ inconsistent ਹੁੰਦੇ ਹਨ। ਇੱਕ ਆਮ ਫੇਲ੍ਹ ਮੋਡ ਇਹ ਹੈ ਕਿ ਇੱਕ ਸੇਵਾ { "error":"..." } ਵਾਪਸ ਕਰਦੀ ਹੈ ਅਤੇ ਦੂਜੀ { "message":"..." }, ਅਤੇ ਸਮਾਨ ਮੁੱਦੇ ਲਈ ਵੱਖ-ਵੱਖ HTTP status codes। ਫਿਰ ਕਲਾਇੰਟ messy, endpoint-specific handlers ਬਣਾਉਂਦੇ ਹਨ।
ਇੱਥੇ ਪੰਜ غلطੀਆਂ ਹਨ ਜੋ ਸਭ ਤੋਂ ਲੰਬੇ email threads ਪੈਦਾ ਕਰਦੀਆਂ ਹਨ:
ਇੱਕ ਸਧਾਰਣ ਆਦਤ ਮਦਦ ਕਰਦੀ ਹੈ: ਹਰ ਰਿਸਪਾਂਸ ਵਿੱਚ request_id ਸ਼ਾਮਿਲ ਕਰੋ, ਅਤੇ ਹਰ 429 ਵਿੱਚ ਦੱਸੋ ਕਿ ਕਦੋਂ retry ਕਰਨਾ ਚਾਹੀਦਾ ਹੈ।
ਕਿਸੇ ਵੀ ਚੀਜ਼ ਨੂੰ ਪ੍ਰਕਾਸ਼ਿਤ ਕਰਨ ਤੋਂ ਪਹਿਲਾਂ consistency 'ਤੇ final pass ਕਰੋ। ਜ਼ਿਆਦਾਤਰ ਸਪੋਰਟ ਟਿਕਟਾਂ ਇਸ ਕਾਰਨ ਹੁੰਦੀਆਂ ਹਨ ਕਿ ਛੋਟੀ-ਛੋਟੀ ਚੀਜ਼ਾਂ endpoints, docs, ਅਤੇ examples ਵਿੱਚ ਮਿਲਦੀਆਂ ਨਹੀਂ।
ਉਹ Quick checks ਜੋ ਸਭ ਤੋਂ ਵੱਧ ਮੁੱਦੇ ਕੈਚ ਕਰਦੀਆਂ ਹਨ:
ਲਾਂਚ ਤੋਂ ਬਾਅਦ, ਲੋਕ ਅਸਲ ਵਿੱਚ ਕੀ ਹਿੱਟ ਕਰ ਰਹੇ ਹਨ ਉਸਨੂੰ ਦੇਖੋ, ਨਾ ਕਿ ਜੋ ਤੁਸੀਂ ਉਮੀਦ ਕਰਦੇ ਸੀ। ਪਹਿਲੇ ਦੌਰ ਵਿੱਚ ਇੱਕ ਛੋਟਾ dashboard ਅਤੇ ਹਫ਼ਤਾਵਾਰ ਸਮੀਖਿਆ ਕਾਫ਼ੀ ਹੈ।
ਇਹ signals ਪਹਿਲਾਂ ਮਾਨੀਟਰ ਕਰੋ:
ਫੀਡਬੈਕ ਇਕੱਠਾ ਕਰੋ ਬਿਨਾਂ ਸਭ ਕੁਝ ਦੁਬਾਰਾ ਲਿਖੇ। ਆਪਣੇ docs ਵਿੱਚ ਇੱਕ ਛੋਟਾ report an issue ਰਾਹ ਬਣਾਓ, ਅਤੇ ਹਰ ਰਿਪੋਰਟ ਨੂੰ endpoint, request id, ਅਤੇ client version ਨਾਲ ਟੈਗ ਕਰੋ। ਜਦੋਂ ਤੁਸੀਂ ਕੁਝ ਫਿਕਸ ਕਰੋ, ਤਾਂ additive changes ਨੂੰ ਤਰਜੀਹ ਦਿਓ: ਨਵੇਂ fields, ਨਵੇਂ optional params, ਜਾਂ ਨਵੇਂ endpoint, ਬਜਾਏ ਮੌਜੂਦਾ ਇਹ ਵਿਹਾਰ ਤੋੜਣ ਦੇ।
ਅਗਲੇ ਕਦਮ: ਆਪਣਾ resources, versioning plan, pagination rules, ਅਤੇ error format ਨਾਲ ਇਕ ਪੰਨਾ API spec ਲਿਖੋ। ਫਿਰ docs ਅਤੇ ਇਕ ਛੋਟਾ starter SDK ਬਣਾਓ ਜੋ authentication ਅਤੇ 2-3 core endpoints ਨੂੰ ਕਵਰ ਕਰੇ। ਜੇ ਤੁਸੀਂ ਤੇਜ਼ੀ ਨਾਲ ਅੱਗੇ ਵਧਣਾ ਚਾਹੁੰਦੇ ਹੋ, ਤਾਂ ਤੁਸੀਂ chat-based ਯੋਜਨਾ ਵਰਤ ਕੇ spec, docs, ਅਤੇ starter SDK draft ਕਰ ਸਕਦੇ ਹੋ—ਜਿਵੇਂ Koder.ai ਦੀ planning mode endpoints ਅਤੇ examples ਨੂੰ map ਕਰਨ ਲਈ ਇਕ ਸਹਾਇਕ ਤਰੀਕਾ ਹੈ।
Start with 5–10 endpoints that map to real customer actions.
A good rule: if you can’t explain a resource in one sentence (what it is, who owns it, how it’s used), keep it private until you learn more from usage.
Pick a small set of stable nouns (resources) customers already use in conversation, and keep those names stable even if your database changes.
Common starters for SaaS are users, organizations, projects, and events—then add more only when there’s clear demand.
Use the standard meanings and be consistent:
GET = read (no side effects)POST = create or start an actionPATCH = partial updateDELETE = remove or disableThe main win is predictability: clients shouldn’t guess what a method does.
Default to URL versioning like /v1/....
It’s easier to see in logs and screenshots, easier to debug with customers, and simpler to run v1 and v2 side by side when you need a breaking change.
A change is breaking if a correct client can fail without changing their code. Common examples:
Adding a new optional field is usually safe.
Keep it simple:
A practical default is a 90-day window for a first API, so customers have time to migrate without panic.
Pick one pattern and stick to it across all list endpoints.
Always define a default sort and a tie-breaker (like created_at + ) so results don’t jump around.
Start with a clear per-key limit (for example 60 requests/minute plus a small burst), then adjust based on real traffic.
When limiting, return 429 and include:
X-RateLimit-LimitX-RateLimit-RemainingUse one error format everywhere (including 500s). A practical shape is:
code (stable identifier)message (human-readable)details (field-level issues)request_id (for support)Also keep status codes consistent (400/401/403/404/409/429/500) so clients can handle errors cleanly.
If you generate lots of endpoints quickly (for example with Koder.ai), keep the public surface small and treat it as a long-term contract.
Do this before launch:
POST actionsThen publish a tiny SDK that helps with auth, timeouts, retries for safe requests, and pagination—without hiding how the HTTP API works.
idX-RateLimit-ResetRetry-AfterThis makes retries predictable and reduces support tickets.