Jina REST API Specification¶
Note
To use REST API support, you need to install jina via pip install "jina[http]" or use the corresponding feature-enabled Docker image.
Interface¶
POST an IndexRequest¶
# POST an IndexRequest to `http://0.0.0.0:5555/api/index`
curl -X POST -d '{"first_doc_id": 5, "data": ["data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAIAAABLbSncAAAA2ElEQVR4nADIADf/AxWcWRUeCEeBO68T3u1qLWarHqMaxDnxhAEaLh0Ssu6ZGfnKcjP4CeDLoJok3o4aOPYAJocsjktZfo4Z7Q/WR1UTgppAAdguAhR+AUm9AnqRH2jgdBZ0R+kKxAFoAME32BL7fwQbcLzhw+dXMmY9BS9K8EarXyWLH8VYK1MACkxlLTY4Eh69XfjpROqjE7P0AeBx6DGmA8/lRRlTCmPkL196pC0aWBkVs2wyjqb/LABVYL8Xgeomjl3VtEMxAeaUrGvnIawVh/oBAAD///GwU6v3yCoVAAAAAElFTkSuQmCC", "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAIAAABLbSncAAAA2ElEQVR4nADIADf/AvdGjTZeOlQq07xSYPgJjlWRwfWEBx2+CgAVrPrP+O5ghhOa+a0cocoWnaMJFAsBuCQCgiJOKDBcIQTiLieOrPD/cp/6iZ/Iu4HqAh5dGzggIQVJI3WqTxwVTDjs5XJOy38AlgHoaKgY+xJEXeFTyR7FOfF7JNWjs3b8evQE6B2dTDvQZx3n3Rz6rgOtVlaZRLvR9geCAxuY3G+0mepEAhrTISES3bwPWYYi48OUrQOc//IaJeij9xZGGmDIG9kc73fNI7eA8VMBAAD//0SxXMMT90UdAAAAAElFTkSuQmCC"]}
' -v -i 'http://0.0.0.0:5555/api/index'
POST a SearchRequest¶
# POST an SearchRequest to `http://0.0.0.0:5555/api/index`
curl -X POST -d '{"top_k": 5, "data": ["data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAIAAABLbSncAAAA2ElEQVR4nADIADf/AxWcWRUeCEeBO68T3u1qLWarHqMaxDnxhAEaLh0Ssu6ZGfnKcjP4CeDLoJok3o4aOPYAJocsjktZfo4Z7Q/WR1UTgppAAdguAhR+AUm9AnqRH2jgdBZ0R+kKxAFoAME32BL7fwQbcLzhw+dXMmY9BS9K8EarXyWLH8VYK1MACkxlLTY4Eh69XfjpROqjE7P0AeBx6DGmA8/lRRlTCmPkL196pC0aWBkVs2wyjqb/LABVYL8Xgeomjl3VtEMxAeaUrGvnIawVh/oBAAD///GwU6v3yCoVAAAAAElFTkSuQmCC", "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAIAAABLbSncAAAA2ElEQVR4nADIADf/AvdGjTZeOlQq07xSYPgJjlWRwfWEBx2+CgAVrPrP+O5ghhOa+a0cocoWnaMJFAsBuCQCgiJOKDBcIQTiLieOrPD/cp/6iZ/Iu4HqAh5dGzggIQVJI3WqTxwVTDjs5XJOy38AlgHoaKgY+xJEXeFTyR7FOfF7JNWjs3b8evQE6B2dTDvQZx3n3Rz6rgOtVlaZRLvR9geCAxuY3G+0mepEAhrTISES3bwPWYYi48OUrQOc//IaJeij9xZGGmDIG9kc73fNI7eA8VMBAAD//0SxXMMT90UdAAAAAElFTkSuQmCC"]}
' -v -i 'http://0.0.0.0:5555/api/search'
Remarks on POST :<port_expose>/api/<mode>¶
<mode>
should be one ofindex
,train
andsearch
MIME type should be
application/json
the content should at least have the
data
field, which contains a list of data URI, each corresponds to one document.You can specify other arguments in the request. For example,
top_k
,batch_size
,first_doc_id
. The full list can be found in here. Please note that not all arguments are supported on the REST API level at the moment.The REST endpoint will be served at
port_expose
Switching from gRPC gateway to REST gateway¶
By default Jina uses gRPC as the gateway for receiving and sending requests from and to clients. Some users especially the frontend engineers may look for a RESTful API to communicate with Jina. This can be done by easily.
In Python API¶
from jina.flow import Flow
f = (Flow(rest_api=True).add(...)
.add(...))
Note that you can not use f.index
, f.search
and f.train
here
anymore. These IO interface are based on Python client, which uses gRPC
behind the scene. You should use Javascript or Node and send HTTP
request to communicate with this Flow instead.
To block a Flow, use block()
with f:
f.block()
In YAML¶
!Flow
with:
rest_api: true
And then either load it in Python via Flow.load_config('my.yml')
or
via CLI: jina flow --yaml-path my.yml
In gateway’s CLI (advanced)¶
Most of the cases you just need to set rest-api
on the Flow level.
But in case you need to start a separate gateway with rest_api
enabled. You can do:
jina gateway --rest-api
Unsupported Features in REST API¶
In the current version, the following features are only supported by gRPC interface not by REST API. We are continuously improving it.
in_proto
is not supported. You can not send raw binary Protobuf documents to Jina using REST API interface.callback_on_body
is not supported.batch_size
is not supported. As it will break one request into multiple responses.REST gateway does not do prefetching. There will be no bi-directional streaming. Internally, REST gateway communicate with Pod in async way, this is the same as in gRPC gateway. However, only after all results are finished, will the REST gateway return the results. This is different than the gRPC gateway, where the results are streamed in an async way.
Please pay attention to the case transformation on the keys in the JSON payload returned. doc_id defined in gRPC protobuf will be returned as docId in JSON.