انتقل إلى المحتوى
أمين أبوزيد
Englishالعربية
منشورBEG-053-L06

عرض عملي: استكشاف API عامة باستخدام Postman وcurl

  • الدرس 6 من 6
  • 10 دقيقة قراءة
  • مبتدئ
في هذا الدرس 11 موضوعات

هذا الدرس متاح حاليًا باللغة الإنجليزية فقط، ولم تُنشر نسخته العربية بعد.

Lesson Overview

This is the hands-on lesson that ties the module together. You will follow one complete exploration of a real public API, step by step: read the documentation, call a list, a single item, and a filtered query, make a planned mistake and fix it, repeat a call with curl -i, and save a Postman collection. It prepares the lab, API explorer, where you do all of this on your own and then sketch a Library API.

In the restaurant picture, you are a new guest with a printed menu (the docs), trying a few dishes, once by sitting at the practice table (Postman) and once by phone (curl), and noticing what happens when you misspell a dish.

We use DummyJSON, a free practice API that needs no sign-up and documents a products resource. Public services can change or disappear, so if this one is unavailable or behaves differently when you try it, pick another documented API with a list endpoint and follow the same steps; the method matters more than the site. Menus and button names in Postman differ between versions, so this lesson describes steps by purpose.

This lesson builds on all earlier lessons of this module.

Learning Objectives

By the end of this lesson you will be able to:

  • Find the list, single-item, search, and filter endpoints of an API in its documentation.
  • Call a list, a single item, and a filtered query with Postman and with curl.
  • Compare a Postman response with a curl -i response of the same request.
  • Recognize a wrong-path 404 and fix it by rereading the documentation.
  • Organize requests into a named Postman collection and export it.
  • Turn what you learned into a first endpoint sketch for a different resource.

Written Explanation

Step 1: Pick an API and read the docs

Choose an API that has documentation, a list endpoint, and needs no credentials. Verify it works before you rely on it. Then read the docs before sending anything. The DummyJSON products documentation lists, among others:

PurposeEndpoint from the docs
List productsGET /products
One productGET /products/{id}
SearchGET /products/search?q=...
PagingGET /products?limit=...&skip=...
Pick fieldsselect=title,price
SortsortBy and order
Category listGET /products/category-list
By categoryGET /products/category/{slug}

It also documents the write endpoints (POST /products/add, PUT or PATCH /products/{id}, DELETE /products/{id}) and says they only simulate the operation without changing the server. That note is exactly the kind of fact you only learn by reading.

Look for the same things in any API's docs: the base URL, the endpoints, the parameters, an example response, and notes about limits or authentication.

Step 2: Set up Postman

  1. Create a collection named "API explorer".
  2. Add a collection variable baseUrl with the value https://dummyjson.com.
  3. Add requests one by one, naming each clearly, and saving it into the collection.

Step 3: Three kinds of calls

You need one of each:

  • List: GET {{baseUrl}}/products with limit = 3 and select = title,price in the Params tab.
  • Single item: GET {{baseUrl}}/products/1 (with select if you want a short answer).
  • Filtered query: either a category ({{baseUrl}}/products/category/laptops) or a search ({{baseUrl}}/products/search?q=phone).

For each: check the status line first, then the body. Notice that the list answer is wrapped in an object (products, total, skip, limit), while the single item is a bare object. APIs often wrap lists to carry paging information.

Step 4: The planned mistake

Mistakes are normal, and a 404 is a clue, not a failure. Send GET {{baseUrl}}/produkts. Status: 404 Not Found. The body is an HTML page rather than JSON: the API did not recognize the path at all. The fix is to reread the documentation, find the correct path (/products), and resend.

A different 404: GET {{baseUrl}}/products/99999. The path is correct, the item does not exist, and this API answers with a JSON message. Same status, different cause, different body. The documentation and the body together tell you which.

Step 5: Repeat one call with curl -i

Pick one of your calls and run its curl twin with -i. Compare to Postman: same status, same body, same headers (Postman shows them in the response Headers tab). Notice headers you did not ask for. For example, the real responses we saw included headers whose names begin with x-ratelimit; names like this usually describe usage limits, but check the API's documentation rather than guessing what they mean. Treat limits as a reason to avoid sending hundreds of requests in a loop to a free service.

Step 6: Save and export the collection

Save every request. Then export the collection as a JSON file from the collection's actions menu (the exact label varies by Postman version). Open the exported file in a text editor and look at it: it is plain JSON listing your requests. Check it for secrets before sharing. This one holds none, since the API needs no credentials.

Step 7: Sketch what you learned

