Barrel
EN GitHub

API REST

Voici la liste de toutes les routes que sert barrel_server, avec qui peut les appeler, quoi envoyer et ce qui revient. Utilisez-la quand vous écrivez un client à la main ou vérifiez ce que fait une route ; le guide du serveur montre les mêmes routes dans une session complète. Elle est construite à partir de la table des routes de barrel_server_api.erl (barrel_server 1.14.0), et les réponses d’exemple ont été capturées sur un serveur en marche.

Vérifiez les détails

Le fichier OpenAPI /openapi.yaml liste toutes les routes de cette page, et un test de barrel échoue quand les deux diffèrent. Certains détails de requêtes et de réponses diffèrent encore du serveur : vérifiez cette page avant de générer un client à partir de lui.

Écarts connus : il dit que GET / est public, mais la route demande une authentification quand auth est configuré ; il renvoie {id, _rev} depuis PUT /db/:db/doc/:id, le serveur renvoie {id, ok, rev} ; il type les éléments where de /find comme des objets, ce sont des tableaux comme ["path",["kind"],"note"], et il autorise des clés supplémentaires que le serveur refuse ; il omet max_rows, deadline_ms, ?conflicts=true, les en-têtes d’écriture, et les erreurs 501, 503 et 500 sur les pièces jointes et la recherche ; les routes de contextes et d’ensembles de travail sont listées avec des corps peu précis.

Conventions

  • Les corps sont en JSON sauf mention contraire de la route. Les erreurs sont {"error": "<code>"} ; voir Codes d’erreur.
  • Seul PUT /db/:db crée une base. Toute autre route /db/:db/... répond 404 {"error":"db_not_found"} quand la base n’existe pas.
  • Les noms utilisent des lettres minuscules, des chiffres, _ et -, de 1 à 63 octets, et ne commencent pas par _ ; tout autre nom répond 400 invalid_name. La base interne _barrel_system n’est pas accessible en REST.
  • Les révisions ressemblent à 000001a1b876972d00000000@w78160d59891ba7d7. Envoyez la révision courante dans _rev pour mettre à jour.
  • Les écritures acceptent les en-têtes x-barrel-actor, x-barrel-session et x-barrel-source, enregistrés comme provenance (256 octets chacun).
  • Les curseurs du flux de changements sont des HLC en base64 sûr pour les URL, comme AAABobh2tYwAAAAB.

Classes d’authentification

ClasseQui passe
publicTout le monde, même quand l’authentification est configurée
serverUn token bearer serveur, une requête signée ou mTLS
read, writeUn identifiant serveur, ou un jeton de capacité avec ce droit quand :db est son espace
agentUn jeton de capacité valide ; le handler vérifie ensuite ses droits
server onlyUn identifiant serveur ; les jetons de capacité reçoivent 403

Un serveur sans auth configuré saute toutes les vérifications. Voir Authentification.

Méta

RouteAuthRequêteRéponseErreurs
GET /serveraucune200 texte barrel edge database401
GET /healthpublicaucune200 {"status":"ok"} ; ne vérifie aucune baseaucune
GET /readypublicaucune200 {"status":"ready"} quand les processus des bases et de la réplication tournent503 {"status":"not_ready","failed":[...]}, failed parmi databases, stores, replication

Bases

RouteAuthRequêteRéponseErreurs
PUT /db/:dbserver onlyfacultatif {"att_opts":{"backend":"blob"|"s3","s3":{...}}}201 {"ok":true,"db":"demo"}400 invalid_name, bad_att_opts
GET /db/:dbreadaucune200 infos : name, config, read_only, db_path, keyspace, retention_period, history_floor, att_floor, write_groups, embedder400, 500
DELETE /db/:dbserver only?purge=true supprime aussi les fichiers200 {"ok":true,"db":"demo"}, plus "purged":true500

Documents

RouteAuthRequêteRéponseErreurs
PUT /db/:db/doc/:idwritele document ; _rev pour mettre à jour ; en-têtes de provenance201 {"id","ok":true,"rev"}409 conflict, 400 bad_json, invalid_provenance
GET /db/:db/doc/:idread?include_embedding=true, ?conflicts=true (ajoute _conflicts, _observed)200 le document avec _rev404 not_found
DELETE /db/:db/doc/:idwriteen-têtes de provenance200 {"id","ok":true,"rev"}404
POST /db/:db/_bulk_docswrite{"docs":[...]}201 {"results":[{"id","ok","rev"} or {"error"}]}400
POST /db/:db/_bulk_getread{"ids":[...],"include_embedding"?}200 {"results":[doc or {"error":"not_found"}]}400
GET /db/:db/doc/:id/_versionsreadaucune200 {"id","versions":[{rev,status,deleted,provenance?}]}404
GET /db/:db/doc/:id/_versions/:revreadaucune200 le corps stocké de cette version404
GET /db/:db/_historyread?since, ?until (curseurs), ?limit, ?id200 {"history":[{id,rev,deleted,cause,hlc,provenance?}]}400 bad_since, bad_until, bad_limit
curl -X PUT localhost:8080/db/demo/doc/a \
  -H 'content-type: application/json' \
  -d '{"title":"hello world","kind":"note"}'
{"id":"a","ok":true,
 "rev":"000001a1b876972d00000000@w78160d59891ba7d7"}

