API Documentation: What is an API?

By /

catalogs

  1. What is API
    • Definitions and core concepts
    • Explanation of analogies (restaurant ordering example)
  2. How the API works
    • Request and response mechanism
    • Communication protocols and data formats
  3. Common Types of APIs
    • Web API (REST, SOAP)
    • Library/Framework APIs (e.g. Python Standard Library)
    • Operating system APIs (e.g. Windows API)
  4. Scenarios for APIs
    • system integration
    • Feature extensions and service calls
  5. API Design Principles
    • Standardization and Ease of Use
    • Security and Version Control
  6. Frequently Asked Questions (FAQ)

1. What is an API?

Definitions and core concepts

An API (Application Programming Interface) is a set of predefined rules and tools that allow interaction between different software components. Simply put, an API is a "middleman" that passes requests and returns results, allowing developers to invoke functionality without having to understand the underlying implementation.

analogy

Imagine you walk into a restaurant:

  • You (the client): make a request (e.g. "order a steak").
  • Waiter (API): passes the request to the kitchen (server side) and returns the well done steak to you.
  • Kitchen (server-side): hide cooking details and just process orders according to the rules.
    The API acts like a waiter, standardizing the interaction process so that both parties don't have to touch complex logic directly.

2. How the API works

Request and response mechanism

  1. Initiating a request: The client sends an operation command in a specific format (e.g. HTTP request).
    • Example: Browser visits https://weather-api.com?city=Beijing for weather data.
  2. Processing the request: the server side verifies the permissions, parses the parameters and executes the logic.
  3. Return Response: The server returns the result as structured data (e.g. JSON/XML). json{ "city": "Beijing", "temperature": "22°C", "humidity": "65%" }

Communication protocols and data formats

  • Protocols: HTTP/HTTPS (Web API), TCP/IP (underlying communication).
  • Data formats: JSON (lightweight and easy to read), XML (structured and strict), Protobuf (efficient binary).

3. Common types of APIs

typologydescriptivetypical example
Web APIWeb-based interface, usually called via HTTPGoogle Maps API, Twitter API
Library/Framework APIfunction or class library provided by the programming languagePython's requests library
Operating System APIsThe underlying functional interfaces provided by the operating systemWindows File Read/Write API
Hardware APIInterfaces to control hardware devices (e.g. cameras, sensors)Cell Phone Gyroscope API

4. Scenarios for the application of the API

typical scenario

  1. system integration
    • Enterprise systems (e.g. ERP, CRM) synchronize data via APIs.
    • Example: An e-commerce platform calls a logistics API to query the status of an express delivery.
  2. Function Expansion
    • Integration of third-party services (e.g., payments, SMS verification codes).
    • Example: Website access to Alipay API to realize online payment.
  3. data sharing
    • Open data for developers to use (e.g., government open data interfaces).
  4. microservices architecture
    • Microservices communicate with each other through APIs, enabling modular deployment.

5. API design principles

Key principles

  • Standardize: Follow the RESTful design style and use clear URL paths (e.g. /v1/s).
  • Security:
    • Authentication mechanism: OAuth 2.0, API Key.
    • Data encryption: HTTPS transmission + sensitive field encryption.
  • Version control: Distinguish versions by URL or request header (e.g. /v2/s).
  • Documentation: Provide interactive documentation tools (e.g. Swagger/Postman).

best practice

bash

# Example: calling a RESTful API via curl
curl -X GET "https://api.example.com/v1/s/123" \
  -H "Authorization: Bearer YOUR_TOKEN"

6. Frequently Asked Questions (FAQ)

Q1: What is the difference between API and SDK?

  • APIs are rules of interaction, and SDKs (Software Development Kits) are collections of tools wrapped in APIs to provide easier ways to invoke them.

Q2: How to test the API?

  • Use tools like Postman, Insomnia, etc. to debug manually or write automated test scripts.

Q3: Is there a charge for calling the API?

  • Depending on the provider's strategy, there may be free credits, pay-per-use billing, or a subscription system (e.g. AWS API Gateway).

Scroll to Top