The last step of the lab moves from using to designing. Using what you learned, sketch the endpoints a Library API needs: for books, members, and loans, give URL, method, and statuses; add "loans of one member" and "overdue loans". Lesson 5 shows the method and the checklist.

Examples

Example 1: Simple. List and single item with curl

bash
curl -s "https://dummyjson.com/products?limit=3&select=title,price"
curl -s "https://dummyjson.com/products/1?select=title,price"

Real output:

json
{"products":[{"id":1,"title":"Essence Mascara Lash Princess","price":9.99},{"id":2,"title":"Eyeshadow Palette with Mirror","price":19.99},{"id":3,"title":"Powder Canister","price":14.99}],"total":194,"skip":0,"limit":3}
{"id":1,"title":"Essence Mascara Lash Princess","price":9.99}

The item from the list (id 1) and the single-item call agree. In both, the field total of the list (194 at the time of writing) says the API holds many more products than the three shown.

Example 2: Practical. A filtered query and a category list

bash
curl -s "https://dummyjson.com/products/category/laptops?limit=2&select=title"
curl -s "https://dummyjson.com/products/category-list" | head -c 150

Real output (the second is cut at 150 characters):

json
{"products":[{"id":78,"title":"Apple MacBook Pro 14 Inch Space Grey"},{"id":79,"title":"Asus Zenbook Pro Dual Screen Laptop"}],"total":5,"skip":0,"limit":2}
["beauty","fragrances","furniture","groceries","home-decoration","kitchen-accessories","laptops","mens-shirts","mens-shoes","mens-watches","mobile-acc

Reading the docs paid off: the category list gives the valid {slug} values, and laptops is one of them. total is 5, so two of five were shown.

The category filter here is a path (/products/category/laptops), not a query parameter. Real APIs do not all follow the plural-noun-plus-query habit from Lesson 2. This one offers both a path form for categories and a query form for limit and select. When you design your own API, prefer the query form for filters (Lesson 5), and when you use someone else's, follow their docs.

Example 3: Realistic. The planned 404, with curl -i

bash
curl -s -i "https://dummyjson.com/produkts" | head -n 1
curl -s -i "https://dummyjson.com/products/99999" | head -n 1
curl -s "https://dummyjson.com/products/99999"

Real output:

text
HTTP/1.1 404 Not Found
HTTP/1.1 404 Not Found
{"message":"Product with id '99999' not found"}

Both are 404. The first is a wrong path; the second is a missing item. Only the body (HTML versus a JSON message) tells them apart, which is why you read the status first and then the body.

A smaller surprise from the same session: GET /product/1 (singular) also returned 200 in our test, while /produkts did not. So this API accepts a singular alias for one route. Do not copy that habit into your own design: pick one form and keep it, as Lesson 2 advised.

Backend Insight

Exploring an unfamiliar API this way is a daily activity: when you integrate a payment provider, a mapping service, or another team's service, you first read the docs, then call the list, a single item, and a filter in a tool, then save those calls as a collection and keep it next to your project. The collection is a safe sandbox for questions like "what does it return when the id is wrong?" before you write Java code that must handle the answer.

The reverse is just as valuable. After you build your own API in the Junior level, you hand your collection to a teammate as living documentation, and the statuses from your endpoint sketch become the expected results you check with each call.

Common Mistakes

  • Skipping the documentation and guessing paths. Guesses give 404s that waste time.
  • Reading only the body. Check the status code first.
  • Assuming all APIs follow the same pattern. DummyJSON uses a path for categories and also accepts a singular alias; other APIs differ. The docs are the authority.
  • Treating a practice API's write calls as real. DummyJSON documents that add, update, and delete only simulate.
  • Hammering a free service with many rapid requests.
  • Exporting a collection containing secrets. Tokens and passwords belong in variables or a vault, not in shared files; this module needs none.
  • Verbs in your own endpoint sketch, after all that practice with other people's URLs.

Exercises

Level A: Foundation

  1. List the six things to look for when you open an API's documentation for the first time.
  2. Which of these calls is the list, the single item, and the filtered query? GET /products/5, GET /products?limit=4, GET /products/search?q=milk.
  3. What did the planned mistake teach about 404 responses?

Level B: Application

  1. In Postman, build and save the three calls from Step 3 in a collection with a baseUrl variable. Write the status you see on each one.
  2. Run the curl -i twin of your single-item call. In two lines, say what is the same as in Postman and what you can see in curl that you did not look at in Postman.
  3. Call GET /products/categories and GET /products/category-list (both documented) with curl -s ... | head -c 200. Say how the two answers differ in shape, and why a category list is useful before a filtered call.

Level C: Challenge

  1. Choose a second public API of your own (documented, no sign-up). Verify it works, then repeat the list, single-item, filter, and 404 steps. Write down one thing it does differently from DummyJSON.
  2. Do the lab's last step: sketch the Library API (books, members, loans) with URL, method, and success and failure statuses, plus "loans of one member" and "overdue loans". Then review your own sketch with the Lesson 5 checklist and write down any change you made.
أظهر الحلول
  1. The base URL, the list of endpoints, the parameters for each, an example response, notes about limits, notes about authentication. (A note that writes are simulated is also valuable.)
  2. List: GET /products?limit=4. Single item: GET /products/5. Filtered query: GET /products/search?q=milk.
  3. A 404 can mean a wrong path or a missing item. The status is the same; the body and the docs tell them apart. Read the docs to correct a wrong path.
  4. Expect 200 OK for all three. Your collection should contain three clearly named requests using {{baseUrl}}.
  5. Same: status, body, Content-Type. Visible in curl -i at once: the complete header block, including headers you may not have opened in Postman (for example those beginning with x-ratelimit).
  6. /products/categories returns a list of objects (with slug, name, url); /products/category-list returns just a list of slugs. The slugs are the valid values for /products/category/{slug}, so listing first avoids guessing and 404s.
  7. Open-ended. A good answer names the second API, shows its list, single, filter, and 404 behavior with statuses, and names a difference such as list wrapping, parameter names, or the body of a 404.
  8. A sketch following the Lesson 5 Library API: GET /books, GET /books/{id}, POST /books, PUT /books/{id}, DELETE /books/{id}, the same for /members, plus GET /members/{id}/loans and GET /loans?status=overdue, with 200/201/204/400/404 as appropriate. The review should find no verbs, plural nouns, and statuses on every line.

Mini Challenge

Write a one-page "API explorer report" for the lab: the API you used (name and base URL), the three calls with their statuses, the planned mistake and how the docs fixed it, one thing that surprised you, and the file name of your exported collection. Add your Library API sketch as the last section. This is exactly what a reviewer needs to mark the lab.

Summary & Next Lesson

Key takeaways

  • Read the docs first: base URL, endpoints, parameters, notes about limits and simulated writes.
  • Make three kinds of calls: list, single item, filtered query.
  • Check the status, then the body. A 404 can be a wrong path or a missing item.
  • curl -i shows what Postman shows: status, headers, body.
  • Save requests in a named collection with a baseUrl variable, then export it, after checking for secrets.
  • Every API has its own conventions; the documentation decides.

Next lesson

This was the last lesson of the module. Finish the lab "API explorer" (collection exported, endpoint sketch reviewed) and the module quiz. The next module in the course plan is BEG-054, whose first lesson is "Why build tools".

Self-check

  1. Which part of an API's documentation tells you what to put after the base URL?
  2. What is the difference between a list and a single-item response in this API?
  3. A call returns 404 with an HTML body. What does that suggest?
  4. Name two things to check before sharing an exported collection.
  5. Why prefer GET /loans?status=overdue over GET /getOverdueLoans in your own design?
أظهر الإجابات
  1. The endpoint list (paths with methods).
  2. The list is wrapped in an object with products, total, skip, and limit; the single item is a bare object.
  3. Probably a wrong path that the API did not recognize at all. Check the docs.
  4. That it contains no secrets (tokens, passwords) and that requests have clear names.
  5. It has no verb, keeps one collection URL, and extra filters need no new endpoint.

References

  • DummyJSON, Products documentation. Lists the endpoints in the Step 1 table, the limit, skip, select, and sort parameters, and states that add, update, and delete only simulate the operation. All outputs were produced by running the commands with curl on the day of writing; the service's data and behavior may change.
  • Postman Docs, Request basics, Variables, and Export data from Postman. Support building and saving requests, {{variable}} use, and the export route; menu labels vary by version, and Postman itself was not run for this lesson.
  • curl project, curl man page. Supports -i/--show-headers and -s.
  • Mozilla Developer Network, 404 Not Found. Supports the meaning of 404 (the server cannot find the requested resource).
  • Not verified: what the x-ratelimit headers exactly mean for this service. The text says only that names like this usually describe limits and asks the reader to check the documentation. The next module title (BEG-054, "Why build tools") is taken from the course spec, not from any outside source.

التطبيق

طبّق هذا الدرس بمختبر الوحدة وتمارينها واختبارها.

المختبر والتمارين الاختبار

تعليم الدرس كمكتمل اختياري ويمكنك التراجع عنه في أي وقت. يبقى تقدمك محفوظًا في هذا المتصفح.

تابع إلى تدريب الوحدة

اكتب للبحث في المستويات والمراحل والوحدات والدروس.