An Introduction to APIs

[shortrounddev2]

I still like REST. Most web applications are CRUD and don't need RPC. It also provides a standard and expected interface for 3rd party developers integrating with your code. If you're a small saas startup, nobody is going to waste their time learning the particularities of your protocol. Also makes the code very easy to read if you follow best practices for MVC style webapis with dependency injection. In my view, asp.net core is the apex of all RESTful frameworks

[irishloop]

Precisely right. Standards work cause everyone understands them. I know a PUT request is almost certainly an update of some kind. I know a POST makes something.

For most shit you wanna do, its view, edit, delete, its really not that complicated.

[delta_p_delta_x]

Web dev has so thoroughly revised the definition of 'API' it's not even funny.

Desktop, embedded, video games, HPC suddenly cried out in terror and were suddenly silenced.

[3cats-in-a-coat]

It's become just a word that means "interface endpoints". And frankly that's fine, it's what it is in the end. Whether in an OS, a website, or another platform.

[pdntspa]

It is even weirder to me how business has latched on to the term "APIs" like some kind of rabid dog biting into your ass

Like, this is a fundamental aspect of how I interact with my job and business has taken the term and elevated it into its own distinct thing

[rewmie]

> Web dev has so thoroughly revised the definition of 'API' it's not even funny.

What leads you to believe that a HTTP API does not meet the definition of a API?

[lazyasciiart]

One place I worked was unable to differentiate between libraries, SDKs and APIs - they just called all of them "an API". Infuriating.

[dinoreic]

REST is for noobs, JSON RPC is silent pro's choice :)

Make all requests POST and enjoy easy life without useless debates on should creation of resource be on POST or PUT or should you return HTTP status 404 or 200 if resource/document on server is not found (of course if should be 200 because request was a success, 404 should only be used it api method is not found).

I 100% agree with Troy Griffitts beautiful take https://vmrcre.org/web/scribe/home/-/blogs/why-rest-sucks

[atsjie]

JSON RPC:

- Everything is a POST, so normal HTTP caching is out of the question.

- JSON RPC code generators are non-existent or badly maintained depending on the language. Same with doc generators.

- Batching is redundant with HTTP2, just complicates things.

- Because everything is a POST normal logging isn't effective (i.e. see the url in logs, easy to filter etc). You'll have to write something yourself.

- Not binary like Protobufs or similar

But yeah, "the silent pro's choice"... Let's keep it silent.

JSON RPC is pretty much dead at this point and superseded by better alternatives if you're designing an RPC service.

[cle]

I don't like REST either, but JSON RPC is similarly hamstrung in some scenarios (examples: streaming, CDN caching, binary encoding).

I mostly dislike REST because nobody can agree on what it is and there are too many zealots who love to bikeshed. If you stick with the simple parts of REST and ignore the zealots, it's decent enough for many scenarios.

I've yet to find an RPC protocol that fills all requirements I've encountered, they all have tradeoffs and at this point you're better off learning the tradeoffs and how to deal with them (REST, JSON RPC, gRPC, WebSockets, etc.) and how they interact with their transports (HTTP/1.1, H2, QUIC, etc.), and then play the unfortunate game of balancing tradeoffs.

[nine_k]

ReST makes sense in certain cases, where resources are a tree (like a typical web site is a tree), with collections of leaves, and these leaves make sense by themselves. Then you can go full HATEOAS and reap some actual benefits from that.

Most of the time (like 99.9%) what you happen to need is JSON RPC. Even if some parts of your API surface look like they would fit the ReST model, the bulk does not. Ignore that, build a protocol along the lines of your subject area. Always return 200 if your server did not fail or reject the request, use internal status signaling for details. Limit yourself to GET and POST. Use HTTP as a mere transport.

[eikenberry]

+1 and I'll bump it up a notch... not only should you ignore REST you should ignore URLs. You want to write protocols, not APIs. Redis, for example, has a better "API" than any web API I've used. Easy to use, easy to wrap, easy to extend and version. HTTP is the other obvious example that I shouldn't have to go into.

If you'd like a good back and forth on the idea the classic c2 page is a great resource. http://wiki.c2.com/?ApiVsProtocol

[lenkite]

Ahh, the 2000's called. They want their SOAP back.

[kiitos]

This article defines REST incorrectly, and doesn't seem to understand the concept of HTTP methods, calling them verbs (arguably fine) and types (huh?) seemingly arbitrarily. Methods are a core part of HTTP -- just because you can't specify them explicitly in a browser as a user doesn't mean they're "cryptic curl arguments" or worth ignoring. I'm not sure I'd put too much stock into this perspective.

[dinoreic]

Thank you all for the great comments.

I want to emphasize that I was not thinking about JSON RPC as a specific protocol, but more as a JSON format to transfer data, similar to how REST APIs usually do, and some kind of "HTTP method agnostic remote procedure call", it does not have to be JSON RPC standard.

