Summary
================
.. Useful links
.. _RQLController cube: https://forge.extranet.logilab.fr/cubicweb/cubes/rqlcontroller
.. _CubicWebJS: https://forge.extranet.logilab.fr/cubicweb/cubicwebjs
.. _React Admin CubicWeb: https://forge.extranet.logilab.fr/cubicweb/react-admin
.. _OpenAPI: https://www.openapis.org
.. _JWT: https://jwt.io
.. _CubicWeb Repository: https://forge.extranet.logilab.fr/cubicweb/cubicweb
.. _Matrix channel: https://matrix.to/#/#cubicweb:matrix.logilab.org
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 <cubicweb_api/openapi/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``
Raw data
{
"_id": null,
"home_page": "https://forge.extranet.logilab.fr/cubicweb/cubes/api",
"name": "cubicweb-api",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10.0",
"maintainer_email": null,
"keywords": null,
"author": "LOGILAB S.A. (Paris, FRANCE)",
"author_email": "contact@logilab.fr",
"download_url": "https://files.pythonhosted.org/packages/80/1c/04e845dbd86f712f317e6f181219288e1a9bb39a59ff4045fae2252f5f58/cubicweb_api-0.16.1.tar.gz",
"platform": null,
"description": "Summary\n================\n\n.. Useful links\n.. _RQLController cube: https://forge.extranet.logilab.fr/cubicweb/cubes/rqlcontroller\n.. _CubicWebJS: https://forge.extranet.logilab.fr/cubicweb/cubicwebjs\n.. _React Admin CubicWeb: https://forge.extranet.logilab.fr/cubicweb/react-admin\n.. _OpenAPI: https://www.openapis.org\n.. _JWT: https://jwt.io\n.. _CubicWeb Repository: https://forge.extranet.logilab.fr/cubicweb/cubicweb\n.. _Matrix channel: https://matrix.to/#/#cubicweb:matrix.logilab.org\n\nThis cube exposes the new api, replacing the `RQLController cube`_ with a simpler architecture.\nWe plan on integrating this new API directly into CubicWeb, without having to rely on this cube.\n\nYou can use the `CubicWebJS`_ client to communicate with this API in JavaScript.\nSee the project `React Admin CubicWeb`_ for an example on how to use `CubicWebJS`_.\n\n\n**\u26a0\ufe0f Please note this cube will later be integrated into CubicWeb.\nThe installation instructions only applies for the API cube while it lives in its own repository.**\n\nVision\n------\n\nThe goal is to offer a minimal API surface,\nsimilar to data-servers compatible with SPARQL.\nTo this end, this API mainly offers a route to send RQL requests to.\n\nThere are only a few helper endpoints to login, fetch the data schema\nand retrieve debug information about the server setup.\nThose are either impossible to express in RQL,\nor essential to have to simplify debugging.\n\n**We will not create endpoints to make common RQL requests easier.**\nInstead it is the responsibility of each client\nto make creating those requests easier by offering helpers.\n\nIf you have trouble expressing your need through RQL,\nplease ask your question in our `Matrix channel`_ or\nopen an issue on the `CubicWeb Repository`_.\nDepending on the need we may update RQL to add new features!\n\nSetup\n-----\n\nInstall this cube with pip by running:\n\n``pip install cubicweb_api``\n\nThen open the ``__pkginfo__.py`` of your CubicWeb instance\nand add ``cubicweb-api`` in the ``__depends__`` dictionary.\n\nExisting instances\n~~~~~~~~~~~~~~~~~~\n\nIf you are adding the api to an existing instance,\nyou need to manually add the cube and run a migration.\nTo do so, run the following commands\n(replacing ``<YOUR_INSTANCE>`` with your instance name):\n\nOpen a shell using `cubicweb-ctl shell <YOUR_INSTANCE>`.\nIn that shell type `add_cube(api)`, then `exit()` to leave the shell.\n\nAnd finally upgrade your instance:\n\n``cubicweb-ctl upgrade <YOUR_INSTANCE>``\n\nThe command will ask you to edit the ``all-in-one.conf`` file.\nAccept the changes to write the default configuration options available for this cube.\n\nConfiguration options\n~~~~~~~~~~~~~~~~~~~~~\n\nSeveral configuration options are available in `pyramid.ini`:\n\n``cubicweb_api.api_path_prefix``\n''''''''''''''''''''''''''''''''\n\nPath after the hostname on which to serve the api. Defaults to ``api``.\nThe api version number will be added after this prefix (only v1 for now).\n\n**Example:**\n\nFor a cubicweb instance deployed on ``http://localhost:8080``.\n\nThe api will be deployed by default at ``http://localhost:8080/api/v1``.\n\nIf you set the option to ``cubicweb_api.api_path_prefix = my/custom/path``,\nit will be then be deployed on ``http://localhost:8080/my/custom/path/v1``\n\n``cubicweb.includes = cubicweb_api.auth.routes``\n''''''''''''''''''''''''''''''''''''''''''''''''\n\nInclude ``cubicweb_api.auth.routes`` to enable the login and logout routes.\nThese routes will use whatever authentication policy is enabled in cubicweb.\n\n``cubicweb.includes = cubicweb_api.auth.jwt``\n'''''''''''''''''''''''''''''''''''''''''''''\n\nInclude ``cubicweb_api.auth.jwt`` to enable the JWT cookie authentication policy.\n\n**\u26a0\ufe0f This feature is experimental, do not use in production**\n\nAvailable Routes\n----------------\n\nThis cube uses the `OpenAPI`_ specification to describe and validate data.\nThe complete specification is available in `openapi_template.yaml <cubicweb_api/openapi/openapi_template.yaml>`_.\n\nOn running instances, the ``<PREFIX>/openapi`` route provides the specification in an interactive HTML page\n(http://localhost:8080/api/v1/openapi with default settings).\nThe ``<PREFIX>/openapi.yaml`` route provides the raw YAML file.\n\nAuthentication\n--------------\n\nWhen sending valid credentials to the login route,\na `JWT`_ token will be generated and sent in the ``Set-Cookie`` header.\nThis token must be sent as a cookie for each request to be successful.\n\nPlease note the login route is disabled by default (see section \"Configuration options\").\n\nTroubleshooting\n---------------\n\n**Pyramid**\n\nDepending on your pyramid configuration,\nyou may need to manually include the api\nroutes by adding this line in your pyramid.ini\n\n``cubicweb.includes = cubicweb_api``\n",
"bugtrack_url": null,
"license": "LGPL",
"summary": "This cube is the new api which will be integrated in CubicWeb 4.",
"version": "0.16.1",
"project_urls": {
"Homepage": "https://forge.extranet.logilab.fr/cubicweb/cubes/api"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2ff857b91dbc51fc8398e8c173515cc31b6d26f4a8e9f7a6f0566fe5d291d9bf",
"md5": "62e4d89564232e6ff651e654608030a1",
"sha256": "e5a6dbc213f3ca8447f19b5535d30647da0a59c9939ef6dbf7c7dde4b8ff2123"
},
"downloads": -1,
"filename": "cubicweb_api-0.16.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "62e4d89564232e6ff651e654608030a1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10.0",
"size": 28479,
"upload_time": "2024-11-26T13:43:48",
"upload_time_iso_8601": "2024-11-26T13:43:48.819627Z",
"url": "https://files.pythonhosted.org/packages/2f/f8/57b91dbc51fc8398e8c173515cc31b6d26f4a8e9f7a6f0566fe5d291d9bf/cubicweb_api-0.16.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "801c04e845dbd86f712f317e6f181219288e1a9bb39a59ff4045fae2252f5f58",
"md5": "8a2d1f12f048d3479acad28c8cda7045",
"sha256": "7602f45de8c449c204a7a374fa2fca4574081cf1a9156cd8470d11e1cffebdc3"
},
"downloads": -1,
"filename": "cubicweb_api-0.16.1.tar.gz",
"has_sig": false,
"md5_digest": "8a2d1f12f048d3479acad28c8cda7045",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10.0",
"size": 27354,
"upload_time": "2024-11-26T13:43:50",
"upload_time_iso_8601": "2024-11-26T13:43:50.508344Z",
"url": "https://files.pythonhosted.org/packages/80/1c/04e845dbd86f712f317e6f181219288e1a9bb39a59ff4045fae2252f5f58/cubicweb_api-0.16.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-26 13:43:50",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "cubicweb-api"
}
JSON