Retrieve a business entity schema
The entity-schemas
and graph-schema
endpoints both
return a JSON representation of business entities. The information returned is similar
to what you would find in the swagger and openapi endpoints, but with additional
metadata. (See Viewing API definitions for information on the
swagger and openapi endpoints.)
As a general rule, use graph-schema
if you're consuming a graph,
such as from AppEvents. Use entity-schemas
if you want a schema for
everything in the API, or you want to use one endpoint that works across all
InsuranceSuite applications.
Retrieve an entity schema
The entity-schemas
endpoints return one or more complete product
schemas. They can also be filtered to target specific sets of entities. For more
information on query parameters, see Business entity schema query parameters.
Use the following command to retrieve a JSON-formatted entity schema:
GET /common/v1/entity-schemas
To retrieve the schema for a single entity, use the following command:
GET /common/v1/entity-schemas/{entityId}
For example, you can return the schema for the User entity with the following command:
The schema returned by the entity-schemas/{entityId}
endpoint
returns the schema for the specified entity and other schemas transitively
referenced from that entity. In the preceding example, in the base configuration the
returned entity schema would include User, plus related schemas such as
UserGroupReference and UserRoleReference. However, it won’t return the schemas for
any child entities. Instead it will return a list of children (if any) in the
x-gw-children
property for each entity. (See "Child entities"
in Schema properties usage for more information.)
To retrieve a specific entity along with the complete schema information for all its
children, filter the entity-schemas
endpoint on
rootEntity
:
GET /common/v1/entity-schemas?filter=rootEntity:eq:{entityId}
Filtering on rootEntity
retrieves a more detailed schema than using
the entity-schemas/{entityId}
endpoint by traversing the entity
graph tree and including all the child entities of the specified entity.
Retrieve a graph schema
The graph-schema
endpoint returns a graph schema. A
graph schema is a JSON representation of one or more logical entities and their
children.
Use the following command to retrieve a graph schema:
GET
/job/v1/graph-schema?product={productId}
Note that the product
query parameter is
required. For more information on query parameters, see Business entity schema query parameters.
The response returned by the graph-schema
endpoint is a
JSON Schema Draft-7 document that contains schema definitions for the primary
business object graphs for the application. The schema definitions are similar to
the schema definitions found in the API schemas and entity-schemas
endpoints, but will include additional properties that embed child objects in their
parents. For example, an entity accessed through an endpoint as /entity with a child
accessed as /entity/{entityId}/entityChild would be represented in the graph schema
as an "Entity" definition with an "entityChild" property.
The schema returned in the response can contain multiple logical "graphs."
However, it does not return all entities. For example, Admin entities such as User
are not included in the graph-schema
response. To retrieve all
entities, use the entity-schemas
endpoint.
The following command retrieves a graph schema with entities such as Account, Coverage, Job, and (for a sample PersonalAuto product) PersonalVehicle.
Command
Response