𝐓𝐡𝐢𝐬 𝐀𝐏𝐈 𝐢𝐬 𝐚 𝐧𝐢𝐠𝐡𝐭𝐦𝐚𝐫𝐞, 𝐇𝐨𝐰 𝐝𝐢𝐝 𝐭𝐡𝐢𝐬 𝐞𝐯𝐞𝐫 𝐠𝐞𝐭 𝐬𝐡𝐢𝐩𝐩𝐞𝐝?

"𝐓𝐡𝐢𝐬 𝐀𝐏𝐈 𝐢𝐬 𝐚 𝐧𝐢𝐠𝐡𝐭𝐦𝐚𝐫𝐞, 𝐇𝐨𝐰 𝐝𝐢𝐝 𝐭𝐡𝐢𝐬 𝐞𝐯𝐞𝐫 𝐠𝐞𝐭 𝐬𝐡𝐢𝐩𝐩𝐞𝐝?" - Edy’s reaction while staring at the API documentation.

No one likes this kind of feedback. What should be done so that developers like Edy advocate for the API? Or, what does it take to ship and maintain a robust REST API, one that other developers will love using?

𝐇𝐞𝐫𝐞 𝐚𝐫𝐞 𝐬𝐨𝐦𝐞 𝐨𝐟 𝐭𝐡𝐞 𝐩𝐨𝐢𝐧𝐭𝐬 𝐚𝐧𝐝 𝐛𝐞𝐬𝐭 𝐩𝐫𝐚𝐜𝐭𝐢𝐜𝐞𝐬 𝐭𝐡𝐚𝐭 𝐈 𝐡𝐚𝐯𝐞 𝐠𝐚𝐭𝐡𝐞𝐫𝐞𝐝 𝐟𝐫𝐨𝐦 𝐭𝐡𝐞 𝐜𝐨𝐦𝐦𝐮𝐧𝐢𝐭𝐲:

1. 𝗦𝘁𝗿𝘂𝗰𝘁𝘂𝗿𝗶𝗻𝗴 𝗮𝗻𝗱 𝗻𝗮𝗺𝗶𝗻𝗴 𝗔𝗣𝗜 𝗲𝗻𝗱𝗽𝗼𝗶𝗻𝘁𝘀: A good API has a well thought out and logical design of endpoints. 🔗

2. 𝗖𝗼𝗺𝗽𝗿𝗲𝗵𝗲𝗻𝘀𝗶𝘃𝗲 𝗗𝗼𝗰𝘂𝗺𝗲𝗻𝘁𝗮𝘁𝗶𝗼𝗻: Bad documentation will throw developers away. A good API makes sure the documentation is clear and follows industry standards. Eg. OpenAI Specifications.🌐

3. 𝗜𝗻𝗽𝘂𝘁 𝗩𝗮𝗹𝗶𝗱𝗮𝘁𝗶𝗼𝐧: A good API meticulously validates user input and provides detailed and structured error messages when an invalid input is received. ❌

4. 𝐑𝐚𝐭𝐞 𝐥𝐢𝐦𝐢𝐭𝐢𝐧𝐠: A good API employs rate limiting to prevent overloading and ensure quality of service for all clients. ⌛

5. 𝐀𝐬𝐲𝐧𝐜𝐡𝐫𝐨𝐧𝐨𝐮𝐬 𝐩𝐫𝐨𝐜𝐞𝐬𝐬𝐢𝐧𝐠: A good API performs longer running tasks in the background using a task queue and worker system and avoids keeping client connections open for extended periods.🔄

6. 𝐌𝐨𝐧𝐢𝐭𝐨𝐫𝐢𝐧𝐠 𝐚𝐧𝐝 𝐨𝐛𝐬𝐞𝐫𝐯𝐚𝐛𝐢𝐥𝐢𝐭𝐲: Maintaining a robust API requires proactive monitoring, so you can take action immediately if there are problems - ideally before they impact consumers. 🔎

𝐄𝐝𝐲 𝐡𝐚𝐭𝐞𝐬 𝐛𝐚𝐝 𝐀𝐏𝐈 𝐝𝐨𝐜𝐮𝐦𝐞𝐧𝐭𝐚𝐭𝐢𝐨𝐧. What are YOUR red flags that can make an API frustrating to work with?