What an API is, in plain words: requests, answers and a REST example

PHP & Development·· 48 views· 4 min read

The short answer: an API is the agreed way for one program to ask another for something. Instead of a person opening a page and clicking, your site sends a request to an address, with a method that says what it wants done, and gets back a response with a status code and, nearly always, data in JSON. That is how a shop talks to its payment operator, how a form sends an SMS, and how an automation reads a spreadsheet. This article is for people starting to code an integration, or ordering one from a developer and wanting to follow the conversation.

The parts of a request

Part What it is In the example below
Endpoint The address of one thing inside the API. In a REST API each thing (an order, a customer, a message) has its own. https://api.example.com/v1/orders/123
Method The verb: GET reads, POST creates, PUT or PATCH changes, DELETE removes. GET to read order 123; POST to create a new one.
Headers Information about the request: who is asking (the key), what format is being sent and what format is wanted back. Authorization, Content-Type, Accept
Body The data sent when creating or changing something. In current APIs, usually JSON. {"customer": "ana@example.com"}
Status code The outcome in three digits: 2xx it worked, 4xx the problem is in the request, 5xx the problem is on the other side. 200 OK when reading; 201 Created when creating; 401 if the key is wrong.
Response What the API sends back: the data you asked for, or an error message, usually in JSON. The order, with its status.

A REST example, step by step

1 Read the service’s documentation first. It gives the base address (here https://api.example.com/v1), how to authenticate (here a key in the Authorization header) and the usage limits. “REST” is only a style: every thing has an address and the method says what to do with it.
2 Read an order with curl, in cPanel’s Terminal (if your account has one) or on your own computer. The -i shows the status code and the response headers: curl -i https://api.example.com/v1/orders/123 \
-H "Authorization: Bearer YOUR_KEY" \
-H "Accept: application/json"
3 Read the response from the top: the code first, then the data. HTTP/1.1 200 OK
Content-Type: application/json

{"id": 123, "status": "paid", "customer": "ana@example.com"} If the code is not 2xx, what follows is an error message, not the data you asked for.
4 Create an order with POST. Now there is a body, and the Content-Type header says it is JSON: curl -i -X POST https://api.example.com/v1/orders \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"customer": "ana@example.com", "product": "basic-plan"}' A REST API usually answers 201 Created and returns the new order with its identifier.
5 Move to code only once curl works. In PHP you do the same with cURL: calling a web API from PHP and reading the JSON. If the response will not parse, see json_decode returns null.
6 If the response says “received” rather than giving the final result, the API is asynchronous: the result comes later. See synchronous or asynchronous.
An API key is a password. Calls to the API are made from the server (PHP, Node, Python), never from JavaScript running in the visitor’s browser: anything sent to the browser can be read by whoever visits the site. Keep the key out of the code, as in environment variables and secrets, and if it ever turns up where it should not, follow an API key or token has leaked.
Many services have a test environment (often called a “sandbox”), with its own keys and address, where you can create orders and payments with no real money. Use it until everything works, and only then switch to the live keys.

Your integration does not answer the way the documentation says? Send us the endpoint, the method and the status code you get (never the key) and we will check whether anything on the hosting side is blocking it.

Open a support ticket

SEE ALSO

Calling a web API from PHP with cURL and reading the JSON reply

json_decode returns null: how to find out what is wrong with the JSON

Synchronous or asynchronous: why a payment or SMS confirmation arrives later

What a webhook is, and how to test one with curl

CORS error between your front end and your API: how to fix it

An API key or token has leaked: what to do, in the right order

RECOMMENDED PRODUCT

Web hosting with cPanel

Domain and SSL included, daily backups and the panel you already know. from $6.60/mo (3-year plan, with coupon)

See plans
Was this answer helpful? Your answer helps us improve this article.

Related Articles

PHP & Development 1,057 How to change your PHP version You can choose which PHP version your site runs on, from the older releases up to the most recent ones, and turn extensi...
PHP & Development 688 Which technologies run here: PHP, Node, Python, Perl, games and the limits «My developer asks whether you support X.» This page answers that in one go, with names and versions - and it also says...
PHP & Development 1,437 Viewing and adjusting your PHP configuration: version per folder, extensions and phpinfo Changing a whole site's PHP version is easy and is covered in how to change your PHP version. This article is the next s...
PHP & Development 760 PHP limits: memory, time, upload size and the one that fails silently «I cannot upload the image.» «The import stops halfway.» «The menu lost half its items after saving.» Three different co...
PHP & Development 641 Where the PHP error log is, how to read it, and the errors you will see most When a site breaks there are two ways to react: guess, or read what the server already wrote down. The second is faster...
PHP & Development 40 Callback URL or return URL: why a customer coming back is not proof of payment The short answer: an online payment usually involves two addresses of yours that the operator uses. The return URL (or s...