في هذه الصفحة
المقدمة
قبل ما ندخل في تفاصيل الـ API documentation، خليني أوضح بسرعة إيه هي الـ API ووظيفتها. الـ API هي اختصار لـ Application Programming Interface. سواء كنت مبرمج مبتدئ أو متمرس، هتقابل المصطلح ده كتير خلال رحلتك في تطوير البرمجيات.
الـ API هي الجسر اللي بيربط بين جهاز الكمبيوتر، الموبايل، أو التطبيق بتاعك وبين موارد خارجية زي قواعد بيانات أو خدمات أخرى. يعني ببساطة، الـ APIs بتدي برامجك القدرة إنها تتفاعل مع برامج أو قواعد بيانات تانية. بدل ما تكتب كود كامل لميزة معينة في تطبيقك، ممكن تستخدم API متاحة بالفعل للميزة دي.
فيه APIs متاحة ببلاش، وفيه اللي لازم تدفع عشان تحصل على مفتاح خاص (Private Key) يسمح لك بالوصول ليها. وفيه أنواع مختلفة زي REST وSOAP وغيرهم.
Alaa Elkzaz
APIs In a Nutshell
إيه هي API Documentation
الـ API documentation بقى هي دليل مكتوب بيوضح وظائف الـ API، إزاي تدمجها في برنامجك، وحالات الاستخدام بتاعتها، مع شوية أمثلة. افتكر إن الـ API documentation بتكون محتوى تقني، يعني هيبقى فيها مصطلحات فنية، لكن المفروض إنها تكون سهلة القراءة والفهم.
الـ Documentation بتبقى زي الخريطة لأي مبرمج عاوز يستخدم الـ API بتاعتك. من غيرها، اللي هيجرب يشتغل بالـ API مش هيفهم أي حاجة وممكن يضيع وقت كتير يحاول يفهم بنفسه. لما يكون عندك Documentation كويسة، المطورين يقدروا يفهموا بسرعة إيه اللي لازم يتعمل، إيه اللي هيجيلهم من الـ API، وإيه اللي المفروض يبعتوه. ده بيقلل الأخطاء وبيسرع الشغل.
ليه الـ API Documentation مهمة
كمان لما الـ API Documentation تبقى مكتوبة بشكل واضح ومنظم، بتساعد إن اللي بيستخدم الـ API ميضيعش وقت كتير في الاستفسارات أو البحث عن حلول للمشاكل اللي قابلها. ده بيسهل الأمور وبيسرع عملية التطوير، وده بيزود فرصة إن ناس أكتر تستخدم الـ API بتاعتك، وده طبعًا في مصلحتك كمطور أو شركة.
مين المفروض يكتب API Documentation؟
الـ APIs بيطورها مبرمجين البرمجيات. وبما إنهم هما اللي بيبنوها وبيستخدموها، بيكون أسهل لهم إنهم يكتبوا الوثائق بتاعتها. لكن المشكلة إن المبرمجين ساعات بيكتبوا الوثائق بشكل فني بحت، وده بيخلي الوثائق صعبة الفهم على ناس كتير. وكمان ممكن ياخد منهم وقت طويل عشان يطوروا الـ API ويكتبوا الوثائق في نفس الوقت.
عشان كده الحل الأفضل إن اللي يكتب الوثائق يكون Technical Writer. الـ Technical Writer هو شخص بيجمع بين مهارات الكتابة التقنية والمعرفة التقنية عشان ينتج وثائق تكون مفهومة وسهلة.
الـ Technical Writer بيتعلم عن الـ API من المطورين، وبعدين بيكتب دروس وأمثلة تشرح استخدام الـ API. المطورين بعد كده بيتابعوا الكاتب عشان يتأكدوا إن الوثائق صحيحة وبيزودوه بأي معلومات إضافية لو احتاج.
الهدف النهائي إن الكل يشتغل سوا عشان يطلع وثائق بتشرح الـ API بشكل واضح وتساعد المستخدمين من غير لخبطه.
محتويات الـ API Documentation
محتويات الـ API Documentation بتكون متقسمة لأجزاء أساسية، وكل جزء بيشرح نقطة معينة بتساعد المبرمجين يفهموا إزاي يستخدموا الـ API بشكل صحيح. تعالوا نشوف أهم الحاجات اللي بتكون موجودة:
1- Introduction
ده القسم اللي بيشرح فكرة الـ API بشكل عام. بتوضح الغرض منها، وإيه الحاجات اللي بتعملها أو بتحلها. بتدي نبذة عن إمكانيات الـ API واللي ممكن تستفيده منها. (هنا تقدر تضيف إزاي الـ API دي هتساعد الشركات أو الأفراد في تحقيق أهدافهم.)
2- Authentication
هنا بتشرح إزاي المبرمجين يقدروا يوصلوا للـ API، يعني إيه الطرق اللي يقدروا يستخدموها عشان يحصلوا على صلاحيات ويستخدموا الـ API. أغلب الوقت بتكون عن طريق مفاتيح API Keys أو الـ OAuth.
3- Headers
الـ Headers هي بيانات إضافية بتتبعت مع كل طلب للـ API عشان تحدد معلومات معينة زي نوع البيانات اللي عاوز تستقبلها أو تبعتها. أحياناً بيكون لازم تبعت بيانات زي الـ Authentication Token في الـ Header عشان توصل للـ API. فيه أنواع مختلفة من الـ Headers زي:
- Authorization: عشان تبعت الـ Token أو الـ API Key اللي يثبت إنك ليك صلاحية.
- Content-Type: عشان تحدد نوع البيانات اللي بتبعتها (زي JSON أو XML).
- Accept: عشان تحدد نوع البيانات اللي عاوز تستقبلها.
4- Endpoints
الجزء ده بيكون قلب الـ Documentation. هنا بنلاقي الـ URLs اللي بتستخدمها عشان تتواصل مع الـ API، زي ما تقول دي العناوين اللي البرنامج بيروح لها عشان يطلب بيانات أو يبعت حاجة.
5- Request Methods
دي بتوضح الطرق المختلفة للتعامل مع الـ API، زي:
- GET: بتستخدمها عشان تسحب بيانات.
- POST: عشان تبعت بيانات جديدة.
- PUT: عشان تحدث بيانات موجودة.
- DELETE: عشان تمسح حاجة.
6- Parameters
أحياناً بتحتاج تبعت حاجات معينة مع الـ request زي ID بتاع حاجة معينة أو نوع البيانات اللي عاوزها. هنا بيشرح إيه الحاجات دي وإزاي تبعتها مع الطلب بتاعك.
7- Responses
هنا بيتم شرح إزاي الـ API هترد على الطلبات اللي بتعملها. بتشوف أمثلة على الردود اللي ممكن توصل، سواء كانت البيانات اللي طلبتها أو لو فيه خطأ حصل. (لازم يكون فيه أمثلة حقيقية لردود الـ API، بحيث المطور يعرف يتوقع الرد المناسب.)
8- Error Codes
هنا بيتم شرح الأخطاء اللي ممكن تحصل وإيه معناها. الـ API ساعات بترجع أكواد زي:
- 404: معناها إن الحاجة اللي طلبتها مش موجودة.
- 401: معناها إنك مش عندك صلاحيات كافية.
9- Examples
بيكون في أمثلة عملية لاستخدام الـ API عشان تسهل على المطورين وتوريهم إزاي يبعتوا الطلبات ويستلموا الردود بشكل عملي.
10 - Rate Limiting
ده بيشرح العدد الأقصى للطلبات اللي ممكن تعملها في وقت معين عشان تمنع استهلاك مفرط أو سوء استخدام للـ API.
تقدروا دلوقتي تشتركوا في النشرة الأسبوعية لاقرأ-تِك بشكل مجاني تمامًا عشان يجيلكوا كل جديد بشكل أسبوعي فيما يخص مواضيع متنوعة وبشروحات بسيطة وسهلة وبجودة عالية 🚀
النشرة هيكون ليها شكل جديد ومختلف عن شكلها القديم وهنحاول انها تكون مميزة ومختلفة وخليط بين المحتوى الأساسي اللي بينزل ومفاجآت تانية كتير 🎉
Eqraatech - اقرأ-تِك
بفضل الله قمنا بإطلاق قناة اقرأ-تِك على التليجرام مجانًا للجميع 🚀
آملين بده اننا نفتح باب تاني لتحقيق رؤيتنا نحو إثراء المحتوى التقني باللغة العربية ، ومساعدة لكل متابعينا في انهم يوصلوا لجميع أخبار اقرأ-تِك من حيث المقالات ومحتوى ورقة وقلم والنشرة الأسبوعية وكل جديد بطريقة سريعة وسهلة
مستنينكوا تنورونا , وده رابط القناة 👇
إزاي تكتب توثيق API مفيد؟
- اعرف الـ API كويس قبل ما تكتب عنها.
- خلي الشرح سهل ومباشر بحيث إن أي شخص، سواء مبتدئ أو محترف، يقدر يفهم التوثيق.
- خليك واضح حتى لو بتستخدم مصطلحات تقنية.
- استخدم خطوات مرقمة أو معلمة للتوضيح.
- اتأكد من مراجعة الوثيقة قبل النشر عشان تكون خالية من الأخطاء
- قدم حلول للمشاكل اللي ممكن يقابلها المطورين عند استخدام الـ API، زي تقديم إرشادات لتفادي أخطاء شائعة أو توضيح كيفية التصرف مع الـ Error Codes.
أدوات مشهورة لكتابة API Documentation
- Postman: أداة بتسهل عملية كتابة الوثائق بشكل كبير، وسهلة الاستخدام.
- DapperDox: بيدعم Markdown ومفتوح المصدر، وبيسهل الكتابة والتحديث.
- SwaggerHub: بيستخدم كتير بسبب واجهته التفاعلية والخيارات السهلة المتاحة.
وأخيرًا، حافظ على التوثيق محدث باستمرار
محدش بيحب توثيق قديم، خلي دايمًا التوثيق محدث مع أي تغييرات أو تحسينات في الـ API. لو بتستخدم أدوات زي DapperDox أو Redocly، ده هيساعدك في تحديث الوثائق تلقائيًا. لكن برضو لازم يكون عندك خطة للصيانة والتحديثات الدورية، وتحدد شخص يكون مسؤول عن مراجعة التوثيق وتحديثه مع أي تطويرات جديدة.
API Documentation Template
ممكن كبدايه تستخدم ال API Documentation Template الموجود هنا:
📄 Overview
Provide a brief description of what the API does and the problems it solves. Include any relevant background information that can help stakeholders understand the purpose and scope of the API
🎯 Importance
Explain the importance of this API and the main screens where this API is used, with a focus on its significance within our apps
⏱ Rate Limits
- Logged-in Users:
- Non-logged-in Users:
🦸🏽 API Usage
📍Endpoint
- HTTP Method:
- URL:
🔑 Headers
🗂️ Query Parameters
🔍 Request Body
📦Code Examples
Provide code examples in one popular programming language to help your peers understand how to interact with the API.
Response Body
Error Codes
🚫 List and describe common error responses that the API might return, including HTTP status codes. This helps developers handle errors effectively in their applications
Example:
- 400 Bad Request - The request was unacceptable, often due to missing a required parameter.
- 401 Unauthorized - No valid API key provided.
- 404 Not Found - The requested resource doesn't exist.
- 500 Internal Server Error - We had a problem with our server. Try again later.
📝 Change Log
Maintain a log of all changes, updates, and deprecations to the API to keep users informed about the evolution of the API
FAQ 🤔
Address frequently asked questions to help quickly resolve common issues or confusions
