Application programming interface Study Guide

📖 Core Concepts API (Application Programming Interface) – a software interface that lets programs (or computers) talk to each other; it exposes only what’s needed and hides internal implementation details. Specification vs. Implementation – the spec describes the calls, arguments, and contract; the implementation actually provides the functionality. Calls / Endpoints – the functions, methods, or URLs that a programmer invokes; sometimes called subroutines, methods, or requests. Contract – an API is a formal agreement: the provider promises certain behavior; the consumer promises to use it as documented. Abstraction – by hiding inner workings, APIs let developers work at a higher level without worrying about low‑level changes. 📌 Must Remember API purpose: enable outside interaction with a software system. Design goal: expose only needed objects/actions → minimal exposure. Release categories: Private → Partner → Public (with tokens/validation). Stability: Public APIs should maintain backward compatibility; deprecate/unstable parts are clearly marked. Legal precedent: Supreme Court 2021 – Google’s use of Java API definitions was fair use. Remote vs. local: Remote APIs (e.g., JDBC, RMI) let you call methods on another machine as if they were local. 🔄 Key Processes API Design & Specification Identify required functionality → define calls & data formats → write spec (including contract, error codes, versioning). Integration (Using an API) Read docs → add library/framework (or generate client) → authenticate (token/key) → call endpoint → handle response (parse JSON/XML). Deprecation Workflow Mark feature unstable → announce deprecation → provide migration path → remove in a later major version. 🔍 Key Comparisons API vs. UI – API = program‑to‑program; UI = human‑to‑program. API vs. ABI – API is source‑code level (methods, signatures); ABI is binary‑level (calling conventions, binary layout). Public vs. Private API – Public: open to any developer (often token‑protected); Private: internal to one organization only. RESTful API vs. SOAP API – REST: uses HTTP verbs, lightweight JSON/XML, resource‑oriented URLs; SOAP: XML envelope, strict contracts, often heavier. ⚠️ Common Misunderstandings “APIs are only for web services.” – APIs also exist as library/OS interfaces, remote DB connectors, etc. “If an API is public, it never changes.” – Public APIs can evolve; they must use versioning and deprecation warnings. “Using an API means you can ignore its docs.” – Directives, constraints, and edge‑case notes in docs are essential to avoid misuse. 🧠 Mental Models / Intuition Lego Block Model: Each API is a connector that lets you snap one piece of software onto another without seeing the internals. Contract Model: Think of an API like a lease agreement – both sides have rights (features) and obligations (usage rules). 🚩 Exceptions & Edge Cases Versioning conflicts: When two services require different major versions of the same API, you may need a compatibility shim. Deprecated but still functional: An API flagged “unstable” may still work; however, future removal is possible—plan migration. Cross‑language bindings: Some libraries expose the same API in multiple languages; subtle differences (e.g., data‑type mapping) can cause bugs. 📍 When to Use Which Choose a Library/Framework API when you need tight, language‑specific performance and can bundle the library with your app. Choose an OS API (e.g., POSIX, Win32) for system‑level operations like file I/O or process control. Choose a Remote API (JDBC, RMI) when the resource lives on another machine or service. Choose a Web API (REST) for stateless, scalable, internet‑facing services; prefer SOAP only if you need built‑in WS‑Security or formal contracts. 👀 Patterns to Recognize “Token / Key” pattern – most public web APIs require an authentication token in the header or query string. “CRUD URL + HTTP verb” pattern – REST APIs map Create/Read/Update/Delete to POST/GET/PUT/PATCH/DELETE on resource URLs. “Deprecated flag in docs” – look for words like unstable, deprecated, will be removed → start migration. 🗂️ Exam Traps Confusing API with UI – a question may describe a “user‑friendly interface” but ask about API design; remember the programmer‑to‑programmer focus. Assuming all public APIs are stable – exam may test knowledge of deprecation and versioning; watch for wording about “breaking changes.” Mixing up ABI and API – choose the answer that mentions source‑code contracts for API, binary contracts for ABI. Legal question nuance: The 2021 Supreme Court ruling upheld fair use, not that APIs are unprotected; be precise about the legal outcome.