Recherche structurée et requêtes

RouteAuthRequêteRéponseErreurs
POST /db/:db/findreadwhere, limit, offset, include_docs, id_prefix, continuation ; toute autre clé est refusée200 {"rows":[{id,doc}],"meta":{has_more,continuation?}}400 invalid_query + reason
POST /db/:db/queryreaddu BQL brut avec un content type non JSON, ou {query, params, continuation, max_rows, deadline_ms}200 application/x-ndjson : des lignes {"row":...}, puis {"meta":{...}}400 invalid_query + message, line, column ; missing_query ; bad_json ; invalid_max_rows ; invalid_deadline_ms ; subscribe_requires_sse
GET /db/:db/queryread?q=, ?max_rows=, ?deadline_ms= (pour EventSource)comme pour POSTcomme pour POST
  • Les éléments where sont des tableaux sous la forme des filtres de réplication, comme ["path",["kind"],"note"].
  • /find renvoie meta.continuation quand il reste des lignes. Pour lire la page suivante, renvoyez-la dans le corps sous continuation, avec la même requête ; une continuation mal formée répond 400 invalid_query. Il renvoie doc dans chaque ligne, avec ou sans include_docs.
  • max_rows vaut 1000 au plus et deadline_ms 300000 au plus. La dernière ligne meta porte has_more, bound (limit_reached ou exhausted), count, continuation, instance_id, last_seq et, pour la recherche, embedding. Une erreur survenue après l’envoi de lignes arrive dans une dernière ligne {"error":"deadline"} ou avec une autre raison.
  • Une instruction SUBSCRIBE demande Accept: text/event-stream ou ?feed=sse, et diffuse les événements row, ready, change, error et ping (toutes les 30 s).
curl -X POST localhost:8080/db/demo/query \
  -H 'content-type: text/plain' \
  --data-binary "SELECT id, title FROM c
    WHERE kind = 'note' ORDER BY id LIMIT 2"

La réponse, capturée avec la même instruction envoyée en JSON :

{"row":{"id":"a","title":"hello world"}}
{"row":{"id":"c","title":"third"}}
{"meta":{"count":2,"bound":"limit_reached",
 "last_seq":"AAABobh2tYwAAAAB",
 "instance_id":"95e252eeaff57fa0","has_more":false}}

Changements

RouteAuthRequêteRéponseErreurs
GET /db/:db/changesread?since=<cursor> ou first ; ?feed=sse ou continuous, ou Accept: text/event-stream200 {"changes":[{id,rev,hlc,changes:[{rev}],num_conflicts}],"last":cursor}aucune

Un since invalide n’échoue pas : le flux repart du premier changement. En SSE, une lecture ponctuelle envoie des lignes data: puis event: last ; continuous garde le flux ouvert avec un ping toutes les 30 s.

Pièces jointes

RouteAuthRequêteRéponseErreurs
PUT /db/:db/doc/:id/att/:namewriteles octets bruts ; content-type ; If-None-Match: * pour créer seulement ; If-Match: <etag>201 {name,length,digest,content_type,chunked} ; le _rev du document ne change pas400 bad_if_none_match, 409 conflict, 501 conditional_writes_unsupported ou attachments_disabled, 503 att_sync_pending
GET /db/:db/doc/:id/att/:namereadaucune200 les octets avec leur content type stocké404
DELETE /db/:db/doc/:id/att/:namewriteaucune200 {"ok":true}404

Vecteurs et recherche

RouteAuthRequêteRéponseErreurs
POST /db/:db/vectorwrite{id, text, metadata, vector?} ; sans vector, le serveur calcule l’embedding de text201 {"ok":true,"id"}500 dimensions incorrectes ou pas d’embedder
POST /db/:db/search/vectorread{"vector":[...],"k"} ; k vaut 10 par défaut, 10000 au plus200 {"hits":[{key,score,text,metadata}]}500 {dimension_mismatch,768,N}
POST /db/:db/search/bm25read{"query","k"}200 {"hits":[{key,score}]}500 bm25_not_enabled
POST /db/:db/search/hybridread{"query","k"}200 {"hits":[...]}500 embedder_not_configured

