What do I not understand about APIs? - language-agnostic

Question

Wikipedia definition:
In computer programming, an application programming interface (API) specifies how some software components should interact with each other.
I've seen some people consider an api of a library just as documentation. Like on api.jquery.com they show how the jquery library gets used. I've also seen people define an api as the visible parts of a library.
I understand how web api's work: There's an interface which you can use to interact with a webapplication using JSON or XML, e.g. youtube api. So I could get information about a youtube video or playlist.
I've read that there are different types of api's. Web api's, library api's, OS api's etc.
Here are some examples that I hope I can clear my confusion with.
Example 1
If I'd include a library in C++, then the header files would be the API? What about an api like Win32/Winapi. Why is this called an api and not a library? Don't I just include it into my source code and start using it?
Example 2
If I want to use a library in C# I'd add a .DLL to my bin folder and tell the compiler I want to use the library (i.e. using System.Web). Would the api just be all the public members (hence the visible parts) in the class that is written in the library?
Example 3
Lets say company X has written an MMORPG game but they do not have a website api. I want to make a windows application and I'd like to make it possible to view any character within my app. How would I communicate with the game to get this data? Where is the api written? How can I view it?
And what kind of an api would an operating system have? How could I use it? Any examples?

Answer 1

API is a contract between service provider and a service consumer (your program). This is it. How is it done, it's implementation specific.
A contract in a way that provider agrees to "If you call function X with parameter Y I promise you the result will be Z.". But client also agrees to "call function X with parameter of type T" and not any nonsense.
Ad1: Your code is a library. It can implement many hidden functions, eg void Nuke_hidden(double lat, double lon); which can strike any place in the world. But you can choose to not expose this method. Instead, have some other one which takes an enum parameter limited to New York, London, Moscow.
Now how your code does something is the body of your library. What you allow your consumers to do with it, is part of your API. Your contract specifically allows bombing only those 3 cities, and forbids bombing any other place.
Ad2: You got it. Exactly.
Ad3: If someone doesn't expose and document an API, it's usually because they don't want you to write such program : ). However they must have some sort of API (even if they never call it such), which the client uses to communicate with the server.

Answer 2

An API is just a definition how to interact with a software component. For example, an API for ebay could contain a function call to create an auction and a function call to retrieve all bids for an auction.
The API is neither some piece of software, nor the documentation, nor a DLL. The API is an abstract definition of how to "talk" to a piece of software. How it is implemented depends on the developer that provides the API.
Of course, to tell other programmers how to use your software, you need to provide documentation of the API. That is: What calls are available? Which parameters do they require and accept?
So, regarding example 1) The header file would define how to use your API using C++. Just like for Windows. Windows has an API (that is: an interface applications can use to create windows, textboxes, etc.). The header files define how to use that from C++.
Regarding example 2) A .NET DLL is a way for a piece of software to interact with an API from managed code. You could say that every class in C# defines an API in that it has public members.
Regarding example 3) Not every piece of software provides access to its internals to other software. For example: Word does have an API you can use to create add-ins. Other software does not provide such an API.