Package: cubicweb-api
This cube exposes the new api, replacing theRQLController cubewith a simpler architecture.
We plan on integrating this new API directly into CubicWeb, without having to rely on this cube.You can use theCubicWebJSclient to communicate with this API in JavaScript.
See the projectReact Admin CubicWebfor an example on how to useCubicWebJS.⚠️ Please note this cube will later be integrated into CubicWeb.
The installation instructions only applies for the API cube while it lives in its own repository.VisionThe goal is to offer a minimal API surface,
similar to data-servers compatible with SPARQL.
To this end, this API mainly offers a route to send RQL requests to.There are only a few helper endpoints to login, fetch the data schema
and retrieve debug information about the server setup.
Those are either impossible to express in RQL,
or essential to have to simplify debugging.We will not create endpoints to make common RQL requests easier.Instead it is the responsibility of each client
to make creating those requests easier by offering helpers.If you have trouble expressing your need through RQL,
please ask your question in ourMatrix channelor
open an issue on theCubicWeb Repository.
Depending on the need we may update RQL to add new features!SetupInstall this cube with pip by running:pip install cubicweb_apiThen open the__pkginfo__.pyof your CubicWeb instance
and addcubicweb-apiin the__depends__dictionary.Existing instancesIf you are adding the api to an existing instance,
you need to manually add the cube and run a migration.
To do so, run the following commands
(replacing<YOUR_INSTANCE>with your instance name):Open a shell usingcubicweb-ctl shell <YOUR_INSTANCE>.
In that shell typeadd_cube(api), thenexit()to leave the shell.And finally upgrade your instance:cubicweb-ctlupgrade <YOUR_INSTANCE>The command will ask you to edit theall-in-one.conffile.
Accept the changes to write the default configuration options available for this cube.Configuration optionsSeveral configuration options are available inpyramid.ini:cubicweb_api.api_path_prefixPath after the hostname on which to serve the api. Defaults toapi.
The api version number will be added after this prefix (only v1 for now).Example:For a cubicweb instance deployed onhttp://localhost:8080.The api will be deployed by default  athttp://localhost:8080/api/v1.If you set the option tocubicweb_api.api_path_prefix = my/custom/path,
it will be then be deployed onhttp://localhost:8080/my/custom/path/v1cubicweb.includes = cubicweb_api.auth.routesIncludecubicweb_api.auth.routesto enable the login and logout routes.
These routes will use whatever authentication policy is enabled in cubicweb.cubicweb.includes = cubicweb_api.auth.jwtIncludecubicweb_api.auth.jwtto enable the JWT cookie authentication policy.⚠️ This feature is experimental, do not use in productionAvailable RoutesThis cube uses theOpenAPIspecification to describe and validate data.
The complete specification is available inopenapi_template.yaml.Please note the login route will not appear in the OpenAPI specification if it is disabled (see section “Configuration options”).AuthenticationWhen sending valid credentials to the login route,
aJWTtoken will be generated and sent in theSet-Cookieheader.
This token must be sent as a cookie for each request to be successful.Please note the login route is disabled by default (see section “Configuration options”).TroubleshootingPyramidDepending on your pyramid configuration,
you may need to manually include the api
routes by adding this line in your pyramid.inicubicweb.includes = cubicweb_api