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.
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.
When I am looking into approach's used for the development of API's, I came across multiple approaches like Code-First, API-First, Design-API-First.
I clearly understand Code-First approach how it is different from other two. But I am not able to get the exact difference between API-First and Design-First approach.
Summary from links:
API First:
API's are considered as first class citizens by the organization.
You design each of your APIs around a contract written in an API
description language like Open API for consistency, reusability, and broad
interoperability.
Design-API-First:
Describing every API design in an iterative way that both humans and computers can understand before you write any code.
API design-first is about the process of creating the API itself.
In design API first approach there will be lot of collaboration in designing of the API.
My understanding by far:
I feel 1 and 2 points of Design-API-First is saying same thing as API First because for example Open API specification is understood by both humans and computers. Is there anything more to it?
So, the only difference there will be collaboration added here by involving stakeholders, developers, customers etc?
So, when we use Design API First, we can say we are also using API-First?
References:
Probably I am able to get the exact context from the following links,
please use them and see if you can get the right understand of it and
address this question.
https://blog.stoplight.io/api-first-vs.-api-design-first-a-comprehensive-guide
https://blog.axway.com/product-insights/amplify-platform/application-integration/api-first-design-api-first
https://www.ecosmob.com/design-first-or-api-first-where-does-future-lies/
I am new to api automation and trying to understand few things. I have a web application and it has its APIs exposed for all basic functionality. But this product is also localized in other foreign languages.
My understanding:
The same APIs are used for all languages. APIs actually test functionality and not the UI. For most cases I need not test these APIs again for other languages.
My question:
Is it possible that there would be separate APIs exposed for different locales?
Or can I pass different locale(foreign language) strings as parameters to the same APIs?
Usually it's not the best practice to expose the various API for the different locales. The API that affected from the language may includes the language id. In this case the internal code may take in the consideration the different languages. Then you have to provide in your tests some variations of such language id.
Other case that you have to consider, the API that includes the strings as the parameter. In this case you will test the strings written in the different languages . Especially you should take in the account the Asia languages like Japanese and Chinese and right to left languages like Arabic and Hebrew.
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 ;)
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.