DHIVA LABS · LEARN

Appearance

What is an API? ​

An API is how one program asks another program to do something. By the end of this page you will know the handful of words that every API guide assumes: client, server, request, response and endpoint.

The restaurant picture ​

You sit at a table. You do not walk into the kitchen. You tell the waiter what you want, the waiter takes the order to the kitchen, and comes back with your food, or with "sorry, we are out of that".

  • You are the client: the one asking.
  • The kitchen is the server: the one that has what you want.
  • The waiter and the menu are the API: the agreed way to ask, and the list of what you may ask for.
  • Your order is a request. What comes back is a response.

The menu matters. You cannot order something that is not on it, and you have to order in a way the kitchen understands. An API is the same: it publishes what you can ask for and the exact form the request must take.

API stands for application programming interface. "Interface" is the important word: it is the counter between two programs.

A real example ​

A weather app on your phone does not measure the weather. When you open it, it sends a request across the internet to a weather service:

http
GET https://api.example.com/weather?city=Chennai

The service answers with data, not with a web page:

json
{
  "city": "Chennai",
  "temperature": 31,
  "condition": "Partly cloudy"
}

The app reads that answer and draws the sun and the number. The request and the answer are the API at work. Everything the app shows you came through it.

The words you will meet ​

WordMeaning
ClientThe program that sends the request: an app, a web page, or a tool such as ApiWorkbench
ServerThe program that receives the request and answers it
RequestThe question: what you want, and any details the server needs
ResponseThe answer: a status saying how it went, and usually some data
EndpointOne address the API answers at, such as /weather or /users/42. An API is a set of endpoints
URLThe full address of an endpoint, such as https://api.example.com/weather
HTTPThe set of rules requests and responses follow on the web. The next lesson covers it
JSONThe text format most APIs use for data. Lesson 3 covers it

Why not use a browser? ​

A browser is a client too, and for the simplest request it works: type an address, get an answer. But a browser can only easily ask to read. It cannot comfortably send data, set headers, sign in with a token, repeat a request a hundred times or check that the answer is correct.

An API client is a tool made for that. ApiWorkbench is one. You fill in the request, press Send, and see everything the server said: the status, how long it took, the headers and the data.

ApiWorkbench showing a GET request to an orders endpoint and its JSON response
  1. 1Method — What kind of request this is. GET means read.
  2. 2URL — The address of the endpoint.
  3. 3Send — Sends the request to the server.
  4. 4Status — How it went. 200 OK means success.
  5. 5Response body — The data the server sent back, as JSON.

Why people test APIs ​

An app is only as reliable as the API behind it. If the API returns the wrong price, accepts an order with no items, or takes ten seconds to answer, every app that uses it is broken, however good its screens look.

Testing the API directly finds those problems early:

  • It is fast. A request takes milliseconds. Clicking through screens takes minutes.
  • It is precise. You see exactly what the server said, not what a screen chose to show.
  • It reaches the awkward cases. You can send a missing field, a wrong password or a huge number that the app's own screens would never let you type.

That is what the testing guides teach.

And when the API does not exist yet? ​

Often the app and the API are built at the same time, by different people. The app team cannot wait. The answer is a mock server: a stand-in that answers at the same addresses with realistic, made-up data. Mock Studio builds one without code. You will make one in lesson 5.

What you learned ​

  • An API is the agreed way for one program to ask another for something.
  • A client sends a request to an endpoint on a server and gets a response.
  • An API client such as ApiWorkbench lets you send any request and inspect the whole answer.
  • A mock server stands in for an API that is missing, unfinished or awkward to test against.

Next steps ​

  • HTTP basics: the rules requests and responses follow
  • Glossary: every term on this site in one place