API Terminology Guide everything you need to know

My first attempt at building an API was a disaster I couldn’t fetch or read and my self-imposed deadline to deploy it in a production environment was running out. I had to scour hours of YouTube content just to work out why I couldn’t get it to work as planned. Some of the terminology was giving me trouble and I remember scribbling what I was learning on a notebook and then adding them to a spreadsheet as I learned the steps to create my own API S.O.P.

I’m sharing what my notes looked like with you today to help if anyone else had a similar issue trying to learn, build and deliver under tight deadlines. It’s not exhaustive but it should cover everything you need to know and how they work to get you started.

Why it matters now more than ever:

1. API literacy is no longer just for tech roles. It’s crucial for:
– Project Managers
– Business Analysts
– C-level Executives
– And anyone involved in modern business operations

2. APIs are the backbone of:
– Business integrations
– Data exchanges
– Service compositions

I’ve built a learning portal as well that outlines the steps to build your own APIs, I hope you find this resource useful.

Learn How To Build APIs

Learning Objective:

To ensure a thorough understanding and correct implementation of API concepts, tools, and processes.

Step 1: Understand Basic API Concepts

API: Application Programming Interface – allows different software to communicate.
API Call: The request made by a client to an API endpoint.
API Economy: The ecosystem of businesses and services built around API-driven interactions.
API Endpoint: The specific route where API calls are directed.
API Integration: The process of linking an API to a system or platform for specific functionality.

Step 2: Learn the API Lifecycle

API Lifecycle: Plan, design, develop, test, deploy, and retire an API.
API Request: A call made to the server, specifying desired data or operations.
API Response: Data returned from the server, often in formats like JSON or XML.

Step 3: Understand API Security Measures

API Keys: Unique identifiers used to authenticate the client making the API call.
API Security: Methods to protect API access, including OAuth, API keys, and JWT tokens.
APIsec: Security practices that focus on protecting APIs from vulnerabilities and attacks.
DDoS: Distributed Denial of Service attacks, where APIs are overwhelmed by traffic.

Step 4: Dive into API Infrastructure

API Gateway: Acts as a reverse proxy to manage traffic between the client and backend services.
API Portal: The interface developers use to access, learn about, and implement an API.
API Layer: The abstraction layer that provides API access while hiding complexity.

Step 5: Explore API Development and Testing Tools

Burp Suite: A tool for security testing of web applications, commonly used to assess API vulnerabilities.
Apigee: A comprehensive platform for managing APIs, providing tools for API lifecycle management.

Step 6: Implement Best Practices for API Design

CI/CD: Continuous Integration/Continuous Deployment – automating the process of testing and deploying API code.
CRUD: Create, Read, Update, Delete – the four basic functions of persistent storage in APIs.

Step 7: Dive into API Performance Optimizations

Cache: Techniques to store data locally for faster subsequent requests.
Pagination: Breaking up large datasets into manageable pages for performance.
Rate Limiting: Controlling the number of API calls a client can make to avoid overloading the server.

Step 8: Deep Dive into API Responses

Response Code: HTTP status codes (200, 404, 500) that communicate the result of an API call.
Payload: The data transferred in the body of the API request or response.

Step 9: Finalize Documentation

API Documentation: Thorough documentation detailing how to use the API, including examples, available endpoints, and response formats.
Query Parameters: The dynamic variables passed in the API URL to filter or modify the response.

Step 10: Regular Audits and Improvement

Framework: A standard API framework like REST or GraphQL ensures scalability and ease of use.
Logic Flaw: Regularly audit APIs for potential logic flaws that could result in unintended functionality or security issues.

Advanced API SOP

Learning Objective:

To cover more advanced API-related concepts, tools, and best practices to implement, secure, and monetize APIs in production environments.

Image: Dash Devs

Step 1: Understand Data Formats and Communication

JSON: JavaScript Object Notation – lightweight data-interchange format.
SOAP: Simple Object Access Protocol – protocol for exchanging structured data in web services.
REST: Representational State Transfer – API architecture style relying on stateless, client-server, cacheable communications.

