api

README

REST API v1

/v1/formats

Format object:

{
    "name": "name of the format"
}

Create format

POST /v1/formats

curl -i -XPOST -H "content-type: application/json" -d '{"name": "pdf"}' "http://localhost:8080/v1/formats"

Retrieve format

GET /v1/formats/{name}

curl -i -XGET "http://localhost:8080/v1/formats/pdf"

Delete format

DELETE /v1/formats/{name}

curl -i -XDELETE "http://localhost:8080/v1/formats/pdf"

List formats

GET /v1/formats

curl -i -XGET "http://localhost:8080/v1/formats"

/v1/indexes

Index create request object:

{
    "id": "the index ID",
    "format": "pdf",
    "tags": ["userABC", "salesTeam"],
    "document": "a base64 encoded document, used for create new index only",
    "records": [{"id": "abcd", "segment": "hello world", "vector": [1, 2]}]
}

An index record object:

{
    "id": "a base64 encoded vector",
    "segment": "this is searchable piece of the text",
    "vector": [1, "abc", 3]
}

Create index

POST /v1/indexes

An index may be created via providing the whole data in the content-type: application/json body:

curl -i -XPOST -H "content-type: application/json" -d '{"id": "1234", "format": "pdf", "tags":{"k1":"v1"}, "records": [{"id":"r1", "segment": "my text", "vector": [1, 2]}]}' "http://localhost:8080/v1/indexes"

or 'multipart/form-data' is also supported:

curl -i -X POST -H "content-type: multipart/form-data" -F"file=@/tmp/test.txt" -F "meta={\"id\": \"test.txt\", \"tags\":{\"k1\":\"v1\"}, \"format\": \"txt\"};type=application/json" "http://localhost:8080/v1/indexes"

Update index

PUT /v1/indexes/{id}

curl -i -XPUT -H "content-type: application/json" -d '{"tags":{"k1":"v1"}}' "http://localhost:8080/v1/indexes/1234"

Retrieve index

GET /v1/indexes/{id}

curl -i -XGET "http://localhost:8080/v1/indexes/1234"

Delete index

DELETE /v1/indexes/{id}

curl -i -XDELETE "http://localhost:8080/v1/indexes/1234"

Query indexes

GET /v1/indexes

Query parameters:

• format = {format name}
• tag = {url encoded json map}
• created-after = {date in "2006-01-02T15:04:05-07:00" format}
• created-before = {date in "2006-01-02T15:04:05-07:00" format}
• start-index-id = {starting index id, see the result object nextPageId field}
• limit= {items per page}

curl -i -XGET "http://localhost:8080/v1/indexes?format=pdf&tags=%7B%22k1%22%3A%22v1%22%7D&created-after=2006-01-02T15:04:05-07:00&created-before=2024-01-02T15:04:05-07:00&start-index-id="123"&limit=1"

Query result object:

{
    "indexes":[],
    "nextIndexId":"",
    "total":1
}

Update index records

PATCH /v1/indexes/{id}/records

Index records update request object:

{
    "upsertRecords": [{"id": "record id", "segment": "this is searcheable piece of the text", "vector": [1, "abc", 3]}],
    "deleteRecords": [{"id": "record id"}]
}

curl -i -XPATCH -H "content-type: application/json" -d '{"upsertRecords": [{"id": "000145f6", "segment": "this is searcheable piece of the text", "vector": [1, "abc", 3]}], "deleteRecords": [{"id": "0001044f"}]}' "http://localhost:8080/v1/indexes/test.txt/records"

Update result object:

{
    "upserted": 1,
    "deleted": 1
}

Query index records

GET /v1/indexes/{id}/records

Query parameters:

• start-record-id = {starting record id, see the result object nextRecordId}
• limit = {items per page}

curl -i -XGET "http://localhost:8080/v1/indexes/test.txt/records?start-record-id=eyJpbmRleF9pZCI6InRlc3QudHh0IiwicmVjb3JkX2lkIjoiMDAwMDAwMDIifQ==&limit=1"

Query result object:

{
    "records": [{"id":"","segment":"","vector":{}}],
    "nextRecordId": "",
    "total": 1
}

/v1/search

Search request object:

{
    "text": "a list of words that should be found",
    "tags": "a json map of `{key:val}` tags to filter by",
    "indexIDs": "a list of index IDs to filter by",
    "distinct": "if true, the result will contain only one record(first) per index",
    "orderByScore": "if true, the results are ordered by the result relevancy score",
    "pageId": "starting page id, see the result object `nextPageId` field",
    "offset": "specifies how many records to skip before beginning to return records",
    "limit": "items per page"
}

Search records

POST /v1/search

# query to iterate through all the results
curl -i -XPOST -H "content-type: application/json" -d '{"text": "shakespeare", "tags":{"k1":"v1"}, "indexIDs":["test.txt"], "pageId":"eyJpbmRleF9pZCI6InRlc3QudHh0IiwicmVjb3JkX2lkIjoiMDAwMGJhODUifQ=="}' "http://localhost:8080/v1/search"

# query to check the most relevant results
curl -i -XPOST -H "content-type: application/json" -d '{"text": "shakespeare", "orderByScore":true, "distinct":true, "offset":25, "limit":100}' "http://localhost:8080/v1/search"

Search result object:

{
    "records": [{"indexId":"","indexRecord":{"id":"","segment":"","vector":{}}, "matchedKeywords": [], "score":2}],
    "nextPageId": "",
    "total": 1
}

Documentation

Index

• func BindAppJson(c *gin.Context, inf interface{}) error
• func ComposeURI(r *http.Request, id string) string
• func ParseTime(s string) (time.Time, error)
• func ResolveHost(r *http.Request) (host string)
• func ResolveScheme(r *http.Request) string
• type ErrorMsg
• type HttpEP
  • func NewHttpEP(svc *Service) *HttpEP
  • func (hep *HttpEP) RegisterEPs(g *gin.Engine) error
• type Service
  • func NewService() *Service
  • func (s *Service) FormatServiceServer() format.ServiceServer
  • func (s *Service) IndexServiceServer() index.ServiceServer

Functions

func BindAppJson

func BindAppJson(c *gin.Context, inf interface{}) error

BindAppJson turns the request body to inf, but for "application/json" contents only

func ComposeURI

func ComposeURI(r *http.Request, id string) string

ComposeURI helper function which composes URI, adding ID to the request path

func ParseTime

func ParseTime(s string) (time.Time, error)

func ResolveHost

func ResolveHost(r *http.Request) (host string)

ResolveHost returns host part of r

func ResolveScheme

func ResolveScheme(r *http.Request) string

ResolveScheme resolves initial request type by r

Types

type ErrorMsg

type ErrorMsg struct {
	Error string `json:"error"`
}

type HttpEP

type HttpEP struct {
	// contains filtered or unexported fields
}

HttpEP provides the api endpoints for the HTTP interface

func NewHttpEP

func NewHttpEP(svc *Service) *HttpEP

func (*HttpEP) RegisterEPs

func (hep *HttpEP) RegisterEPs(g *gin.Engine) error

type Service

type Service struct {
	PProvider parser.Provider `inject:""`
	Db        persistence.Db  `inject:""`
	// contains filtered or unexported fields
}

Service implements the gRPC API endpoints

func NewService

func NewService() *Service

func (*Service) FormatServiceServer

func (s *Service) FormatServiceServer() format.ServiceServer

func (*Service) IndexServiceServer

func (s *Service) IndexServiceServer() index.ServiceServer

IndexServiceServer returns index.ServiceServer