Repository files navigation

bridgeql is part of VMware's support for open source developmentand community.

A library which will add feature to serve your model over rest API

• This will allow users to make ORM query based on any models present in the django app
• This will ask user to provide request in defined format and will serve the API response as json data
• This will allow users to make filter, selection, ordering, slicing and count of model objects

As of today we only support fordjango, will add support forsqlalchemy soon.

bridgeql is release under the BSD-2 license, see theLICENSE file.

SPDX-License-Identifier: BSD-2-Clause

You can install it directly frompypi.org using

pip install bridgeql

The bridgeql library can be integrated to the Django app by editing settingsfile by includingbridgeql in thesettings.INSTALLED_APPS variable.Another change required is to add a url to your existing project as

    projectname/projectname/settings.py

INSTALLED_APPS= [    ...'bridgeql',    ...    ]

URLs Configuration

In your project you can editurls.py, to include thebridgeql urls.

frombridgeql.djangoimporturlsasbridgeql_urls...urlpatterns= [    ...path('api/bridgeql/',include(bridgeql_urls)),    ...]...

This way your app will be ready to serve the REST API to expose model query, you can request the APIto perform basic CRUD operations using one of the following URLs

• Create:create/db_name/app_name/model_name
• Read:read/db_name/app_name/model_name/<?pk>
• Update:update/db_name/app_name/model_name/pk
• Delete:delete/db_name/app_name/model_name/pk

Example Usage:

importrequestsparams= {'filter': {'os__name':'os-name-1'    },'fields': ['ip','name','id'],'exclude': {'name':'machine-name-11'    },'order_by': ['ip'],'limit':5,'offset':10,# default 0}# db_name could be defaultapi_url='<yoursite.com>/api/bridgeql/read/default/machine/Machine'resp=requests.get(api_url, {'payload':json.dumps(params)})result=resp.json()

The above parameters will translate into running the model query forMachine model ofmachine django app.

Machine.objects.using('default')                .filter(os__name='os-name-1')                .exclude(name='machine-name-11')                .values(['ip','name','id'])                .order_by('ip')[10:15]# offset: offset + limit

Settings available inBridgeQL and their default values

BRIDGEQL_ALLOWED_APPS

Default:[list of local apps] (list)

By default, it will try to lookup your local apps for the project, consideringsettings.BASE_DIR orsettings.SITE_ROOT (whichever is found) as your project root directory. If none of this will be available,WARNING will be there to setupBRIDGEQL_ALLOWED_APPS as application starts up.

Adding values as list of desired apps toBRIDGEQL_ALLOWED_APPS will allow you expose models only for the selected apps.This way you can add django backend apps as well as third party apps e.g.django.contrib.auth which can exposeUser model.You can combine next settingsBRIDGEQL_RESTRICTED_MODELS to restrict few columns of that particular model e.gpassword.

BRIDGEQL_ALLOWED_APPS= ['machine','django.contrib.auth']

BRIDGEQL_RESTRICTED_MODELS

Default:{} (Empty dictionary)

Dictionary mappingapp_label.model_name strings to list/bool(True). The value represents list of fields to be restricted for the model as provided in key. If the value is set toTrue, all the fields of that model will be restricted to lookup.

BRIDGEQL_RESTRICTED_MODELS= {'auth.User':True,'machine.OperatingSystem': ['license_key'],}

BRIDGEQL_AUTHENTICATION_DECORATOR

Default:

{  'reader': '',  'writer': ''}

Above setting allows you to use an authentication decorator to authenticate your client's requests.You can provide a custom authentication decorator,for reader and writer separately, whichever suits your application usecase, e.g login_required, same_subnet, etc.

Default value forBRIDGEQL_AUTHENTICATION_DECORATOR will allow you to access API without authentication.

BRIDGEQL_AUTHENTICATION_DECORATOR= {'reader':'bridgeql.auth.basic_auth','writer':'bridgeql.auth.basic_auth'}

bridgeql.auth.basic_auth is available as a basic authentication method where you can pass authorization header asAuthorization: Basic base64(username:password) for each request.

1. make test
2. source venv/bin/activate && tox
3. python -m pip install --upgrade build
4. python -m build

The bridgeql project team welcomes contributions from the community. Before you start working with bridgeql, pleaseread ourDeveloper Certificate of Origin. All contributions to this repository must besigned as described on that page. Your signature certifies that you wrote the patch or have the right to pass it onas an open-source patch. For more detailed information, refer toCONTRIBUTING_DCO.md.

Created and maintained by
Piyus Kumar
Priyank Singh

Copyright © 2023, VMware, Inc. All rights reserved.