|
| 1 | +# HTTP |
| 2 | + |
| 3 | +You connect to a gateway via standard HTTP 1.1. While connecting to a gateway, the path holds pointers to the type of gateway, the tenant, the application id, and the gateway name. |
| 4 | + |
| 5 | +The URL structure is http://\<control-plane-domain>:\<api-gateway-port>/api/gateways/\<gateway-type>/\<tenant-name>/\<application-id>/\<gateway-id>. |
| 6 | + |
| 7 | +Authentication (`credentials,test-credentials`), options (`option:`) and parameters (`param:`) are expected to be in the query string. HTTP headers are ignored by the API Gateway service. |
| 8 | + |
| 9 | + |
| 10 | +## Produce messages |
| 11 | + |
| 12 | +To produce messages via HTTP, configure a `produce` gateway: |
| 13 | +```yaml |
| 14 | + |
| 15 | +gateways: |
| 16 | + - id: "user-input" |
| 17 | + type: produce |
| 18 | + topic: "questions-topic" |
| 19 | + parameters: |
| 20 | + - sessionId |
| 21 | +``` |
| 22 | +
|
| 23 | +Once a gateway is configured, you can use whatever HTTP client you prefer to connect. This is an example with Curl: |
| 24 | +
|
| 25 | +```bash |
| 26 | +curl -X POST --body '{"value": "hello"}' "http://localhost:8091/api/gateways/produce/my-tenant/my-app/user-input?param:sessionId=12543yusi1" |
| 27 | +``` |
| 28 | +
|
| 29 | +You can also use the LangStream CLI: |
| 30 | +
|
| 31 | +```bash |
| 32 | +langstream gateway produce my-app user-input --protocol http -v '{"value": "hello"}' -p sessionId=12543yusi1 |
| 33 | +``` |
| 34 | +
|
| 35 | +
|
| 36 | +## Produce messages and wait for a message |
| 37 | +
|
| 38 | +To produce messages via HTTP and wait for a message, configure a `service` gateway: |
| 39 | +```yaml |
| 40 | +
|
| 41 | +gateways: |
| 42 | + - id: "user-input-await" |
| 43 | + type: service |
| 44 | + parameters: |
| 45 | + - sessionId |
| 46 | + service-options: |
| 47 | + input-topic: inputs |
| 48 | + output-topic: results |
| 49 | +``` |
| 50 | + |
| 51 | +Once a gateway is configured, you can use whatever HTTP client you prefer to connect. This is an example with Curl: |
| 52 | + |
| 53 | +```bash |
| 54 | +curl -X POST --body '{"value": "hello"}' "http://localhost:8091/api/gateways/service/my-tenant/my-app/user-input-await" |
| 55 | +``` |
| 56 | + |
| 57 | +The timeout of the wait is the TCP timeout of the connection, which is usually 30 seconds (may vary depending on the http client). |
| 58 | + |
| 59 | +## Proxy service agent requests |
| 60 | + |
| 61 | +To proxy requests to a specific `service` agent via HTTP, configure a `service` gateway: |
| 62 | + |
| 63 | +```yaml |
| 64 | +gateways: |
| 65 | + - id: "my-service" |
| 66 | + type: service |
| 67 | + parameters: |
| 68 | + - sessionId |
| 69 | + service-options: |
| 70 | + agent-id: my-service-agent |
| 71 | + |
| 72 | +``` |
| 73 | + |
| 74 | +A service agent might look like this in the pipeline configuration: |
| 75 | +```yaml |
| 76 | +pipeline: |
| 77 | + - name: "Start my service" |
| 78 | + id: my-service-agent |
| 79 | + type: "python-service" |
| 80 | + configuration: |
| 81 | + className: example.ChatBotService |
| 82 | +``` |
| 83 | + |
| 84 | + |
| 85 | +Once a gateway is configured, you can use whatever HTTP client you prefer to connect. This is an example with Curl: |
| 86 | + |
| 87 | +```bash |
| 88 | +curl -X POST \ |
| 89 | + --body '{"value": "hello"}' \ |
| 90 | + --H 'Authorization: Bearer XXX' \ |
| 91 | + "http://localhost:8091/api/gateways/service/my-tenant/my-app/my-service/the/custom/path?service-param-1=yes" |
| 92 | +``` |
| 93 | + |
| 94 | +The final part of the URL, query string, HTTP method, and headers will be sent to the service agent. |
| 95 | + |
| 96 | + |
| 97 | +In the above case, the agent service will receive an equivalent request of: |
| 98 | + |
| 99 | +``` |
| 100 | +curl -X POST \ |
| 101 | + --body '{"value": "hello"}' \ |
| 102 | + --H 'Authorization: Bearer XXX' \ |
| 103 | + "http://localhost:8000/the/custom/path?service-param-1=yes" |
| 104 | +``` |
| 105 | + |
| 106 | + |
| 107 | +The `credentials`, `test-credentials`, `option:xx`, `param:xx` are stripped out from the routed requests. |
| 108 | +If the gateway has authentication enabled, it will be performed as for other gateways. |
| 109 | + |
| 110 | +POST, GET, DELETE and PUT are all supported. |
| 111 | + |
| 112 | +Leveraging the API gateway to expose your service solves authentication, HTTPS, high-availability, and scalability out of the box. |
0 commit comments