Step 2: Explore Microservices Architecture

Microservices: Architectural style where applications are structured as a collection of loosely coupled services, each serving a single function. Each microservice runs independently and communicates via APIs.

Step 3: API Security Auditing and Tools

OWASP: Open Web Application Security Project – provides guidelines for securing APIs.
ZAP: Zed Attack Proxy – open-source security tool for finding vulnerabilities in web applications, especially useful for APIs.
Penetration Testing: A simulated cyberattack to find security vulnerabilities in APIs, checking for flaws like SQL injection, DDoS, and over-permission containers.
Link to Security Toolkits

Step 4: Monetize Your API

Monetization: Use pricing models like pay-per-use, subscription-based models, or tiered pricing. Include rate limiting and pricing tiers based on API usage.

Step 5: API Security Testing and Common Vulnerabilities

SQL Injection: Malicious injection of SQL commands to manipulate database queries, leading to unauthorized access to data.
Over-Permissioned Containers: Avoid giving API services excessive permissions, following the principle of least privilege.

Step 6: Environment Management

Production Environment: The live environment where your API interacts with real users and data. Ensure the production environment is well-tested, secure, and monitored.

Step 7: Improve Workflow and Testing in SDLC

SDLC: Software Development Life Cycle – integrates security and performance testing into each phase, from design to deployment.
CI/CD: Continuous Integration/Continuous Deployment pipelines automate testing and deployment of API updates.

Step 8: API Documentation and Webhooks

SDK: Software Development Kit – helps developers integrate APIs with pre-built tools.
Webhook: A method to provide real-time data to a system based on events (e.g., sending an HTTP POST when data changes in an API).

Learning how to build, manage and maintain APIs was phase 1 of my career but learning or should I say unlocking the knowledge of how to optimise and extend the functionality of my APIs has definitely been a highlight in Phase 2 & 3 of my engineering career. Work smarter, not harder and give your APIs the attention that they deserve.

What Different Types of APIs are there?

In terms of architecture, there are five types of APIs:

REST APIs: REST APIs allow you to perform CRUD (create, read, update, and delete) operations between a client and a server. It provides multiple API endpoints to manipulate data.
GraphQL APIs: It is a query language that lets clients request the precise data they require from the server. Thus, eliminating the issues of under-fetching and over-fetching that occur in other operating systems.
SOAP APIs: Any web service that complies with the SOAP web services API specification is a SOAP web service.
Kafka APIs: Apache Kafka is an event streaming platform that combines three capabilities so that you can implement different use cases. The three capabilities are publishing and subscribing to the streams of events, storing streams of events durably and reliably, and processing streams of events as they occur.
Async APIs: These APIs work on the principle of Event-Driven Architecture (EDA). In AsyncAPIs, multiple Subscribers can subscribe to a Publisher. When an event occurs, the Publisher (API provider) can notify all the Subscribers via the Message broker.

There are four main types of Access APIs:

Open APIs: Also known as Public APIs. These APIs are publicly available, and there are no restrictions to accessing them.
Partner APIs: These APIs are not publicly available, so you need specific rights or licenses to access them; a good example is APIs shared by a business with business partners to leverage the API capabilities to provide business value.
Internal APIs: Also known as Private APIs. These APIs are usually meant for use within a company and are only exposed by internal systems. A company can use this type of API across different internal teams to be able to improve its products and services.
Composite APIs: These APIs combine different data and service APIs. It is a sequence of tasks that runs synchronously as a result of the execution and not at the request of a task. The main purpose of this type of API is to speed up the process of execution and improve the performance of the listeners in the web interfaces.

The language of APIs is the language of modern business. In the past years APIs have enabled hundreds of thousands of businesses to become profitable, they are exceptionally powerful and make everyone’s life easier.

This guide is intended for beginners, intermediates and seasoned pros alike. I’ve certainly had to brush up on a couple of terms I haven’t seen or used in some time. It is designed to enhance your understanding and improve communication.

If this guide helped you before or you’re discovering it for the first time, please share it with your network.
Let’s continue to build awesome API product suites and further the tech industry together.