Skip to content

Entity Service APIs

If you are looking for an appropriate API for a System-System Integration, then Entity Service APIs (ESA) could be the way forward, it also known as "Data Entity Services" (DES). Entity Service API's can be used to create new business flows and can easily identify which API to use for different contexts. Therefore the limitation which we had with existing API's can be eliminated to a certain extend.

Many of the standard projection APIs are tightly coupled to the IFS Cloud Web pages they serve, which makes it difficult to reuse these APIs for following different requirements. Whilst this gap is fulfilled to a certain extent by the purposely built Integration projections and Premium APIs, the number of such projections are limited and have designed to fulfil specific business scenarios and for integration purposes. The level of composability and discoverability is at minimal level, hence they cannot be reused for new business flows, and hard to identify which to use in different contexts.

  • Creating workflows
  • Third party app integrations
  • Bulk data processing
  • Master data management

Entity Services will add capabilities to automatically promote our Entity Data Models directly as REST end points, without modelling of a projection, hence it address both the issues of discoverability and composability. Exposed Entity models can be used as an OData service for performing CRUD operations and will act as stand-alone model specially for System-System Integrations. Many entity models could be exposed in this way with a minimum effort from product teams. The Entity model, which is representative of the underlying oracle table is the correct level of granularity for composing other useful functionalities.

Following is the recommended order of consuming different APIs, IFS offers for different integration scenarios?

• Premium APIs – as they are tailor made and fully supported by R&D for specific business scenarios

• (Non-Premium) Integration APIs – intended for integration scenarios

• Standard APIs or Entity Service APIs (ESA)– If a Standard APIs support a given integration requirement it may be used, otherwise DES is to be considered, especially if composing on lower-level API end points.

• However, ESA should NOT be used for external end-user interactive access. For end-user scenarios, refer to above API categories.

Goals and Objectives

  • Expose IFS Entity Models as OData services for performing CRUD operations and State Machine transitions
  • Entity models will get exposed as Rest endpoints without the modelling of a projection.
  • Entity models which are exposed as services will act as stand-alone models for integrations.
  • PL/SQL methods other than CRUD and State Events in *_API package layer, will not be exposed.

Solution

Code Generation Support for Entity Service APIs (ESA) is enabled by default in the Developer Studio Tool as well as in the Build Environments. CRUD methods get generated for all Entities from 23R1 and onwards unless an entity is disqualified being exposed as Entity Service by using the codegen Property “ExposeEntityAsService = false” in entity models. Refer this link for more details on Entity Services code generation.

Also the Runtime Administration support is available in API Explorer for 23R1 as an additional admin layer to activate Entity Services. Even the code generation is enabled by default, in order for OData Provider to consume an entity as a service, ESA has to be activated by an Admin user in API Explorer. Then only the CRUD operations will be available for OData provider to consume as a service. Since all entities are enabled by default, you will see a large number of Entity projection entries in API explorer in 23R1.

  • API Class is set to "StandardEntity" and in the next column you will see status of the Entity API as YES/NO, it indicate whether the entity API is activated or deactivated.
  • Entity projections are of “Integration” type
  • A new metadata called “SOURCE” is added to both metadata and projection registration. For services based on regular projections this will be set to “projection” and for data entity services this will be set to “entity” (default value is 'projection')
  • The layer is “Base” for these new projections since it is kind of an internal projection.
  • The new service endpoint for the entity service projections is: host/int/ifsapplications/entity/v1/Entity.svc
  • Ex: If Account.entity is the entity, AccountEntity.svc would be the generated service/API name

If there are entities or areas that are obviously bad to expose as Entity Service APIs, those can be disabled using the "ExposeEntityAsService" codegen property in entity model, so neither the CRUD methods in entity API/APY and middle-tier metadata will get generated nor visible in API explore.

API Usage – Product Policy for StandardEntity API class

  • Entity APIs will be visible in API explorer, but requires activation by system administrator before they can be used. Technical specifications (OpenAPI v3, v2) and technical documentation provided.
  • Only allowed usage is for configuration tools within IFS Cloud and for system-2-system integration with other trusted system(s), and should not be used for external end-user interactive access.
  • Intend to provide a list of breaking API changes in conjunction with releases.
  • Defects reported will be assigned priority 3 and addressed in a future release update.
  • Customer is responsible for consequences of inappropriate use of APIs and shall assure that individuals using entity class APIs have sufficient understanding of IFS Cloud to use them appropriately.