The API Handbook: Your Gateway to Seamless Software Integration

An API (application programming interface) is how one piece of software asks another for data or for an action: your website asking a payment gateway to take a payment, a shipping service for a tracking status, or an SMS provider to send an OTP. This handbook covers the basics every business owner and beginner developer needs, shows a first API call, and points to our in-depth guides for each topic.

1. What an API is, in one example

Think of a restaurant. You (the client) don't walk into the kitchen (the other system's database). You give an order to the waiter (the API) in an agreed format, and the waiter brings back what you asked for, or an explanation of why not.

Every modern integration works this way: UPI and card payment gateways, GST and e-invoicing services, courier tracking, WhatsApp Business messaging, maps, AI models. Each provider publishes documentation describing its endpoints, the data it expects and what it returns.

2. The parts of an API call

The status code tells you what happened before you read the body:

3. Make your first API call

You can try an API from any terminal with curl. This reads data (GET) and then creates something (POST) on a typical REST API:

# Read
curl -s https://api.example.com/v1/orders/1234 \
  -H "Authorization: Bearer YOUR_API_KEY"

# Create
curl -s -X POST https://api.example.com/v1/orders \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 49900, "currency": "INR"}'

The same POST from PHP, with a timeout and proper error handling:

<?php
// Keys live in a file outside public_html, e.g. /home/youruser/config/secrets.php
$secrets = require dirname(__DIR__) . '/config/secrets.php';

$ch = curl_init('https://api.example.com/v1/orders');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 20,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $secrets['orders_api_key'],
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode(['amount' => 49900, 'currency' => 'INR']),
]);
$body   = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($body === false) {
    error_log('API call failed: ' . curl_error($ch));
} elseif ($status >= 400) {
    error_log("API returned $status: $body");
} else {
    $order = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
}

And from JavaScript on a server (Node.js 18 or later has fetch built in):

const res = await fetch("https://api.example.com/v1/orders/1234", {
  headers: { Authorization: `Bearer ${process.env.ORDERS_API_KEY}` },
  signal: AbortSignal.timeout(20000),
});
if (!res.ok) throw new Error(`API returned ${res.status}`);
const order = await res.json();

For a fuller PHP walk-through, see how to integrate third-party APIs with PHP.

4. The main kinds of API

• REST uses URLs for things and HTTP methods for actions, with JSON data. It is what most payment, SMS and business APIs offer.
• GraphQL has one endpoint where the client asks for exactly the fields it needs. See building GraphQL APIs.
• Webhooks reverse the direction: the provider calls your URL when something happens, such as "payment captured".
• SOAP is an older XML style still found in some banking and government integrations.
• WebSockets and streaming keep a connection open for live updates such as chat.

When and why to choose each is covered in Mastering API architectures.

5. Keep your API keys safe

• Store keys outside your web root, in a config file above public_html or in environment variables, never in a file a browser can download.
• Use test keys while building; most payment gateways give separate sandbox credentials.
• Give each integration its own key with the narrowest permissions the provider allows, so you can revoke one without breaking the rest.
• Verify webhooks. Check the signature header the provider sends, using its documented method, before you trust a "payment successful" message.
• Validate everything that comes back before you save it to your database.

The full picture, including OAuth 2.0 and JWT, is in The evolution of API authentication.

6. Handle errors and rate limits

• Set a timeout on every call, as in the examples above, so a slow provider does not freeze your page.
• Retry only what is safe to retry, such as 429, 502, 503 and 504, and wait longer each time. If the response has a Retry-After header, respect it.
• Don't retry a payment blindly. Use the provider's idempotency key, if it offers one, so a repeated request cannot charge twice.
• Log the status code and the provider's error message, never the API key.

7. Test before you build

Try each endpoint in a tool such as Postman or with curl before you write application code, so you know exactly what the API returns for success and for each error. Our Postman guide covers collections, environments and automated tests.

8. Running API integrations on Domain India

• cPanel shared hosting. PHP's cURL functions work for calling external APIs. Socket and process functions such as fsockopen, stream_socket_client and proc_open are disabled, so a library that relies on them fails; see PHP disabled functions on shared hosting. A request that takes longer than about 90 seconds returns a 504, so move slow work to a cron job.
• DirectAdmin shared hosting. curl_exec is disabled on most DirectAdmin sites, so test an integration on your plan before you rely on it.
• App Platform. Node.js apps are detected automatically and other languages run from a Dockerfile. Keep keys in the app's environment variables. WebSockets are not supported. See getting started with the App Platform.
• VPS. A self-managed server with root access runs any API client or server, including WebSocket and gRPC services.

Frequently asked questions

Ready to build an integration? Read Mastering API architectures, deploy an API service on the App Platform, or open a support ticket if a call fails on your hosting. Support is on 24/7 live chat, and tickets get a first response within 15 minutes.