Here are some of the most common questions about APIs that we've seen/heard. If you have another question, please post it to the google group. If enough people ask about something, we'll add it here!
- What does API stand for?
- Application Programming Interface.
- What does an API do?
- APIs provide a standardized way for developers to leverage data, functions, and applications to build entirely new products and services. The interfaces allow users and programs outside of a company to access specific functions or data from inside the company, without exposing everything inside the firewall. Because they are both simple and flexible, APIs make it possible for companies to rapidly expand into new contexts and be readily prepared to adapt to meet the ever-changing needs of their customers.
- What languages are used for API interfaces?
- Any programming language can be used, but the most common REST languages are:
- OpenAPI Specification (OAS) — formerly Swagger
- OData – Microsoft-sponsored Open Data Protocol for REST APIs
- YAML (YAML Ain't Markup Language)
- What tools are used for API documentation?
- APIs can be documented in pretty much any tool out there, from MS Word or Open Office Write or FrameMaker to the most basic text editor. The most common non-wordprocessing tools are Swagger, Postman, or text editors such as Notepad++. It is possible to do API documentation in HTML or XML/DITA, for which there are a large number of tools.
APIs and SDKs — what's the difference?
Both are a way for a program to interface with and control the resources provided by another piece of software, whether that other software is a web service, an end-user app, an OS service or daemon, or a kernel device driver.
So… what is the difference between an SDK and an API?
The TL:DR answer is that all modern SDKs are or contain APIs but not all APIs are SDKs.
The long form is as follows:
A Software Development Kit is the "box" that contains (or references) all the "tools" (APIs, documentation, samples, etc. that's needed to create an application. An SDK could be nothing but an API (files to help interface with another app), but usually includes other code to help with debugging and other pieces for your IDE. In addition, Typically one SDK covers an entire platform or product. As examples, there's one MacOS X SDK and one iOS SDK, and each of those contain API's for many different areas of functionality.
An Application Programming Interface is a specification for a set of related methods that allow one program or service connect to a different program or service. For example, being able to link an excel spreadsheet to an Oracle database. Not all API's are fully documented, and while examples can be part of the documentation for an API, generally the minimal documentation is functions, calls, data types, sizes/limits, and classes. More extensive (and useful) documentation includes supported protocols, supported file formats, error messaging, and so on. Sometimes there is a graphic illustrating the data flow or the workflow. A lot depends on how much handholding is expected. Also, whether a technical write is involved to ask the tough questions of "what happens next?" and "what happens if XXX occurs?". A lot of time, developers don't think about such things unless they are forced to.
Be aware that these days the term "API" is often used (incorrectly) as a synonym for "library". Part of a software library is the API that allows code to use the library, but the library itself isn't an API.