Hacker News Reader

Comment by sergiotapia | Hacker News Reader

I highly suggest you expose functionality through Graphql. It lets users send out an agent with a goal like: "Figure out how to do X" and because graphql has introspection, it can find stuff pretty reliably! It's really lovely as an end user. Best of luck!

View on HN

A proper REST API would also work without all the extra overhead of GraphQL.

People may dislike XML, but it is easy to make a REST API with and it works well as an interface between computer systems where a human doesn't have to see the syntax.

Depends mostly on efficiency: GraphQL (or Odata as a REST compliant alternative that has more or less the same functionality) provide the client with more controls out of the box to tune the response it needs. It can control the depth of the associated objects it needs, filter what it doesn't need, etc. This can make a lot of difference for the performance of a client. I actually like Odata more than GraphQL for this purpose, as it is REST compliant, and has standardized more of the protocol.

REST + Swagger I'd say

Swagger is critical. The graphql schema.json is very very good at helping ai's figure out how to use the service. Swagger evens that advantage.

How does Swagger help with REST though? By design, REST supports schemas and is self documenting, Swagger seems redundant.

Why would you need Swagger with REST?

Why would anyone need docs.

REST is self documenting.

Edit: for down voters, I'd be curious why.

I didn't downvote, but I'm thinking that you need endpoint discovery, bucket types, etc. Sure you could write a 1 page document describing the buckets at the root level, the relationships of the objects, etc., but why not let swagger do that for you at compile time?

I'm talking about actual REST here though, not RPC. Endpoint discover and typed schemas are core pieces of REST, we don't need Swagger or similar to fill in those gaps.

Not one of the downvoters, but I'd guess it's because this is only true with HATEOAS which is the part that 99% of teams ignore when implementing "REST" APIs. The downvoters may not have even known that's what you were talking about. When people say REST they almost never mean HATEOAS even though they were explicitly intended to go together. Today "REST" just means "we'll occasionally use a verb other than GET and POST, and sometimes we'll put an argument in the path instead of the query string" and sometimes not even that much. If you're really doing RPC and calling it REST, then you need something to document all the endpoints because the endpoints are no longer self-documenting.

But that is roughly the point here. If we still used REST we wouldn't need swagger, openapi, graphql (for documentation at least, it has other benefits), etc.

We solved the problem of discovery and documentation between machines decades ago. LLMs can and should be using that today instead of us reinventing bandaids yet again.

HATEOAS won't give you the basic nouns on which to work with

Right, you wouldn't need HTML at all for LLMs though. REST would work really well, self a documenting and discoverable is all we really need.

What we find ourselves doing, apparently, is bolting together multiple disparate tools and/or specs to try to accomplish the same goal.

Self documenting, but mainly to the architect who put ‘RESTful’ in the slide deck and called the documentation done.

I tried this recently and found the token overhead makes it prohibitive for any non-trivial schema. Dumping the full introspection result into the context window gets expensive fast and seems to increase hallucination rates compared to just providing specific, narrow tool definitions.

a friend (and colleague, disclaimer) pushed this recently to github. It passes data through a duck fb layer exactly to avoid context bloat:

https://github.com/agoda-com/api-agent

worth taking a look to see multiple approaches to the problem

Hasura is working on this approach: https://promptql.io

Reply on news.ycombinator.com