How should we build the APIs of tomorrow?

As a creator of APIs, agents seem scary from an optimization/caching point of view.

I’d rather serve the same request 10,000 (which could be cached) than have 1,000 different agents making requests (which would be hard to cache).

Having dealt with something like this, I can assure you that no one wants to learn a new scripting language, which only runs on someone else's machine, and no ability to debug it.

Am I missing something, or do all of these use cases preclude immutability?

Forgive my ignorance, but how would this work in practice? Would agents be arbitrary code that a client would submit to an API, or would the agent be something that the server itself implements and manages in the backend?

EDIT: after some further reading of the mentioned threads, it appears to me like the idea is that we ship data with their own interpreters of some kind? I can help but fear this will cause even more JavaScript code to be pushed to the server. :)

Another aspect is intimating error conditions. One would be amazed on the myriad different ways an API fails and many do a poor job of conveying what went wrong, and how to recover, if possible.

I just wish people implemented their webhook systems well (a popular standard would be nice as well) - REST is fine, it mostly works and it's pretty standard.

In the context of regular REST API requests, it seems like all they're good for is batching requests together and filtering the results down to exactly what the client wants. That can be more directly accomplished in most cases with a query language like GraphQL or SQL. An SQL query is itself an example of an agent you send to a database server. Another option is an API for batching requests and specifying which fields you want on the responses (Google APIs support this).

I can imagine cases where users want to make potentially long-running queries against a large dataset with a richer agent than a regular query language supports (I'm imagining examples where the dataset is something like world terrain and navigational data, or the live state of everything in a large active multiplayer videogame world), but most of these cases I've thought of would strongly benefit from the data being pre-processed to have indexes so that the individual queries would be more efficient and not so long-running. ... Okay, actually that suggests a pretty radical and interesting example for an agent use-case: the client submits an agent to run on the server which reacts to data updates and maintains a set of indexes on the server, and then the client can issue requests directly to their agent running on the server to query the pre-processed data. (The dataset host may charge the user for the cpu+memory resources to continually execute the agent and for the storage resources to keep its indexes.) In the case that multiple users submit the same exact indexing agent to run over the same input data, the server could execute the indexing agent just once, and then offer a discount to the users for coordinating.

Another use-case for agents also involves retained long-running agents, as a replacement for webhooks. Currently I imagine a lot of service integrations look like this: service A is configured with a webhook to Zapier, and on receiving the webhook, Zapier calls back to service A to get some more data related to the webhook, and then calls service B to do something with the data from service A. This adds extra latency and a third party (Zapier) as a point of failure. If instead of a webhook, service A supported users submitting an agent that gets called with dataset updates, then a user could submit an agent to service A which processes update events and directly contacts service B. This cuts out all the roundtrips with Zapier. (If the agent only contacts service B on some events, then doing this would eliminate most communication between service A and the outside world!)

Related, I think agents fit in a lot of cases where latency is important:

* An obvious example is for a bot in an online bot-vs-bot game (like https://screeps.com/). Having the bots be implemented as agents submitted to the game server and executed there is a lot more efficient, dependable, and low-latency than having everyone implement their bots as clients on their computer which they must leave on and connected to the game server as long as they want their bot to be active. (Additionally, having the agents be under the game server's control allows the game to have mechanics involving making a temporary fork of the agent and see how it reacts to certain possibilities, without giving the mainline agent or the player the ability to know what hypotheticals it was tested on.)

* In a spreadsheet, you could consider a cell's formula as an agent. For comparison, consider the very naive solution of implementing formulas in a spreadsheet web-app as a webhook: the user implements the formula as a web service on their own server, and then enters the URL to their web service in the spreadsheet as the formula webhook for a cell. Every time the spreadsheet wants to show a formula result, it calls the web service (passing the formula inputs in the request) for it. This means when the user edits one of the inputs, their computer makes a request to the spreadsheet web-app server with the new input value for the new formula result, and then that server makes a request with the input values to the user's web service. By having the formula instead be an agent that's submitted to the spreadsheet web-app server, then obviously the roundtrip to the user's web service can be cut out, but you can go even further and cut out all the roundtrips on edits by having the spreadsheet web-app server send the agent directly to the client to execute there on changes. Then a user tweaking values in the spreadsheet can immediately see how it affects the formula results without waiting on communication to any servers.

Another use-case for agents I've thought of involves enabling account delegation with arbitrary restrictions: imagine I want to have a counter in a spreadsheet on google docs that I want to allow my friend (or an external service, etc) to increment. I don't want to allow my friend to be able to access anything else about my account, view the spreadsheet, or change the counter in any way other than increment it. Maybe even I want to enforce a rate-limit. The standard solution for this would be for me to make a web service running on my own server which has an "increment" endpoint, and my web service has access to my google account credentials (or maybe an API key that gives it access to fully read+write my spreadsheets). This isn't great because it means I need to maintain a separate server, it's an added point of failure, it's an extra hop of latency, and if it's hacked/stolen/etc, then someone gets access to my account that lets them do more with my account than increment a value. Instead, it would be convenient if I could upload an agent that lives next to my Google docs data that exposes an "increment" endpoint. An agent-created endpoint like this could be set to be either publicly available, available to certain users, or available to requests with a specific API token.

---

I think the biggest point of agents is that they let the logic come to the data. It seems like the number one practical motivator is latency, though there are side benefits like increased availability for the logic and allowing users to avoid needing to source their own always-on webserver or external service just for their logic to live on. It is a big paradigm shift though, and I'm not sure most of my use-cases are enough to warrant it alone. The very latency-sensitive examples like the formula cell and game bot examples seem obviously useful to be worth it, but the rest seem like they would only be done if we had very high latency networks (maybe a deep space network would find these strategies useful) or if we had a widespread computing model already in place that made it easy and safe for services to implement.

Not to mention, a lot of computing is not done with your own data. Sure, my pictures could stay in my house, and I could access my friends' pictures with relatively simple APIs. But I also need to work with Wikipedia, with StackOverflow's database of answers, with Amazon's database of products, with YouTube's and Netflix's video databases etc.

So you get some economies of scale ... I wonder what the "breakeven topology" would look like.

The ones that I do have some issues that he doesn't cover, and a whole lot of issues that he discusses are of no concern to me.