Une base ouverte avec les options par défaut a un magasin de vecteurs cosinus à 768 dimensions, BM25 désactivé et aucun embedder. Définissez open_opts dans la configuration du serveur, ou ouvrez la base en mode enregistrement, pour obtenir la recherche par mots-clés et hybride.

Timeline

Toutes les routes de timeline sont server only.

RouteRequêteRéponseErreurs
GET /db/:db/_timelineaucune{"db","branches":[...],"parent"?,"fork_hlc"?}400, 500
POST /db/:db/_timeline/branch{"name", "at"?} (un curseur du flux de changements) ou {"name", "at_time"?} (RFC 3339)201 {"ok","branch","parent","fork_hlc"}400 invalid_name, bad_at, pitr_window_exceeded ; 409 already_exists, cannot_branch_a_branch
POST /db/:db/_timeline/mergeaucune ; appelez-la sur la branche200 docs_read, docs_written, failed, last_merged, att_sync409 not_a_branch, 404 parent_not_found

Protocole de réplication

Ces routes transportent la réplication entre les nœuds et barrel-lite. Vous ne les appelez pas à la main ; barrel_rep et barrel-lite le font. Chaque réponse porte un en-tête x-barrel-hlc. Elles ne créent jamais de base.

RouteDroitRôle
GET /db/:db/_sync/inforeadCapacités : full_state, att_flush, att_filter, planchers
POST /db/:db/_sync/hlcreadÉchange d’horloges
POST /db/:db/_sync/changesread{since, limit, filter?, deleted?} vers {changes, last_seq}
POST /db/:db/_sync/diffreadLes versions qui manquent au serveur
GET, PUT /db/:db/_sync/doc/:idread, writeUne version
GET, PUT /db/:db/_sync/state/:idread, writeL’état complet du document
PUT /db/:db/_sync/repair/:idwriteRéparation des corps, utilisée par reconcile
GET, PUT, DELETE /db/:db/_sync/local/:idread, write, writeCheckpoints de réplication
GET /db/:db/_sync/att_changesreadFlux des pièces jointes
POST /db/:db/_sync/att_diffread{attachments, touch?}
POST /db/:db/_sync/att_listread{ids}
POST /db/:db/_sync/att_flushwriteRendre durables les écritures de pièces jointes
GET /db/:db/_sync/att_state/:id/:namereadÉtat d’une pièce jointe
GET, PUT, DELETE /db/:db/_sync/att/:id/:nameread, write, writeOctets de pièce jointe en flux, avec x-barrel-digest, x-barrel-att-origin, x-barrel-att-touch

Espaces, sessions et passations

Toutes en classe agent. Voir le guide des espaces pour les corps.

RoutesRôle
POST, GET /spaces ; GET, DELETE /spaces/:spaceCréer, lister, lire et supprimer des espaces
POST, GET /spaces/:space/grants ; DELETE /spaces/:space/grants/:token_idÉmettre, lister et révoquer des jetons de capacité
POST, GET /spaces/:space/sessions ; GET, DELETE .../sessions/:sid ; POST .../sessions/:sid/touchSessions avec un TTL glissant
POST, GET .../sessions/:sid/messagesMessages de session
PUT, GET .../sessions/:sid/data/:keyDonnées de session
POST, GET /handoffs ; POST /handoffs/accept ; POST /handoffs/completePassations
curl -X POST localhost:8080/spaces \
  -H 'content-type: application/json' \
  -d '{"label":"team"}'
{"ok":true,"space":"sp_..."}

Contextes et ensembles de travail

Voir le guide des contextes pour les corps.

RouteAuth
POST /contexts (201)server only
GET /contexts (?prefix=, ?unlisted=true, ?q=)agent
GET /contexts/_capabilitiesagent
GET /contexts/_offlineagent
PUT /contexts/_offlineserver only
POST /contexts/_queryagent ; chaque membre local est vérifié comme POST /db/:db/query
GET /contexts/:idagent
DELETE /contexts/:idserver only
POST, GET /worksetsserver only
GET, DELETE /worksets/:wsserver only
POST /worksets/:ws/membersserver only
DELETE /worksets/:ws/members/:ctxserver only
POST /worksets/:ws/_materializeserver only
POST /worksets/:ws/_importserver only

Il n’y a pas de route pour mettre à jour une fiche de contexte.

MCP

POST, GET, DELETE et OPTIONS /mcp servent le Model Context Protocol en HTTP streamable. Le point d’accès n’accepte que des tokens bearer. Les outils sont listés dans Outils MCP.

Traduit de la page anglaise: /docs/reference/rest-api/ Modifier cette page Voir en Markdown

Haut et bas pour se déplacerEntrée pour ouvrir