cuba-platform / jpawebapi

CUBA JPA Web API Addon

JPA Web API

Overview

The universal JPA web API enables loading and saving any entities defined in the application data model by sending simple HTTP requests.

The add-on provides an easy way to integrate with a wide range of third-party applications – from the JavaScript code executed in the browser to arbitrary systems running on Java, .NET, PHP or any other platform.

Key API features:

• Loading entity instances from the database by identifier or by JPQL query with parameters.
• Saving new and modified instances, deleting instances.
• Obtaining a description of the data model in HTML format.
• Data representation in JSON and XML formats.
• Middleware service calls.
• User authentication.

Read add-on Wiki for additional information.

Installation

You can install the add-on by coordinates choosing the required version of the add-on from the table.

In case you want to install the add-on by manual editing or by building from sources see the complete add-ons installation guide in CUBA Platform documentation.

By Coordinates

1. Open your application in CUBA Studio. Check the latest version of CUBA Studio on the CUBA Platform site.
2. Go to CUBA -> Marketplace in the main menu.

3. Click the icon in the upper-right corner.

4. Paste the add-on coordinates in the corresponding field as follows:

com.haulmont.addon.jpawebapi:jpawebapi-global:<add-on version>

where <add-on version> is compatible with the used version of the CUBA platform.

Platform Version	Add-on Version
7.2.X	1.1.0
7.1.X	1.0.0

5. Click Install and apply the changes. The add-on will be installed to your project.

After that the JPA Web API functionality will be available at:

• {host:port}/app/dispatch/api/* - for Web module
• {host:port}/app-portal/api/* - for Portal module

Customization

JPA Web API URL can be customized via jpawebapi.mapping.url app property both for web and portal application modules.

Security

Since CUBA Platform 7.2 you should create a new role with included permission-config.jpawebapi.api.enabled permission and assign it to new users in order to grant them access to the add-on.

Demo

1. Login as admin / admin with GET request:

http://localhost:8080/app/dispatch/api/login?u=admin&p=admin&l=ru

2. Load Users list using auth token:

http://localhost:8080/app/dispatch/api/query.json?e=sec$Role&q=select+r+from+sec$Role+r&s=b376f1d2-15d7-ea33-4048-2199de9721e7

jpawebapi's Issues

Provide default value for property 'cuba.rest.allowedOrigins'

Use dependencies from bom file of CUBA Platform for same dependencies

Update Installation instuctions in readme

Please update the "Installation" section of readme.md: describe how to install the component using Add-ons Marketplace

Add information about the need to creating custom role with allowed permission-config.jpawebapi.api.enabled

Environment

• Platform version: 7.2.8
• Addon version: 1.1.0

Description of the bug or enhancement

Add information about that permission-config.jpawebapi.api.enabled specific permission is enabled

• Minimal reproducible example

1. Create a new project on 6.10.18 Platform version

2. Migrate the project to the 7.2.8 Platform version

3. Add jpawebapi addon

4. Run the project

5. Create a new user

6. Try to login as created user with GET request
   AR: Request return JSON with error HTTP Status 401 – Unauthorize

7. Login in app and open Administration -> Roles -> Create a new Role -> Open the Specific tab

8. Allow the permission-config.jpawebapi.api.enabled and save changes

9. Assign the created role to created user
   10 Try to login as created user with GET request

AR: Login as created user was successeful and request return JSON with access token

Entity is updated which specified as new property value of commit instance

Environment

• Platform version: 7.2-SNAPSHOT
• Addon version: 1.1.0

Description of the bug or enhancement

• Minimal reproducible example
  By use http://localhost:8080/app-portal/api/commit request
  try to update existing entity (without specified view !) with setting reference property to the new value.
  Bug is reproducing only if reference entity (specified as new property value) has @PostConstruct method in which some fields are initializing by not null values (or some entity fields are initializing in field declaration).

For example (request body):

{
  "commitInstances": [
    {
      "id": "df$DocKind-c40ea551-d399-4a11-b6be-347ca5f27837",
      "numerator": {
        "id": "df$Numerator-70dfe954-fe9d-11e2-96e0-1f9c56fc4e22"
      }
    }
  ]
}

1. "df$DocKind-c40ea551-d399-4a11-b6be-347ca5f27837" - without view
2. "df$Numerator-70dfe954-fe9d-11e2-96e0-1f9c56fc4e22" - new reference property value
3. Entity 'df$Numerator' has @PostConstruct method:

    @PostConstruct
    protected void init() {
        setPeriodicity(PeriodicityType.YEAR);
        setScriptEnabled(false);
        setNumberInitialValue(1);
    }

These 3 fields of Numerator entity will be really updated after merge DocKind.

see:
com.haulmont.addon.jpawebapi.api.controller.DataServiceController#commit

// reference to an existing entity
                            Object refEntityId = refEntity.getId();
                            refEntity = metadata.create(refEntity.getMetaClass());

                            //noinspection unchecked
                            ((BaseGenericIdEntity) refEntity).setId(refEntityId);

com.haulmont.cuba.core.sys.EntityManagerImpl#merge(T)
com.haulmont.cuba.core.sys.EntityManagerImpl#deepCopyIgnoringNulls

• Expected behavior
  Entity which specified as new property value is not updated.
  (DocKind is updated, Numerator is not, for example)
• Actual behavior
  The commit instance and entity which specified as new property value are updated.

Add localization for role permission setting

Environment

• Platform version: 7.1.x
• Addon version: 1.0.0

Portal module doesn't response at GET request in case of SingleWAR and UberJAR deployment

1. Create an application with Platform version 7.1+
2. Add jpawebapi addon
3. Add Portal module
4. Build SingleWar
5. Start app server
6. Try to send GET to the portal via http://localhost:8080/app-portal/api/login?u=admin&p=admin&l=ru

AR: No response from portal module

Try the same steps for UberJAR deployment.
AR:

Publish XSD schemes

We have to publish schemes located in directory:

./modules/jpawebapi/src/com/haulmont/addon/jpawebapi/api/scheme

Schemes should be published under http://schemas.haulmont.com/jpawebapi/ path

Then update scheme usages in Wiki.

REST API doesn't allow returning collection of non-entity types for service invocation

For service methods that return collection of non-entity types REST API checks that case and throws an exception from JSONConverter.processServiceMethodResult().

if (!checkCollectionItemTypes((Collection) result, Entity.class))
                throw new IllegalArgumentException("Items that are not instances of Entity found in service method result");

Whereas returning non-entity types (not wrapped in a collection) is allowed.
Returning a collection of non-entity types should be allowed as well.

---

Original issue: https://youtrack.haulmont.com/issue/PL-8131