Summary
This cube exposes the new api, replacing the RQLController cube with a simpler architecture. We plan on integrating this new API directly into CubicWeb, without having to rely on this cube.
You can use the CubicWebJS client to communicate with this API in JavaScript. See the project React Admin CubicWeb for an example on how to use CubicWebJS.
⚠️ 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.
Vision
The 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 our Matrix channel or open an issue on the CubicWeb Repository. Depending on the need we may update RQL to add new features!
Setup
Install this cube with pip by running:
pip install cubicweb_api
Then open the __pkginfo__.py of your CubicWeb instance and add cubicweb-api in the __depends__ dictionary.
Existing instances
If 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 using cubicweb-ctl shell <YOUR_INSTANCE>. In that shell type add_cube(api), then exit() to leave the shell.
And finally upgrade your instance:
cubicweb-ctl upgrade <YOUR_INSTANCE>
The command will ask you to edit the all-in-one.conf file. Accept the changes to write the default configuration options available for this cube.
Configuration options
Several configuration options are available in pyramid.ini:
cubicweb_api.api_path_prefix
Path after the hostname on which to serve the api. Defaults to api. The api version number will be added after this prefix (only v1 for now).
Example:
For a cubicweb instance deployed on http://localhost:8080.
The api will be deployed by default at http://localhost:8080/api/v1.
If you set the option to cubicweb_api.api_path_prefix = my/custom/path, it will be then be deployed on http://localhost:8080/my/custom/path/v1
cubicweb.includes = cubicweb_api.auth.routes
Include cubicweb_api.auth.routes to enable the login and logout routes. These routes will use whatever authentication policy is enabled in cubicweb.
cubicweb.includes = cubicweb_api.auth.jwt
Include cubicweb_api.auth.jwt to enable the JWT cookie authentication policy.
⚠️ This feature is experimental, do not use in production
Available Routes
This cube uses the OpenAPI specification to describe and validate data. The complete specification is available in openapi_template.yaml.
On running instances, the <PREFIX>/openapi route provides the specification in an interactive HTML page (http://localhost:8080/api/v1/openapi with default settings). The <PREFIX>/openapi.yaml route provides the raw YAML file.
Authentication
When sending valid credentials to the login route, a JWT token will be generated and sent in the Set-Cookie header. 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”).
Troubleshooting
Pyramid
Depending on your pyramid configuration, you may need to manually include the api routes by adding this line in your pyramid.ini
cubicweb.includes = cubicweb_api
1 maintainer
Release files for cubicweb-api 0.17.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| cubicweb_api-0.17.2.tar.gz | 27.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| cubicweb_api-0.17.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 55.3 kB
Release files / cubicweb_api-0.17.2.tar.gz
| Download URL | cubicweb_api-0.17.2.tar.gz |
|---|---|
| Size | 27.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fff3041f007bc1f657b066ad83ab7ab8b5167c380a6ed7bc276cc8c5f4094cb5
|
|
BLAKE2b-256 checksum How to use checksums |
82f4b8a4b333d021f28e2178713728715dc4875339fbc7705026d8a18770bd13
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.2
|
Release files / cubicweb_api-0.17.2-py3-none-any.whl
| Download URL | cubicweb_api-0.17.2-py3-none-any.whl |
|---|---|
| Size | 27.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d35a01ce1718109975197bc0113620b11197c4fc251aea5e781f265d34c2d44b
|
|
BLAKE2b-256 checksum How to use checksums |
92f9d6e700f33f0d2a322a4c933c86d249f8086a40b48422fccbce7429a10668
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.2
|