Personally, I am a fan of just having API Class-es + methods that automatically map to API calls with automatic api interface and doc builders. I find that it would be super strange if I had to prefix my internal methods with DELETE or PUT based on do they remove or add to some Array. Using that logic, why do that in APIs.

I just find it super strange that people want to mirror their app logic + error response codes to some protocol like HTTP – ridiculous :) Why not go even lower as TCP and use some of that spec for our client <> server API conn. Many people will laugh, but if you think about it, where is the difference?

[parentheses]

REST conventions only make sense for externally consumed APIs. Even for those, there's GraphQL.

[lprd]

I've been a REST API developer for a few years now. For whatever reason, I've never bothered dipping my toes in the RPC realm. This article resonated with me. Looks like I'll be building an RPC API in the near future.

[eska]

People are complimenting great technical writing here, but the first definition they provide is this:

> Technically, an API is just a set of rules (interface) that the two sides agree to follow. The company publishing the API then implements their side by writing a program and putting it on a server. In practice, lumping the interface in with the implementation is an easier way to think about it.

which is neither technically correct, nor easy to understand for a layperson. Compare to Wikipedia:

> An application programming interface (API) is a way for two or more computer programs to communicate with each other. It is a type of software interface, offering a service to other pieces of software.

[xtiansimon]

Ch6 “Linking resources together”

This is the most difficult topic for me. I struggle to discover, understand and implement in my code highly linked resources. How an API is organized or designed should be its own chapter IMHO

“We'll skip the details… […] REST practitioners are split on how to solve the problem of associating resources.”

UUUG

[lolive]

I think JSON [tree] data [with no fixed field for unique identifier, and no fkey referencing] is wrong. The lack of a proper type system+schema for data is wrong. The need for server-side query management makes any API supremely rigid.

Still some concerns to solve, for me, with REST APIs.

[JimDabell]

JSON covers syntax not semantics. This means you can build the formats you want on top of JSON by only describing the semantics without having to make decisions about syntax or write parsers.

[seveibar]

This article advocates for a traditional REST API design. At Seam, we use an API design that is like a RESTful RPC API, inspired by the API at Slack. I think that HTTP RPC and Slack-like APIs are much better than traditional REST because most consumers of an API use an SDK, and RPC-style HTTP APIs optimize for the SDK usage.

We also built a framework like trpc but for Next REST APIs[1] to get all the nice benefits of shared types but also the nice benefits of OpenAPI generation that typically come with RESTful frameworks https://github.com/seamapi/nextlove

[danjc]

Side point - has anyone got a better way to refer to a non-technical person than "non-technical"? I see they use that term in the intro and I use it to but seems a bit condescending.

[gabereiser]

The phrase you seek is called “Layman’s Terms” as defined: https://www.merriam-webster.com/dictionary/layman%27s%20term...

This avoids classification of the reader. To refer to someone who lacks the knowledge of a domain, they are a “layman”.

[mellosouls]

Layperson (layman in old money), though I don't think non-technical is normally condescending.

https://dictionary.cambridge.org/dictionary/english/layperso...

someone who is not an expert in or does not have a detailed knowledge of a particular subject

"bluffer" would be a humorous alternative.

[ch1234]

…. And that’s the entire world is in this state. Stop trying to create victims out of people for no reason.

Non-technical = not technical = does not have technical expertise.

Seems pretty logical to me

[macintux]

I’m fine with that, but seeing the term “normies” here sets my teeth on edge.

[vitorbaptistaa]

I usually use "non-developer", as that's what it means to me most of the time.

I find it hard to call a data analyst (for example), who can be highly technical, as a non-technical person.

[FractalHQ]

Muggle

[pranavpiyush]

Business user

[gibb0n]

noob

[vorpalhex]

When an accurate term seems condescending, sometimes that tells us more about ourselves than the word.

[foundart]

Very well written. However, I have never thought of the word 'endpoint' as used in API documentation in the way they describe it. I have no idea what the true origin is but I've always thought of it as the end of the journey the api request makes over the network.

> These are called endpoints simply because they go at the end of the URL, as in http://example.com/<endpoint_goes_here>.

[aggrrrh]

Basic REST and JSON RPC are very simple to start with, but have common problems when application gets bigger. How do you represent relations, pagination, filtering etc? My go-to specification for structuring JSON documents is https://jsonapi.org/ It covers most basic needs of a standard API.

[sibit]

> POST - Asks the server to create a new resource

> PUT - Asks the server to edit/update an existing resource

Maybe I've been doing it wrong all these years but it seems to me that the guides flip-flops the responsibility of POST and PUT. My understanding is that POST should edit/modify while PUT creates/replaces a resource.

[aridiculous]

There’s nothing like good technical writing.

[gumby]

Title should say "Web APIs".

[distantsounds]

(2014)

[ninja-ninja]

was talking to someone about how product managers should have an understanding of engineering and they said you should just know what apis are haha

[ChrisArchitect]

(2014)

[synergy20]

maybe call it 'cloud APIs'

It was written in 2014, not sure if it's still 'up to date' but the articles seem well written, concise, to the point.