DEV Community

Cover image for A Developer’s Guide to APIs and Their Classifications
Prachi Gupta
Prachi Gupta

Posted on

A Developer’s Guide to APIs and Their Classifications

#webdev #javascript #programming #api

Understanding APIs: Definition, Purpose, and Their Various Types

Hello Devs!

Whether you're new to development or brushing up for interviews, understanding APIs is essential in today's tech world. Let's dive into what an API is, the various types (with real examples), and explore important topics like Webhooks, Streaming APIs, and comparisons between REST, RESTful, SOAP, and GraphQL.

What is an API?

API stands for Application Programming Interface.

It allows two software applications to communicate with each other. Think of it like a waiter at a restaurant — you (the frontend) tell the waiter (API) what you want, and the waiter tells the kitchen (backend) to prepare it and deliver it to you.

Example: When you open your weather app, it uses an API to fetch weather data from a remote server.

Types of APIs (With Examples)

1. Open APIs (Public APIs)

These are available for anyone to use, often with registration.

Example:

  • OpenWeatherMap API – get weather info.
  • GitHub’s public API.

2. Internal APIs (Private APIs)

Used within a company only, not exposed publicly.

Example:

  • A company’s internal payroll system API used only by HR apps.

3. Partner APIs

Shared with specific external partners with authentication.

Example:

  • A flight booking company gives API access to travel partners like MakeMyTrip.

4. Composite APIs

These combine multiple API calls into a single request.

Example:

  • One API request fetches user profile, order history, and wishlist from different services in one go.

Web APIs (Protocols & Architectures)

Let’s look at the architectural styles and protocols of APIs used in web development.

1. REST API (Representational State Transfer)

Most popular architecture style.

Features:

  • Stateless: Every request is independent. The server does not remember the previous request.

For example, if you log in and then fetch your profile, each request must include your token. The server doesn’t "remember" you unless you tell it who you are again.

  • Can return data in JSON or XML (JSON is more common today).

  • Uses HTTP methods:

    • GET (read)
    • POST (create)
    • PUT (update)
    • DELETE (remove)

Example:

GET /users/101
Enter fullscreen mode Exit fullscreen mode

Returns the user with ID 101.

2. SOAP API (Simple Object Access Protocol)

An older protocol, more strict and secure.

Features:

  • Uses XML format only.
  • Works over HTTP, SMTP, etc.
  • Heavier than REST, but good for banking and enterprise systems.

Example:

<soap:Envelope>
  <soap:Body>
    <GetUser>
      <id>101</id>
    </GetUser>
  </soap:Body>
</soap:Envelope>
Enter fullscreen mode Exit fullscreen mode

3. GraphQL API

Developed by Facebook. A modern alternative to REST.

Features:

  • Clients can request exact data they want.
  • Uses a single endpoint for all queries.
  • Reduces over-fetching and under-fetching of data.

Example:

query {
  user(id: 101) {
    name
    email
  }
}
Enter fullscreen mode Exit fullscreen mode

Webhook vs Streaming API

What is a Webhook?

A Webhook is like a reverse API call — instead of you asking the server, the server notifies you when something happens.

Example:

  • Stripe sends a webhook to your backend when a payment is successful.

You register your URL with the provider, and they call it when an event occurs.

What is a Streaming API?

Streaming APIs provide real-time data over a continuous connection — no polling.

Example:

  • Twitter’s Streaming API sends you tweets live without you needing to constantly ask for updates.

Used in:

  • Stock market updates
  • Live chat apps
  • IoT sensors

REST API vs RESTful API

These two terms confuse many, especially in interviews.

  • A REST API refers to any API that uses REST principles.
  • A RESTful API is an API that strictly follows REST guidelines (proper use of HTTP verbs, stateless communication, correct URI structure, etc.)

Example of a RESTful design:

GET /users/101
Enter fullscreen mode Exit fullscreen mode

Example of a non-RESTful API (not RESTful):

POST /getUser?id=101
Enter fullscreen mode Exit fullscreen mode

(Uses POST for read operation — not RESTful)

So: REST is the style, RESTful is how properly it's implemented.

REST vs SOAP vs GraphQL — Quick Comparison Table

Feature REST SOAP GraphQL
Format JSON, XML XML only JSON
Protocol HTTP HTTP, SMTP HTTP
Flexibility Medium Low (strict) High
Real-time support No (extra setup) No Yes (subscriptions)
Learning Curve Easy Steep Moderate
Use Case Web & mobile apps Enterprise apps Modern UIs, mobile

Key Concepts to Remember

  • Stateless means each request is independent — no session is stored on the server.
  • REST is most popular due to simplicity.
  • GraphQL is powerful for frontend needs.
  • SOAP is strict, secure, and still used in enterprise systems.
  • Webhooks are great for event-based triggers.
  • Streaming APIs are best for real-time data.

Final Thoughts

  • APIs are the backbone of modern applications.
  • REST is widely used, but GraphQL is becoming popular for flexible frontend needs.
  • Webhooks and Streaming APIs are excellent for real-time use cases.
  • Understand the differences not just for coding — but also for interviews!

Follow me for more tech content, beginner-friendly explanations, and development tips:

Top comments (0)