trustgraph/docs/apis/README.md

# TrustGraph APIs

## Overview

If you want to interact with TrustGraph through APIs, there are 3
forms of API which may be of interest to you:

### Pulsar APIs

Apache Pulsar is a pub/sub system used to deliver messages between TrustGraph
components. Using Pulsar, you can communicate with TrustGraph components.

Pros:
  - Provides complete access to all TrustGraph functionality
  - Simple integration with metrics and observability

Cons:
  - Integration is non-trivial, requires a special-purpose Pulsar client
    library
  - The Pulsar interfaces are likely something that you would not want to
    expose outside of the processing cluster in a production or well-secured
    deployment
    
### REST APIs

A component, `api-gateway`, provides a bridge between Pulsar internals and
the REST API which allows many services to be invoked using REST APIs.

Pros:
  - Uses standard REST approach can be easily integrated into many kinds
    of technology
  - Can be easily protected with authentication and TLS for production-grade
    or secure deployments

Cons:
  - For a complex application, a long series of REST invocations has
    latency and performance overheads - HTTP has limits on the number
    of concurrent service invocations
  - Lower coverage of functionality - service interfaces need to be added to
    `api-gateway` to permit REST invocation

### Websocket API

The `api-gateway` component also provides access to services through a
websocket API.

Pros:
  - Usable through a standard websocket library
  - Can be easily protected with authentication and TLS for production-grade
    or secure deployments
  - Supports concurrent service invocations

Cons:
  - Websocket service invocation is a little more complex to develop than
    using a basic REST API, particular if you want to cover all of the error
    scenarios well

## Further reading

- [TrustGraph websocket overview](websocket.md)
- [TrustGraph Pulsar overview](pulsar.md)
- API details
  - [Graph RAG](api-graph-rag.md)
  - [Document load](api-document-load.md)
  - [Agent](api-agent.md)
  - [Embeddings](api-embeddings.md)
  - [Text completion](api-text-completion.md)