Comment by sergiotapia
14 days ago
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!
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.
1 reply →
Why would you need Swagger with REST?
9 replies →
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