Skip to content

Entity Service APIs

If you are looking for an appropriate API for a System-System integration, Entity Service APIs is the way forward. Entity Service APIs can be used to create new business flows and can easily identify which API to use for different contexts.

Many Standard APIs are tightly coupled to the IFS Cloud Web pages they serve, which makes it difficult to reuse them for other requirements like the ones given below. 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 designed to fulfill specific business scenarios and for integration purposes. The level of composability and discoverability is minimal, making them unsuitable to be reused for new business flows. It is also hard to identify which particular API should be used in each different context.

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

Entity Services will add capabilities to automatically promote our Entity Data Models as REST endpoints, without modelling of a projection. Hence, it addresses both the issues of discoverability and composability. Exposed entity models can be used as an OData service for performing CRUD operations and 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 a 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 – If a Standard API supports a given integration requirement, it can be used. Otherwise, an Entity Service API is to be considered, especially when composing on lower-level API endpoints.

• However, Entity Service APIs should NOT be used for external end-user interactive access.

Goals and Objectives

  • Expose IFS Entity Models as OData services for performing CRUD operations and State Machine transitions.
  • Entity models will be 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 is enabled by default in the Developer Studio Tool as well as in the Build Environments. CRUD methods get generated for all entities for versions 23R1 and above, unless an entity is disqualified from being exposed as an Entity Service by using the codegen Property, “ExposeEntityAsService = false” in entity models. Refer Entity Services code generation for more details.

Also, the Runtime Administration support is available in API Explorer as an additional admin layer to activate Entity Services. Even though 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. Only then 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 the API Explorer.

  • API Class is set to StandardEntity and in the next column you will see status of the Entity API as YES/NO indicating whether the entity API is activated or deactivated.
  • Entity projections are of Integration type.
  • A new metadata called SOURCE is added to both the 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/<EntityModelName>**Entity**.svc. For example, if Account.entity is the entity, AccountEntity.svc would be the generated service/API name.

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

API Usage – Product Policy for StandardEntity API class

  • Entity APIs will be visible in the API explorer, but requires activation by the system administrator before they can be used. Technical specifications (OpenAPI v3, v2) and technical documentation will be 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.
  • A list of breaking API changes will be provided 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.