Both API and IDL act as an interface between two components of software and play the role of bridge between two components of software or between two software.
What is the difference between them?
API is a concept. It is any external programming interface that a piece of software exposes so that it can accept external input from some other software, run some logic, and provide output. Usually when we talk about API's, like Facebook's Graph API, or the Windows API, we are talking about the types and logic contained within those API's, and how they can be used.
IDL, as the tag says, is a language you can use to describe a API, in a manner that other software may understand. It is platform independent, so can be used to facilitate integration. More information about this language is vastly available if you search for it ;)
Related
So I was going through the Wikipedia page on API, in the first paragraph it is stated that
A document or standard that describes how to build or use such a connection or interface is called an API specification. A computer system that meets this standard is said to implement or expose an API. The term API may refer either to the specification or to the implementation.
While I understand the 'specification' part of the definition, I didn't get what 'implementation' here means.
Taking Python as an example, whenever I'm writing a program in it I understand that I'm using it's API specification (or API), but what does 'implementation' mean here? Is it the source code of the Python that was used to build this API or object code or something else. And if it really is source code or object code, then it feels counter-intuitive to call them as API to me — so far in my experience I used to see only specification as API. So, if you could kindly help me to resolve this long lasting query, I'll be highly grateful. Thanks.
Sometimes, people use the term 'API' to refer to a library that implements a particular API. This strikes me as a mis-use of the term, but it might be what motivated the Wikipedia article to say "The term API may refer ... to the implementation". There's some discussion of that on the article's 'Talk' page.
"The term API may refer ... to the implementation" is just a suboptimal wording.
Just take the later in that wikipedia article "The calls that make up the API are also known as subroutines, methods, requests, or endpoints. An API specification defines these calls, meaning that it explains how to use or implement them." which points to what I would phrase "the way you call functions, methods, etc. in a programming language are part of the 'API' of that programming language".
The thing that I stipulate the author of "... to the implementation" meant. You could contact him/her directly to clarify that.
It is complicated because API, protocol, ABI have quite some overlap. "API" is in practice the catch-all for saying "something interacts in a controlled way with a system. May it be an Interpreter, an HTTP-service, a dynamic library (because it is ... "an interface (of some kind) to a system" (of some kind).
That said: "implementation" is IMHO a misleading wording. The API is the interface.
If I do a GET request to nginx or apache ... the "API" would be HTTP and the implementation however nginx and apache do to reply to the HTTP request.
If I do a function call to a Python function the API is the function signature; if the backend (what I would call the "implementation" is CPython or PyPy is not the API but the implementation.
The pointers to the talk page for that wikipedia article are worth a lot!
API and implementations with analogy
I like to think of APIs and implementations with a help of an analogy with some real-world devices, like a car for example. Each car has a steering system, which helps you steer the car (obviously). But in order to use this system, you don't have to know how it works and how it's implemented, so you interface with it via a steering wheel. This also has the benefit of each car manufacturing company having a relative freedom of how they can implement the steering system (because at the end of the day all the driver is worried about is the steering wheel). So in this example the steering wheel would be your API/interface, the steering system is the implementation and the driver is some client application.
APIs and implementations in code
This works similarly in code. When developing a software system or a library, you always choose which components (classes/methods/variables) are exposed to the client applications (the ones which use your system/library), and which ones stay hidden from them and become an implementation detail. The first is the API while the latter is the implementation. Imagine you develop a library of collection classes and utilities, and as part of your API you expose a sort(collection) function, which, as the name states, sorts a collection. Client applications will call this API without caring how it's implemented, so later you can change the underlying sorting algorithm without breaking any clients (they probably won't even know something changed, they are just calling the function same as before). In other words, your implementation can change without any changes to the API.
API specifications
Now, where the wording can get confusing is when we add API specifications into the mix. API specifications are often human-readable documents which describe said API (what classes/methods should be there and how they should behave). Such specifications are not code, they are just text-based documents aimed to guide developers to provide an implementation for this API. When a library implements such API specification, it will contain the actual API (code components which correspond to the specification and are exposed to the clients) and implementation (code components hidden from clients which do the actual work and are called by the API). Now, where confusion lies is that the whole library (including both API and implementation) can be called an implementation of the API specification (because this is actual code implementing what is written in a text document, even though this code contains both API and implementation). I think this is what is meant in the Wiki:
The term API may refer either to the specification or to the implementation.
meaning that when you hear the term API it can refer to either a formal text-based document describing said API or to the actual code components which form the API of some software implementation.
Word on Java interfaces: Java interfaces are basically code components which only have an API, meaning they have no implementation and are meant to be implemented by other classes. This allows developers to have API specifications in code so to speak, where they provide a package which contains only interfaces, and other vendors can use those when developing their implementations. This lets you enforce the specification more reliably, because now instead of simply relying on a document, implementation developers will add those interfaces as code dependencies and rely on the compiler to check whether they implemented every method correctly (of course they still need to worry about the intended behaviour themselves). That said, this only adds to the confusion, because now actual code can also be called an API specification.
From my understanding, these two words are used almost interchangeably to refer to code that allows people to use a particular programming language to interact with an API. For example, many Python packages are labeled API wrappers or SDKs while providing essentially the same functionalities.
However, I am interested in hearing all of your opinions regarding the semantics of these two words.
Suppose you are developing a platform which has a web-based interface for its users and APIs for third-party developers. Something similar to Salesforce (or even Facebook).
Salesforce and Facebook, both platforms have normal web-based interface for its users and APIs for third party developers.
Ideally any API internally calls the same function which is being used by the web-based interface. For e.g. "Create a Project" button and "CreateProject" API calls the same "createProject()" function internally. So you can maintain the same version for both as in most cases they are tightly integrated.
Now sometimes you add a feature which makes you increment the minor version of the web-based interface but since you are not implementing that feature in API, API version should remain as is.
How do you handle such cases? Should you maintain separate versions of your web-based interface and APIs for your platform?
It Depends. Because It is difficult to offer a conclusive answer to this question. But I would share some ideas and drill-down some scenarios to help at best.
I would suggest there should be two versions of the api. internal apis and public apis. At a caller's end, they would be two physically distinct apis/end-points so that the security policies and a of lot of other things can be done without exposing much information as well as without relaying any responsibility on code to handle the distinction policy based on who's calling from where as that may quite easilyfail.
It is ok if both versions of the apis consolidate down the line to some extent without involving any security risk but a separate team of expert engineers can design this consolidation to be seamless yet safe. It's a trade-off of between code-reuse and everything else. This is very subjective and can turn into endless discussion. But the software evolves very well as result of this design process if it is agile and iterative.
The apis should be externalizable and inter operable. If the project is very large, then different teams working on separate parts of the project will interact with each other's work using internal apis only. No hanky-panky. No direct data access. Only apis.
This approach will help you create awareness of what's being done in the project across all teams if the apis are discoverable which I personally believe is a very good thing for collaborative team work. In fact it also helps in re-usability. Testing becomes unified and automated. Every team will become responsible for their own work and hence it should be easy to address accountability.
There's more stuff that can go in here but I think this is sufficient at a high level.
IF allowed, I would also read this question as
"Should you have purely service oriented architecture or not ?"
And my answer would be, **It Depends.**Because It is difficult to offer a conclusive answer to this...
Do not publish core function directly via API, instead create all API functions as proxy functions and all changes in core functions will be handled in proxy functions.
Change public api version if there is change in API input/output.
This way you could achieve code re-usability and it does not increase public API version frequently.
Edit:
If you are talking about software version number. My answer is Yes.
Can anyone think of the shortest possible definition for API, especially for someone who doesn't know programming? I'm using it in an essay and would like to footnote the definition for readers that might not understand the meaning or context of an app programming interface without tripping myself and the flow of the work.
From the wikipedia disambiguation page:
API, originally Advanced Programming Interface but now more commonly known by its near-synonym, Application programming interface, is any defined inter-program interface.
"any defined inter-program interface" is nice, but maybe a little broad for your purposes.
It's a lot of things (see wikipedia). But I usually think of it as the collection of tools and documentation that allow a user to interact with an external library or base of information.
Howstuffworks has a good definition:
An application-programming interface (API) is a set of programming instructions and standards for accessing a Web-based software application or Web tool.
I don't think API implies that the application must be web-based, but I otherwise like this definition.
This is probably a pretty basic question, but are APIs language specific. In General, do certain languages only work with certain APIs or should any language be able to talk to any API.
Specifically, Bing Webmaster Tools API has code example in C#. Does that mean I can't access the API in Python?
Thanks in advance!
If an API is exposed via HTTP and returns a language-neutral format like JSON or XML (which most popular third-party APIs do) then there's no restriction on what programming language you can use to parse the API responses.
Some API providers may provide specific client libraries e.g,. The Facebook JavaScript SDK, but this doesn't preclude using a different language, it just means you'll get less support in doing so.
An API always relates to just one language. However, sometimes interfaces or libraries are created so that they can be accessed by other languages. For example, XML is used for specifying listings in ebay. It is uploaded via HTTP. However there are many libraries, such as for PHP and Java, that abstract that into their terms, but keep a direct correlation between their usage and the XML they send.
It depends. Many APIs are designed for use with one particular language, for example functionality provided by a PHP framework. Having said that, it does not necessarily mean that in the future another language could start using them; for example IronPython making use of the .NET Framework.
It is very common for compiled libraries to be used by multiple languages, e.g. graphics libraries.
You can also have web-service based APIs (e.g. Bing in your example) which respond to HTTP requests. These could be invoked by any language, or anything in general.