Lesson 16 / الدرس 16

What an API is / ما واجهة البرمجة

A way for one program to ask another for something, over the same HTTP your browser already speaks. Once you see that a REST API is just a website that answers in JSON instead of HTML, most of the mystery goes.

طريقة يطلب بها برنامج شيئًا من آخر، عبر HTTP نفسه الذي يتكلمه متصفحك أصلًا. وما إن ترى أن واجهة REST موقع يجيب بـJSON بدل HTML حتى يذهب أكثر الغموض.

The same request, a different answer

a browser asks         GET /bookings/1        and gets HTML to draw
a program asks         GET /api/bookings/1    and gets JSON to use

same protocol, same server, same URL shape — only the representation differs

resource   the THING            a booking, a room, a guest
endpoint   the ADDRESS of it    /api/bookings/1
method     what you want done   GET, POST, PATCH, DELETE

The demonstration is a tiny server in the page. It holds three bookings, answers the same set of URLs a real one would, and prints every request and response in full so you can see the shape of the conversation. Press the buttons in order.

Why anyone bothers

A server that only returns HTML can be used by exactly one kind of client: a browser showing pages. The moment the guest house wants a phone app, a partner site listing its rooms, or a nightly report emailed to the owner, that HTML is in the way — every one of them would have to pull the numbers back out of the markup. An API separates what the system knows from how it happens to be displayed, and once separated, the same server serves the website, the app and the report without knowing which is asking.

Word	Means	Example
Resource	A thing the system knows about	A booking
Collection	All of them	/api/bookings
Endpoint	One addressable URL	/api/bookings/1
Client	Whoever is asking	A browser, an app, another server
Payload / body	The data carried with a request or answer	The JSON
REST	A style: resources as URLs, methods as verbs	Not a technology or a library

REST is the last row and the most misused word here. It is a set of conventions about naming and behaviour, not something you install — which is why two REST APIs can look quite different and both be correct, and why "is this RESTful?" is usually a less useful question than "is this predictable?".

والواجهة وعد عليك الوفاء به. ففي اللحظة التي تعتمد فيها شيفرة غيرك على booking.guest، تكسر إعادةُ تسمية ذلك الحقل إلى booking.guest_name تطبيقَهم في يوم لم تكن تفكر فيهم — وخلافًا لصفحاتك أنت، لا تستطيع إصلاح شيفرتهم بالالتزام نفسه. ولهذا تحمل الواجهات إصدارات في العنوان (/api/v1/bookings)، ولهذا تكون إضافة حقل آمنة وحذفه ليس كذلك، ولهذا يستحق شكل جوابك الأول ساعة تفكير لا خمس دقائق.

Look again at the stand-in server: it is one function that takes a method and a path and returns a status, a content type and a body. A real framework adds routing, database access, authentication and a hundred other things, and underneath all of them it is still that function. Holding that picture makes the rest of this section — methods, status codes, headers, tokens — feel like details of a shape you already understand, rather than a pile of unrelated facts.

ولديك عميل واجهة أصلًا: المتصفح. اكتب عنوان أي واجهة عامة في شريط العنوان فتحصل على JSON منسَّقًا في لسان تستطيع البحث فيه. جرّب https://api.github.com/users/torvalds. وفعل ذلك قبل كتابة أي شيفرة يخبرك بأسماء الحقول وأشكالها بالضبط، ويوفّر نصف ساعة كانت ستُنفق في طباعة أشياء من داخل fetch.

Try it live / جرّب بنفسك

<button id="go">GET /api/rooms</button>
<pre id="out"></pre>

<script>
  const rooms = [{ id: 1, name: 'Palm', price_per_night: 400 }];

  function server(method, path) {
    if (path === '/api/rooms') {
      return { status: 200, body: rooms };
    }
    return { status: 404, body: { error: 'Not found' } };
  }

  document.getElementById('go').addEventListener('click', function () {
    const res = server('GET', '/api/rooms');
    document.getElementById('out').textContent =
      res.status + '\n' + JSON.stringify(res.body, null, 2);
  });
</script>

Preview / المعاينة

Check yourself / اختبر نفسك

1. What is the difference between /bookings/1 and /api/bookings/1?

ما الفرق بين /bookings/1 و/api/bookings/1؟

2. Why do APIs carry a version in the URL?

3. What is REST?

Your task / مهمتك

Open three public APIs in your browser's address bar and study the JSON each returns — GitHub, a weather service and one of your own choosing. For each, write down the resource, the endpoint pattern, three field names and one thing about the shape you did not expect. Then design the endpoints for a system of your own on paper: list the resources, the URL for the collection and for one item, and the exact JSON one item would return. Extend the stand-in server here to answer two of your own endpoints.

افتح ثلاث واجهات عامة في شريط عنوان متصفحك وادرس JSON الذي تعيده كل واحدة — GitHub وخدمة طقس وواحدة من اختيارك. واكتب لكل واحدة المورد ونمط العنوان وثلاثة أسماء حقول وشيئًا في الشكل لم تتوقعه. ثم صمّم على ورق نقاط نظامك أنت: عدّد الموارد، وعنوان المجموعة وعنوان العنصر الواحد، وJSON الذي سيعيده عنصر واحد بالضبط. ووسّع الخادم البديل هنا ليجيب نقطتين من عندك.

Three real APIs examined, with their shapes noted ثلاث واجهات حقيقية مفحوصة بأشكالها مدوَّنة
One surprise per API written down مفاجأة واحدة لكل واجهة مكتوبة
Your own resources and endpoint patterns designed مواردك وأنماط نقاطك مصمَّمة
Two of your endpoints answering in the stand-in server نقطتان من عندك تجيبان في الخادم البديل