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.
Related
could you please explain the difference between interface and API?
I was looking for this information here and using google but I only find a special information for Oracle.
What I'm looking for is the general difference.
Much appreciated!
Update:
thank you all for the answers. My question was kept deliberately general because I
1) do not have the detailed information about the used programming languages (question based on a short information about one vendor's implementation in my project);
2) I wanted to understand the general high-level difference between the both terms.
Without further context, your question is a bit broad; but lets try; by looking up the definition of API on wikipedia:
In computer programming, an application programming interface (API) is a set of subroutine definitions, protocols, and tools for building software and applications.
Then: API stands for application programming interface; indicating that well, an API contains all elements (plural!) required to create an application which wants to interact with the component behind that API.
Whereas an interface in its stricter sense typically denotes a "single specific entity"; like the List interface in java describes an ordered collection (without providing details about specific implementation).
But of course, there are certain commonalities - both terms are about the description of the "boundary" of a "system". Long story short: there is simply no sharp, precise separation between those two concepts. Thus, when using those words within a group of people, you might want to first "step back" and discuss terminology - to ensure that all people involved have the same understanding of such terms. Or as DDD puts it: you want to create a Ubiquitous Language in which such terms have a clear, well defined meaning.
Finally: it is also worth mentioning that the term interface has different meanings when using different programming languages. In Java, an interface is really a concept embodied within the language core; where as in C++, an "interface" would probably be seen as the content of a single header file; leading to subtle but important "flavors" of "interface" for those two languages.
Edit:
Both, interface and API should not expose (too much?!) of the internals to the outside world.
Generally speaking, an API outlines a "component" (a complete "application" for example); whereas an interface might outline a "smaller" entity".
For your other refinement, about one company providing the API, and another the interface - I cant say anything. Because; as others have explained too: the definitions for those terms are really to unclear/fuzzy. We would need to know much more about the application and its requirements to even comment on your statement here.
The question "what is the difference between X and Y" is only meaningful when X and Y have single meanings and strict definitions. But "interface" and "API" do not have either single meanings nor strict definitions, so one cannot tell what is the difference between them.
For the most part, there is no difference, but there exist certain contexts where one would be suitable to use, while the other would be less suitable, or even unsuitable.
So, for example, a class implements an interface, never an API. On the other hand, an entire software system is more likely to be said to expose APIs rather than interfaces, though to say interfaces in this case would not be wrong either.
I wish there was some easy distinction, like "interfaces are small-scale, APIs are large-scale", or "interfaces are more specific, APIs are more nebulous", but there is no such distinction.
The current Swagger spec claims that Swagger is used to describe and document RESTful APIs. I think this is not the case rather I think Swagger is useful for simply describing a HTTP API for a few reasons:
The Swagger spec has elements like Path and Definition but they don't clearly map to the REST data elements like resource, representation, and media types. My thought is that to effectively describe a REST API, you should be required to define the explicit REST data elements in the context of your API.
Hyperlinks are not first class objects in the Swagger spec and thus hyperlinks and their critical descriptive attribute, link relation, can easily be left out. In fact, hyperlinks are not mentioned at all.
HTTP paths are at the front-and-center which seems to be a clear violation of a point Fielding made in his famous blog post:
A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server)
Essentially, I think APIs defined using the Swagger 2.0 spec leads you to design an API that isn't constrained by HATEOAS which would violate REST.
Is this correct or am I missing something?
I absolutely agree. Swagger is not well suited for defining truly REST compliant APIs. The problem is that people define REST in a lot of different ways. The Richardson Maturity Model helps describe these different definitions.
Level 0 REST APIs pipe all requests through one URI and one HTTP method. This level includes any API that uses HTTP no matter how limited. In practice, people rarely call this REST anymore, but it does happen (probably for marketing reasons).
Level 1 REST APIs employ many URIs, but still only use one HTTP method (usually POST). Again, in practice, this rarely called REST anymore, but there was a time when it was common.
Level 2 REST APIs are where the concepts of resources and uniform interface are introduced. These APIs have URIs that represent resources and use the HTTP methods to perform CRUD operations on those resources. In practice, people started referring to this as RESTful to distinguish it from Level 1. I credit Ruby on Rails for popularizing this interpretation of REST, but I can't back that up. In any case, when Swagger claims to be for describing RESTful APIs, Level 2 is the definition they are referring to.
Level 3 REST APIs are fully compliant with the REST architectural style. In particular, they are characterized by using HATEOAS. All of the concerns you laid out in your question aren't taken into account until this level. In practice, some people have started calling these Hypermedia APIs to distinguish them from the now entrenched definition of RESTful as referring to the Level 2 definition.
I would say that your understanding of REST is more "mature" than that used by Swagger and therefore, you will only be frustrated trying to use it (I speak from experience). My personal choice for defining Hypermedia APIs is JSON Hyper-Schema. It can't match all the great tools Swagger has, but it allows me to write APIs at Level 3. That's more than I can say for any of the popular API definition languages out there.
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.
As i grow in my professional career i consider naming conventions very important. I noticed that people throw around controller, LibraryController, service, LibraryService, and provider, LibraryProvider and use them somewhat interchangeable. Is there any specific reasoning to use one vs the other?
If there are websites that have more concrete definitions that would be great.
In Java Spring, Spring Boot and also .NET you would have:
Repository: persist data in the database and perform SQL queries.
Service: contain most of the business logic
Controller: define REST endpoints, which contains as little logic as possible.
Conceptually this means that the WHAT (functional) is separated from the HOW (technical) as much as possible. The services try to stay technologically neutral. By contrast a controller only wants to define an external contract for communication. And finally the repository only wants to facilitate the access to the database.
Organizing your code in this way keeps the business logic short, clean and maintainable. Unfortunately it is not always easy to keep them separated. e.g. It is tempting to pollute or enrich your objects with meta-data in the form of decorators/annotations. (e.g. database column name and data type).
Some developers don't see harm in this and get away with it. Others keep their objects strictly separated and define multiple sets of objects.
The objects for the database are often referred to as "entities" or "models".
For a REST controller they are often referred to as DTOs which stands for data-transfer-object.
Having multiple objects means that you need Mappers to convert one type of object to another. Some frameworks can do this for you (e.g. MapStruct).
It would be easy to claim that strictness is always a good thing, but it can slow you down. It's okay to strike a balance.
In Node.js, the concepts of controllers and services are identical. However the term Repository isn't used very often. Instead, they would call that a Provider or sometimes they would just generalize Repositories as a kind of Service.
NestJS has stronger opinions about this (which can be a good thing). The naming conventions of NestJS (a Node.js framework) are strongly influenced by the naming conventions of Angular, which is of course a totally different kind of framework (front-end).
(For completeness, in Angular, a Provider is actually just something that can be injected as a dependency. Most providers are Services, but not necessarily. (It could be a Guard or even a Module. A Module would be more like a set of tools/driver or a connector.)
PS: Anyway, the usage of the term Module is a bit confusing because there also are "ES6 modules", which is a totally different thing.)
ES6 and more modern version of javascript (including typescript) are extremely powerful when it comes to (de)constructing objects. And that makes mappers unnecessary.
Having said that, most Node.js and Angular developers prefer to use typescript these days, which has more features than java or C# when it comes to defining types.
So, all these frameworks are influencing each other. And they pretty much all agree on what a Controller and a Service is. It's mostly the Repository and Provider words that have different meanings. It really is just a matter of conventions. If your framework has a convention, then stick to that. If there isn't one, then pick one yourself.
These terms can be synonymous with each other depending on context, which is why each framework or language creator is free to explicitly declare them as they see fit... think function/method/procedure or process/service, all pretty much the same thing but slight differences in different contexts.
Just going off formal English definitions:
Provider: a person or thing that provides something.
i.e. the provider does a service by controlling some process.
Service: the action of helping or doing work for someone.
i.e. the service is provided by controlling some work process.
Controller: a person or thing that directs or regulates something.
i.e. the controller directs something to provide a service.
These definitions are just listed to the explain how the developer looks at common English meanings when defining the terminology of a framework or language; it's not always one for one and the similarity in terminology actually provides the developer with a means of naming things that are very very similar but still are slightly different.
So for example, lets take AngularJS. Here the developers decided to use the term Controller to imply "HTML Controller", a Service to imply something like a "Quasi Class" since they are instantiated with the New keyword and a Provider is really a super-set of Service and Factory which is also similar. You could really program any application using any of them and really wouldn't lose anything much; though one might be a little better than another in certain context, I don't personally believe its worth the extra confusion... essentially they are all providers. The Angular people could have just defined factory, provider and service as a single term "provider" and then passed in modifiers for things like "static" and "void" like most languages and the exact same functionality could have been provided; this would have been my preference, however I've learned not to fight the conventions and terminology of the frameworks your working no matter how strongly you disagree.
Looking myself too for a more meaningful name than Provider :)
And found this useful post
Old dev here that stumbled on this. My opinion and how I’ve seen it used over the last 20 years shows that it varies by language but the Java C# crowd mostly uses them as follows.
A service handles business logic and deals with domain objects. You find services in controllers and other services.
A repository does NOT handle business logic, but instead acts like a pool of domain objects (with helper methods for finding or persisting them. Services often contain repositories. Repositories often contain a context and are responsible for mapping from infrastructure shaped data to domain shaped data if the definitions have drifted apart. Controllers also often contain repositories for crud endpoints.
A context handles infrastructure the domain owns. Most often this is a database, but context means that anything that touches this data does so through (in) this context. A context returns infrastructure shaped data. A repository often contains a context. Context directly in services is sometimes appropriate. Context in controller is a hard no.
A provider provides access to infrastructure some other app owns. Most often these are rest apis, but can also be kafka streams or rpc classes that read data from or push data to someone else. If the source of truth for some of your domain objects fields changes you will probably see a provider next to a context in your repository, and your repository handles insulating the rest of your code from that change. Providers that provide rpc functionality are often found in services. In micro services or gateways or vertical slice architecture you sometimes see providers directly in controllers.
One old guy’s opinion but I hope it helps.
I've seen several questions revolving around that theme on SO, but no answer that really satisfies me.
I'm trying to put words on things I feel without always being able to express them clearly enough to convince people around me. Might be that I'm wrong. Might be that my understanding is not deep enough to find proper arguments.
How would you contrast developing applications according to a "service oriented approach" instead of a "traditional" API approach?
Let's be totally clear here that, by services, I don't necessarily mean Web Services.
Here are some differences I see. Please correct me if I'm wrong:
a service is a "living thing" that you can talk to, according to a given and explicit protocol. A service has its own runtime while a library uses the runtime of your application. You can move that "living thing" wherever you want
a library allows code-based integration, while services traditionally use a message-based integration (however, nothing really prevents you to write a library based on exchanging messages)
services are discoverable
contracts are explicit and expressed "outside" the running code
services are autonomous (but here again, you could write autonomous APIs, couldn't you?)
boundaries are explicit
What am I missing here? What else really distinguishes services from a high-level API?
Service oriented architecture implies that the exposed interface does not live on the same host where the client runs and the service is completely decoupled from the client code (loose coupling). You can easily call an API by loading the necessary library and executing your code, on the same node. Rather than defining the API, service oriented architecture is focusing on the functionality, many times you can access the same feature using different protocols.
I would go for the loose code coupling if there was anything which would distinguish SOA and AOA.
You have covered most important points. I would add one :
Usually, a Service is stateless. Each Service request is independent. This is in contrast to a library interface where you may make certain calls in a sequence to get the desired result.