From fe4a915e788f7da13a1d8cef4f1aff82c79fd7b9 Mon Sep 17 00:00:00 2001 From: Cyber MacGeddon Date: Sat, 28 Dec 2024 14:18:07 +0000 Subject: [PATCH] API docs --- docs/apis/README.md | 53 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 docs/apis/README.md diff --git a/docs/apis/README.md b/docs/apis/README.md new file mode 100644 index 00000000..5ad76b6d --- /dev/null +++ b/docs/apis/README.md @@ -0,0 +1,53 @@ + +# 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 +