What, exactly is the basic unit of an api?
-
@DogsB said in a Lounge thread (no quotes or links for that reason) something about a project having about X apis.
This raises, for me, a question I've had before--is the unit of "api"
- a service/collection of related endpoints or public methods (possibly grouped into an interface definition).
- a single endpoint or method.
Imagine a simple HTTP "REST" server that has 3 endpoints:
GET /widgets-> returning some kind of collection of widgets
POST /widgets, taking in a message body and doing something to the widgets collection with it, probably inserting it into the collection
DELETE /widgets/<id>, which removes a single widget from the collection.Is this:
- one
widgetapi - three separate apis.
-
@Benjamin-Hall tough one. You can segment it down endpoints (so, 3), you can segment it by logical divisions (widgets, so 1 strictly in this case)
But you really want to consider it slightly larger.
Assume on top of your 3 widgets endpoints, you also have a set of /foobar endpoints (same CRUD ones for simplicity)
This is 6 endpoints, 2 logical divisions (widgets, foobar), quite possibly one actual physical service supplying both (#monolithforever)
But I think the answer is how people “think of it”. Facebook has its Graph API, and it has a bajillion endpoints, a fuckton of logical entity groupings etc etc but people refer to it just as “the Graph API” because it’s all just facets of the data hose.
Then just to be helpful, sometimes people conflate the logical subdivisions, e.g. “the posts API”
I personally find the most appropriate definition is to group it into logical units for context and go from there - so you have a widgets API, a foobar API, and these collectively are your API.
Humans are messy, Conway’s law implies that what we will build will be equally messy.
-
I look at it from the traditional viewpoint of the API being the collection of functions. The acronym stands for Application Programming Interface. You use this one API to interact with the application. A program can have more than one API, usually in a transition period, like when OnBase struggled to move from COM to .NET, but it's not ideal.
Like I think @Arantor is suggesting, webservices with these endpoints really screwed that up. You don't have a single application anymore. You have functions pulled out and made into their own little programs. Except the little programs are virtually useless unless combined with the other little programs. Like an application, except shattered into a thousand pieces.
-
@Zenith that was a shitshow even in the SOAP days though at least in the SOAP days a single API published its WSDL with what it did, so you could point to that and call it “the API”.
-
@Arantor My personal gut feeling is that if I have
- 35
/fooendpoints, all related to each other but only partially (or not at all) tobar - 56
/barendpoints, all related to each other but only partially tofoo - 12 endpoints that require both
fooandbarobjects
I'd say it differently depending on what I'm talking about. I'd never say I had "35 foo apis". I might say "I have 3 main apis, the Foo api, the Bar api, and the WTF-is-wrong API." If I'm in a context where only
foois relevant, I might talk about sub-groupings of endpoints: "use thefoo frobnicatorapi for that, not thefoo retrofunctorapi for that", talking about those X endpoints over there.If a class implements 3 well-defined interfaces, I'd think (but probably wouldn't say, because I've done so much web dev that "api" and "HTTP REST-like api" have too much connection in my brain) about the "api surface" for the class being really 4-fold--one for each interface and one for the (inevitable, sadly) bits that don't fit into any of the interface definitions but are still public.
- 35
-
@Benjamin-Hall compare with projects. What is a project? How many applications are in a single project? How many projects are in a single application?
On one hand, there is no good answer because all those terms are too fuzzy to say anything definite about them.
On the other hand, for any specific unit of work, every developer instinctively knows whether it's still the same project they worked on yesterday or a different one. We also instinctively know when the management artificially inflates the projects count or artificially joins multiple projects under a single name for office politics reasons.
Same with APIs. It's hard to define how many APIs there are, but it's very easy to actually count them and give you an answer for a specific case. for the example in OP, it's obviously just one.
-
@Benjamin-Hall Pretty much.
I might vary it based on who I’m talking to and what I’m trying to communicate. I could easily see it described as “the API” in collective in some contexts, but by logical domain (the Foo, the Bar) etc is usually the place you want to be because it defines the scope of what you’re talking about to whoever you’re talking at, and that’s usually the bit that matters.
-
@Zenith That actually adds yet another meaning for this term for me--
I might say that a linux program "only has a unix-like api", meaning it expects to get commands from a "command line" (or equivalent) and outputs them similarly. Effectively "CLI as API surface".
But then I also talk about the "api surface" of a program, application, or even part of an application. Meaning "all the things I expect someone outside this module/program to be able to poke programmatically."
As a side note, my company's core product has 3 "APIs"--
- A SMTP-based one, which is ~75% of all traffic. We take in emails, parse them (differently for each customer or set of customers), and do something with the data.
- A SNPP-based one...which is basically the same idea but fed differently.
- A HTTP-based one, which skips all the parsing and does a bunch of special-snowflake stuff (doesn't store the raw data anywhere, doesn't use agency parsers, etc). This is used only internally, by our web interface and client apps for self-dispatch.
-
@Benjamin-Hall alternative interfaces for the same system definitely count as different APIs. Even if they had the exact same behavior.
I'm inclined to say there's also one API per service, so two related services are still two separate APIs, but we live in the microservices world now so there's like 60 separate services driving just one API.
-
@Benjamin-Hall said in What, exactly is the basic unit of an api?:
I might say that a linux program "only has a unix-like api", meaning it expects to get commands from a "command line" (or equivalent) and outputs them similarly. Effectively "CLI as API surface".
From the Windows world, I view it as a failure of your real API (exposed functions) if you're using the command line from a program because, to me, the command line is a user interface.
Edit: But I would agree that SMTP, SNPP, and HTTP access would be three APIs.
-
@Zenith said in What, exactly is the basic unit of an api?:
@Benjamin-Hall said in What, exactly is the basic unit of an api?:
I might say that a linux program "only has a unix-like api", meaning it expects to get commands from a "command line" (or equivalent) and outputs them similarly. Effectively "CLI as API surface".
From the Windows world, I view it as a failure of your real API (exposed functions) if you're using the command line from a program because, to me, the command line is a user interface.
Unix has always been one huge failure on the I front, whether it's U or AP.
-
-
@Benjamin-Hall said in What, exactly is the basic unit of an api?:
Is this:
- one
widgetapi - three separate apis.
If any sane implementation of them would require them to know intimately about each others' internals, I'd call them a single API. An API never was required to only ever be a single function call...
- one
-
@Gustav said in What, exactly is the basic unit of an api?:
On one hand, there is no good answer because all those terms are too fuzzy to say anything definite about them.
Yeah, I can accept whatever definition someone wants to use so long as they make it clear. But I'd also wonder why they care about this unit.
-
@boomzilla said in What, exactly is the basic unit of an api?:
But I'd also wonder why they care about this unit.
To be precise, my questioning here was mostly around understanding what it means to the speaker for a project to have a couple serverless functions with "hundreds of apis". Because that just hits my sense of the English language as wrong--that or I'm fundamentally misunderstanding how certain words are used. It just made me go "huh?"
-
@Benjamin-Hall said in What, exactly is the basic unit of an api?:
@boomzilla said in What, exactly is the basic unit of an api?:
But I'd also wonder why they care about this unit.
To be precise, my questioning here was mostly around understanding what it means to the speaker for a project to have a couple serverless functions with "hundreds of apis". Because that just hits my sense of the English language as wrong--that or I'm fundamentally misunderstanding how certain words are used. It just made me go "huh?"
And I don't think anyone but him can answer that question for you. But I think the more important question, "Is this person sane and / or competent?" is answered by the inclusion of "serverless" right there.
-
@Benjamin-Hall said in What, exactly is the basic unit of an api?:
@boomzilla said in What, exactly is the basic unit of an api?:
But I'd also wonder why they care about this unit.
To be precise, my questioning here was mostly around understanding what it means to the speaker for a project to have a couple serverless functions with "hundreds of apis". Because that just hits my sense of the English language as wrong--that or I'm fundamentally misunderstanding how certain words are used. It just made me go "huh?"
I'm with you here. Either that's load of bull, or those serverless functions could really use a server (or several).
-
@Zenith said in What, exactly is the basic unit of an api?:
@Benjamin-Hall said in What, exactly is the basic unit of an api?:
I might say that a linux program "only has a unix-like api", meaning it expects to get commands from a "command line" (or equivalent) and outputs them similarly. Effectively "CLI as API surface".
From the Windows world, I view it as a failure of your real API (exposed functions) if you're using the command line from a program because, to me, the command line is a user interface.
I found out yesterday that when using tar with -z, to do gzip on the archive, tar doesn't use a gzip binary – it forks to
/bin/sh -c gzip, and then that forks togzip. Three running processes for the work of two.
-
@kazitor It's probably just using
popen()as that's an easy thing to just shove in there. Yes, that's howpopen()works...
-
@Arantor said in What, exactly is the basic unit of an api?:
at least in the SOAP days a single API published its WSDL
The web world caught up and now has an equivalent: an OpenAPI specification - often generated with Swagger. True to both of their histories, WSDL was an XML file and OpenAPI uses json.
So, you can still use the same metric - if it's documented in a single OpenAPI spec, then it's a single API. Most commonly, these are built from a single pile of source code (referred to as a project in all of the technologies I use, but I'm sure someone uses different terminology).
Usually when people bother to say "We have three APIs", they either means that they support three generations of doing the same thing, but have kept the old ones around because APIs are used for application-to-application communication and you have to give the consumers time to transition. Or they mean that their back end has consumers from three different perspectives (i.e. Customers, Vendors, and internal code) that have different levels of access and different needs and it was decided to make independent APIs for the three.
A big implementation detail that is usually true for "an API" is that it uses one method of authentication across all endpoints. Go here, get a token, and tack that token to the header of all calls. The scope of "all calls" would be an API.
-
@Jaime except when people do “clever” shit, in which case all sensible bets are off.
The theory’s good and it sounds like we here are all broadly in agreement which is somewhat unexpected (and as usual, it’s everyone else who are wrong)
-
@Arantor said in What, exactly is the basic unit of an api?:
except when people do “clever” shit, in which case all sensible bets are off
It was ever so. When some smartass sabotages common sense, all sorts of weird stuff turns up. My contribution to that pile of trouble was through putting proper auth on a websocket (i.e., so things need to auth to persuade the service to switch protocol in the first place). Easy to implement in Spring, and everything supports it on the client side... except browsers because they just omitted to support any way of providing the API key header by any non-URL mechanism. In my case, I didn't care — browsers were a use-case I didn't need to support for that part of the webapp, and I don't think anyone's written the protocol client that sits on top of that in anything other than Python and Java in the first place — but it definitely seems like the weirdest sort of omission. Anyway, that's definitely a place where "is it an API?" is getting somewhat flexible (though in my case I'd say it is clearly part of one, as there is various bits of necessary wiring up behind the scenes). Which to me means that an API doesn't need to be single-protocol.
-
'ing for a bad joke (hey it's not a Help thread so that's OK!).@Benjamin-Hall asked What, exactly is the basic unit of an api?
The answer is easy, it's kg/m^3.
-
The API gravity scale is based on errors in early implementations of the Baumé scale.
How fitting.
-
@error said in What, exactly is the basic unit of an api?:
This was the essence of a dispute I had with a philosopher friend. He maintained that buying the result of an action of type X did not cause X, because of the heap paradox. My solution was what T-Rex implied, that buying the result of an action of type X did in fact cause actions of type X, because even though not everyone has the same definition of heap, that statistically the more grains in the pile the more likely that any person will call it a heap.
This friend did his dissertation on the Liar's Paradox.
-
@jinpa said in What, exactly is the basic unit of an api?:
buying the result of an action of type X
I fail to see the connection between this and heap paradox. I'm 90% sure I misunderstand what you mean by buying. An example please?
-
@Gustav presumably: demand causing supply.
-
@Gustav said in What, exactly is the basic unit of an api?:
@jinpa said in What, exactly is the basic unit of an api?:
"buying the result of an action of type X"I fail to see the connection between this and heap paradox. I'm 90% sure I misunderstand what you mean by buying. An example please?
Here, "buying" into the argument. That is, agreeing with it.
