A beginner's guide to API (Application Programming Interface)

API stands for Application Programming Interface. It helps establish a connection between two different systems, often in a common language. Technically, it’s a set of rules and protocols that determines how a system can request data from another system. APIs are a means to expose a system or application to interactions with other systems.

Because the API connection is created in standardized common languages, knowledge or understanding of how the system is built isn't necessary for the other system. API works by hiding internal details of the system and only exposing the parts of the system required for the integration. It can be used to plug into an existing program instead of building one from scratch.

How does API work?

To understand how API works, there are some key terms and concepts that we need to understand first.

Client: In an API workflow, the client is the entity that makes the request. In most cases, this is a request for specific data.

Server: A server is the entity that holds the data the client requests. In other words, it’s the entity that performs the task of the API.

API endpoints: These are essentially URLs that are matched to the respective application or data. They act as access points for the API.

HTTP methods: The API requests are typically sent using one of the four main HTTP methods:

• GET: Used to retrieve data.

• POST: Used to add new data.

• PUT: Used to update data.

• DELETE: Used to remove data.

Now, we'll see how an API actually works.

Step 1: The client sends a request

The client needs to access certain data. It sends a request to the API endpoint associated with that data. The request will include:

• Endpoint URL (e.g., https://api.example.com/products)

• HTTP Method (e.g., GET, POST)

• Headers (e.g., content type, authentication token)

• Parameters (query strings, path variables, or body data)

Step 2: The server processes the request

The server receiving the request will perform a series of actions to fulfill it:

• Validate the request by checking the format and permissions.

• Authenticate the client.

• Perform the task requested by the API request.

• Generate the appropriate response.

Step 3: The server reverts with a response

To inform the client about the API request, the server sends a response once the request is processed. The response generally includes:

• Status Code (e.g., 200 OK, 404 Not Found, 401 Unauthorized)

• Response Body (usually in JSON or XML)

• Headers (e.g., content type, rate limit info)

API request—response workflow example

Request:

GET /users/123 HTTP/1.1 
Host: api.example.com 
Authorization: Bearer YOUR_API_KEY 
Accept: application/json

Processing by server:

• Verify the token used to raise the request.

• Fetch user with ID 123 from the database.

• Return the formatted user data requested.

Response:

HTTP/1.1 200 OK 
Content-Type: application/json 
  { 
  "id": 123, 
  "name": "John Doe", 
  "email": "john@example.com" 
} 

Types of APIs

Not all APIs are made equal. APIs can be categorized into types based on two main aspects—access level and infrastructures.

Access level types

When an API is created, it is not always available for everyone to use.There are rules and policies that govern its use and dictates who can access it. There are three main restrictions for APIs:

• Private or internal APIs: These APIs are accessible only by a single person or an entity. They’re often shared within an organization. They’re used to connect systems or enable flow of data between different sections.

• Partner: Partners of the API’s owner are allowed access to use the API. These will require special keys or agreements to use.

• Public or open APIs: These APIs are open for everyone to use and easily accessible. They’re posted publicly with instructions on how to use them so developers can access them easily.

Infrastructure types

APIs can also be categorized based on the type of infrastructure used. API architecture determines how data is requested, sent, and received between systems. Each architecture type comes with its own protocol, format, and purpose—affecting performance, flexibility, and use cases.

REST (Representational State Transfer)

REST APIs use standard HTTP methods like GET, POST, PUT, and DELETE to raise requests. It’s one of the most common API types due to the simplicity, flexibility, and no requirement of request history (statelessness). The format of the API is usually in JSON or XML.

SOAP (Simple Object Access Protocol) 

SOAP is a less flexible protocol where data is exchanged only in the XML format. It has a strict standard for message structure. It’s widely used in enterprise and legacy systems.

It supports advanced features like built-in error handling and transaction control. SOAP is ideal for industries like banking, insurance, or healthcare—where security and formal contracts are non-negotiable. It also comes with built-in security like WS-security for authentication, integrity, encryption, and transaction control. It’s commonly used by financial services, telecommunication systems, and government applications.

GraphQL

GraphQL is a query language that allows users to ask for the exact data they need. The client specifies exactly what data it needs in a single query. This means you can fetch multiple related resources in one request, reducing the risk of over-fetching or under-fetching data. In contrast, REST APIs return a fixed data structure determined by the server, often resulting in either too much data (over-fetching) or not enough (under-fetching), requiring additional calls.

WebSockets

The WebSocket protocol allows two-way communication between the client and server. It eliminates the need for constant polling to know if there is new data to share. The connection remains open, enabling two-way and real-time interactions. After the initial handshake, communications are often lightweight, with just the data and no headers. This is used in applications that need a live relay of data, like trading platforms, analytics dashboards, and chat apps.

RPC (Remote Procedure Call) 

RPC APIs allow the client to execute requests directly on a remote server—similar to a local server even though the data resides in another server. There are different formats of RPC available: JSON-RPC, XML-RPC, and gRPC. They’re often used by internal microservices, backend automations, and embedded systems. They’re easier to implement for developers but can be hard to scale.

Summary table

Best practices and security considerations for APIs

Authentication

Authentication is the process of verifying who is making the request. Best practices for API authentication include:

• Using OAuth 2.0 for third-party access.

• Using API keys for internal services.

• Using JSON web tokens for stateless, secure authentication.

• Implementing multi-factor authentication.

Authorization

Authorization is the process that determines what the requestor is allowed to do after the authentication. Best practices include:

• Implementing role-based access control (RBAC) or attribute-based access control (ABAC).

• Using scopes in OAuth to limit permissions.

• Checking permissions on every request—not just at login.

Rate limiting and throttling 

Set a limit on the number of requests a client can make to prevent abuse or DoS attacks. Rate limits can be implemented based on user, IP, or token. Make sure to monitor and alert for suspicious usage patterns.

Input validation

Ensure that the data being pushed through the API doesn’t contain malicious code. Validate all inputs, like data types, length, and structure. Sanitize to avoid SQL injection, XSS, and command injection. Use libraries like OWASP's ESAPI or validator.js to secure your applications.

Encryption

Make sure to protect your data using encryption at rest and transit. Use HTTPS/TLS encrypted pathways for API. Use end-to-end encryption wherever needed and possible. Encrypt sensitive data stored in databases using advanced encryption algorithms.

CORS (Cross-Origin Resource Sharing) 

CORS will help create a policy on how to handle requests from different origins. You can configure the policy to allow only trusted domains. You can also restrict methods and headers using the CORS policy.

Logging and monitoring

Make sure to log and track all API activity to your server. This will help detect anomalies, security incidents, and patterns. Log all authorization attempts, errors, and suspicious activities. Set up alerts to notify suspicious activity like failed authorization attempts.

Versioning and deprecation 

Version your API to help maintain different API versions. Securely deprecate outdated versions with less security with appropriate client notice. Fix vulnerabilities in older versions or deprecate them.

Secure coding practices

Write your API codes with a security-first approach. Some best practices include:

• Using parameterized queries to prevent SQL injection.

• Following the principle of least privilege.

• Regularly performing code reviews and security audits.

• Staying updated on the OWASP API Security Top 10.

Documentation

Ensure that you publish extensive help documentations and keep them updated. This helps developers access and use your APIs better. It also reduces the load on your support staff and helps onboard quicker.

Prioritize optimal performance and scalability

Build the APIs with performance optimization in mind. Fast and reliable APIs will make the user experience better. Similarly, create your APIs to scale up to new features and additional integrations in the future.